Adding firestore samples (#877)

firestore/README.md

@@ -0,0 +1,47 @@
+# Getting started with Google Cloud Firestore
+[Google Cloud Firestore](https://cloud.google.com/firestore/docs/) is a hosted NoSQL database built
+for automatic scaling, high performance, and ease of application development.
+
+These code samples demonstrate how to access the Google Cloud Firestore API
+using the Beta version of the Firestore Client Libraries.
+
+Note: You cannot use both Cloud Firestore and Cloud Datastore in the
+same project, which might affect apps using App Engine. Try using Cloud Firestore with a different
+project.
+
+## Setup
+- Install [Maven](http://maven.apache.org/).
+- Open the [Firebase Console](https://console.firebase.com) and click **Add project**.
+- Select the option to **Enable Cloud Firestore Beta** for this project.
+- Click **Create Project**.
+  When you create a Cloud Firestore project, it also enables the API in the
+  [Cloud API Manager](https://console.cloud.google.com/projectselector/apis/api/firestore.googleapis.com/overview).
+- [Create a service account](https://cloud.google.com/docs/authentication/)
+ and set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to the
+ credentials JSON file.
+
+## Build
+Build your project:
+
+     mvn clean package
+
+
+## Quickstart
+[Quickstart.java](src/main/java/com/example/java/com/example/firestore/Quicstart.java)
+ demonstrates adding and querying documents in a collection in Firestore.
+You can run the quickstart with:
+
+    mvn exec:java -Dexec.mainClass=com.example.firestore.Quickstart -Dexec.args="your-firestore-project-id"
+
+Note: the default project-id will be used if no argument is provided.
+
+## Snippets
+These [code samples](src/main/java/com/example/firestore/snippets) support
+the Firestore [documentation](https://cloud.google.com/firestore/docs).
+
+## Tests
+Run all tests:
+```
+   mvn clean verify
+```
+

firestore/pom.xml

@@ -0,0 +1,58 @@
+<!--
+  Copyright 2017 Google Inc.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  You may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+<project>
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.example.firestore</groupId>
+  <artifactId>firestore-samples</artifactId>
+  <version>1.0.0</version>
+  <packaging>jar</packaging>
+  <name>Google Cloud Firestore Samples</name>
+  <description>
+    Quick start and code snippets supporting Firestore documentation
+  </description>
+
+  <parent>
+    <artifactId>doc-samples</artifactId>
+    <groupId>com.google.cloud</groupId>
+    <version>1.0.0</version>
+    <relativePath>..</relativePath>
+  </parent>
+
+  <properties>
+    <maven.compiler.target>1.7</maven.compiler.target>
+    <maven.compiler.source>1.7</maven.compiler.source>
+  </properties>
+
+  <dependencies>
+    <!-- Firestore -->
+    <!-- [START fs-maven] -->
+    <dependency>
+      <groupId>com.google.cloud</groupId>
+      <artifactId>google-cloud-firestore</artifactId>
+      <version>0.25.0-beta</version>
+    </dependency>
+    <!-- [END fs-maven] -->
+
+    <!-- Test dependencies -->
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>4.12</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+</project>

firestore/src/main/java/com/example/firestore/Quickstart.java

@@ -0,0 +1,196 @@
+/*
+ * Copyright 2017 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+
+package com.example.firestore;
+
+import com.google.api.core.ApiFuture;
+import com.google.cloud.firestore.DocumentReference;
+import com.google.cloud.firestore.DocumentSnapshot;
+// [START fs_include_dependencies]
+import com.google.cloud.firestore.Firestore;
+import com.google.cloud.firestore.FirestoreOptions;
+// [END fs_include_dependencies]
+import com.google.cloud.firestore.QuerySnapshot;
+import com.google.cloud.firestore.WriteResult;
+import com.google.common.collect.ImmutableMap;
+
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * A simple Quick start application demonstrating how to connect to Firestore
+ * and add and query documents.
+ */
+public class Quickstart {
+
+  private Firestore db;
+
+  /**
+   * Initialize Firestore using default project ID.
+   */
+  public Quickstart() {
+    // [START fs_initialize]
+    Firestore db = FirestoreOptions.getDefaultInstance().getService();
+    // [END fs_initialize]
+    this.db = db;
+  }
+
+  public Quickstart(String projectId) {
+    // [START fs_initialize_project_id]
+    FirestoreOptions firestoreOptions =
+        FirestoreOptions.getDefaultInstance().toBuilder()
+            .setProjectId(projectId)
+            .build();
+    Firestore db = firestoreOptions.getService();
+    // [END fs_initialize_project_id]
+    this.db = db;
+  }
+
+  Firestore getDb() {
+    return db;
+  }
+
+  /**
+   * Add named test documents with fields first, last, middle (optional), born.
+   *
+   * @param docName document name
+   */
+  void addDocument(String docName) throws Exception {
+    switch (docName) {
+      case "alovelace": {
+        // [START fs_add_data_1]
+        DocumentReference docRef = db.collection("users").document("alovelace");
+        // Add document data  with id "alovelace" using a hashmap
+        Map<String, Object> data = new HashMap<>();
+        data.put("first", "Ada");
+        data.put("last", "Lovelace");
+        data.put("born", 1815);
+        //asynchronously write data
+        ApiFuture<WriteResult> result = docRef.set(data);
+        // ...
+        // result.get() blocks on response
+        System.out.println("Update time : " + result.get().getUpdateTime());
+        // [END fs_add_data_1]
+        break;
+      }
+      case "aturing": {
+        // [START fs_add_data_2]
+        DocumentReference docRef = db.collection("users").document("aturing");
+        // Add document data with an additional field ("middle")
+        Map<String, Object> data = new HashMap<>();
+        data.put("first", "Alan");
+        data.put("middle", "Mathison");
+        data.put("last", "Turing");
+        data.put("born", 1912);
+
+        ApiFuture<WriteResult> result = docRef.set(data);
+        System.out.println("Update time : " + result.get().getUpdateTime());
+        // [END fs_add_data_2]
+        break;
+      }
+      case "cbabbage": {
+        DocumentReference docRef = db.collection("users").document("cbabbage");
+        Map<String, Object> data =
+            new ImmutableMap.Builder<String, Object>()
+                .put("first", "Charles")
+                .put("last", "Babbage")
+                .put("born", 1791)
+                .build();
+        ApiFuture<WriteResult> result = docRef.set(data);
+        System.out.println("Update time : " + result.get().getUpdateTime());
+        break;
+      }
+      default:
+    }
+  }
+
+  void runAQuery() throws Exception {
+    // [START fs_add_query]
+    // asynchronously query for all users born before 1900
+    ApiFuture<QuerySnapshot> query =
+        db.collection("users").whereLessThan("born", 1900).get();
+    // ...
+    // query.get() blocks on response
+    QuerySnapshot querySnapshot = query.get();
+    List<DocumentSnapshot> documents = querySnapshot.getDocuments();
+    for (DocumentSnapshot document : documents) {
+      System.out.println("User: " + document.getId());
+      System.out.println("First: " + document.getString("first"));
+      if (document.contains("middle")) {
+        System.out.println("Middle: " + document.getString("middle"));
+      }
+      System.out.println("Last: " + document.getString("last"));
+      System.out.println("Born: " + document.getLong("born"));
+    }
+    // [END fs_add_query]
+  }
+
+  void retrieveAllDocuments() throws Exception {
+    // [START fs_get_all]
+    // asynchronously retrieve all users
+    ApiFuture<QuerySnapshot> query = db.collection("users").get();
+    // ...
+    // query.get() blocks on response
+    QuerySnapshot querySnapshot = query.get();
+    List<DocumentSnapshot> documents = querySnapshot.getDocuments();
+    for (DocumentSnapshot document : documents) {
+      System.out.println("User: " + document.getId());
+      System.out.println("First: " + document.getString("first"));
+      if (document.contains("middle")) {
+        System.out.println("Middle: " + document.getString("middle"));
+      }
+      System.out.println("Last: " + document.getString("last"));
+      System.out.println("Born: " + document.getLong("born"));
+    }
+    // [END fs_get_all]
+  }
+
+  void run() throws Exception {
+    String[] docNames = {"alovelace", "aturing", "cbabbage"};
+
+    // Adding document 1
+    System.out.println("########## Adding document 1 ##########");
+    addDocument(docNames[0]);
+
+    // Adding document 2
+    System.out.println("########## Adding document 2 ##########");
+    addDocument(docNames[1]);
+
+    // Adding document 3
+    System.out.println("########## Adding document 3 ##########");
+    addDocument(docNames[2]);
+
+    // retrieve all users born before 1900
+    System.out.println("########## users born before 1900 ##########");
+    runAQuery();
+
+    // retrieve all users
+    System.out.println("########## All users ##########");
+    retrieveAllDocuments();
+    System.out.println("###################################");
+  }
+
+  /**
+   * A quick start application to get started with Firestore.
+   *
+   * @param args firestore-project-id (optional)
+   */
+  public static void main(String[] args) throws Exception {
+    // default project is will be used if project-id argument is not available
+    String projectId = (args.length == 0) ? null : args[0];
+    Quickstart quickStart = (projectId != null) ? new Quickstart(projectId) : new Quickstart();
+    quickStart.run();
+  }
+}