Merge pull request #635 from mziccard/refactor-examples

Refactor examples
googleapis · Feb 10, 2016 · 7864a93 · 7864a93
2 parents 307ddf3 + 8c9cb2e
commit 7864a93
Show file tree

Hide file tree

Showing 24 changed files with 885 additions and 382 deletions.
diff --git a/README.md b/README.md
@@ -42,17 +42,17 @@ libraryDependencies += "com.google.gcloud" % "gcloud-java" % "0.1.3"
 Example Applications
 --------------------
 
-- [`BigQueryExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/BigQueryExample.java) - A simple command line interface providing some of Cloud BigQuery's functionality
+- [`BigQueryExample`](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/bigquery/BigQueryExample.java) - A simple command line interface providing some of Cloud BigQuery's functionality
   - Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/BigQueryExample.html).
 - [`Bookshelf`](https://github.com/GoogleCloudPlatform/getting-started-java/tree/master/bookshelf) - An App Engine app that manages a virtual bookshelf.
   - This app uses `gcloud-java` to interface with Cloud Datastore and Cloud Storage. It also uses Cloud SQL, another Google Cloud Platform service.
-- [`DatastoreExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/DatastoreExample.java) - A simple command line interface for the Cloud Datastore
+- [`DatastoreExample`](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/datastore/DatastoreExample.java) - A simple command line interface for the Cloud Datastore
   - Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/DatastoreExample.html).
-- [`ResourceManagerExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/ResourceManagerExample.java) - A simple command line interface providing some of Cloud Resource Manager's functionality
+- [`ResourceManagerExample`](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/resourcemanager/ResourceManagerExample.java) - A simple command line interface providing some of Cloud Resource Manager's functionality
   - Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/ResourceManagerExample.html).
 - [`SparkDemo`](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/master/managed_vms/sparkjava) - An example of using gcloud-java-datastore from within the SparkJava and App Engine Managed VM frameworks.
   - Read about how it works on the example's [README page](https://github.com/GoogleCloudPlatform/java-docs-samples/tree/master/managed_vms/sparkjava#how-does-it-work).
-- [`StorageExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/StorageExample.java) - A simple command line interface providing some of Cloud Storage's functionality
+- [`StorageExample`](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/storage/StorageExample.java) - A simple command line interface providing some of Cloud Storage's functionality
   - Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/StorageExample.html).
 
 Specifying a Project ID
@@ -123,15 +123,15 @@ Google Cloud BigQuery (Alpha)
 
 Here is a code snippet showing a simple usage example from within Compute/App Engine. Note that you
 must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
+Complete source code can be found at
+[CreateTableAndLoadData.java](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/bigquery/snippets/CreateTableAndLoadData.java).
 
 ```java
 import com.google.gcloud.bigquery.BigQuery;
 import com.google.gcloud.bigquery.BigQueryOptions;
 import com.google.gcloud.bigquery.Field;
+import com.google.gcloud.bigquery.FormatOptions;
 import com.google.gcloud.bigquery.Job;
-import com.google.gcloud.bigquery.JobStatus;
-import com.google.gcloud.bigquery.JobInfo;
-import com.google.gcloud.bigquery.LoadJobConfiguration;
 import com.google.gcloud.bigquery.Schema;
 import com.google.gcloud.bigquery.StandardTableDefinition;
 import com.google.gcloud.bigquery.Table;
@@ -145,19 +145,17 @@ if (table == null) {
   System.out.println("Creating table " + tableId);
   Field integerField = Field.of("fieldName", Field.Type.integer());
   Schema schema = Schema.of(integerField);
-  bigquery.create(TableInfo.of(tableId, StandardTableDefinition.of(schema)));
+  table = bigquery.create(TableInfo.of(tableId, StandardTableDefinition.of(schema)));
+}
+System.out.println("Loading data into table " + tableId);
+Job loadJob = table.load(FormatOptions.csv(), "gs://bucket/path");
+while (!loadJob.isDone()) {
+  Thread.sleep(1000L);
+}
+if (loadJob.status().error() != null) {
+  System.out.println("Job completed with errors");
 } else {
-  System.out.println("Loading data into table " + tableId);
-  LoadJobConfiguration configuration = LoadJobConfiguration.of(tableId, "gs://bucket/path");
-  Job loadJob = bigquery.create(JobInfo.of(configuration));
-  while (!loadJob.isDone()) {
-    Thread.sleep(1000L);
-  }
-  if (loadJob.status().error() != null) {
-    System.out.println("Job completed with errors");
-  } else {
-    System.out.println("Job succeeded");
-  }
+  System.out.println("Job succeeded");
 }
 ```
 
@@ -171,8 +169,32 @@ Google Cloud Datastore
 
 #### Preview
 
-Here is a code snippet showing a simple usage example from within Compute/App Engine.  Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
+Here are two code snippets showing simple usage examples from within Compute/App Engine. Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
+
+The first snippet shows how to create a Datastore entity. Complete source code can be found at
+[CreateEntity.java](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/datastore/snippets/CreateEntity.java).
+
+```java
+import com.google.gcloud.datastore.Datastore;
+import com.google.gcloud.datastore.DatastoreOptions;
+import com.google.gcloud.datastore.DateTime;
+import com.google.gcloud.datastore.Entity;
+import com.google.gcloud.datastore.Key;
+import com.google.gcloud.datastore.KeyFactory;
 
+Datastore datastore = DatastoreOptions.defaultInstance().service();
+KeyFactory keyFactory = datastore.newKeyFactory().kind("keyKind");
+Key key = keyFactory.newKey("keyName");
+Entity entity = Entity.builder(key)
+    .set("name", "John Doe")
+    .set("age", 30)
+    .set("access_time", DateTime.now())
+    .build();
+datastore.put(entity);
+```
+The second snippet shows how to update a Datastore entity if it exists. Complete source code can be
+found at
+[UpdateEntity.java](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/datastore/snippets/UpdateEntity.java).
 ```java
 import com.google.gcloud.datastore.Datastore;
 import com.google.gcloud.datastore.DatastoreOptions;
@@ -182,17 +204,10 @@ import com.google.gcloud.datastore.Key;
 import com.google.gcloud.datastore.KeyFactory;
 
 Datastore datastore = DatastoreOptions.defaultInstance().service();
-KeyFactory keyFactory = datastore.newKeyFactory().kind(KIND);
-Key key = keyFactory.newKey(keyName);
+KeyFactory keyFactory = datastore.newKeyFactory().kind("keyKind");
+Key key = keyFactory.newKey("keyName");
 Entity entity = datastore.get(key);
-if (entity == null) {
-  entity = Entity.builder(key)
-      .set("name", "John Do")
-      .set("age", 30)
-      .set("access_time", DateTime.now())
-      .build();
-  datastore.put(entity);
-} else {
+if (entity != null) {
   System.out.println("Updating access_time for " + entity.getString("name"));
   entity = Entity.builder(entity)
       .set("access_time", DateTime.now())
@@ -210,7 +225,8 @@ Google Cloud Resource Manager (Alpha)
 #### Preview
 
 Here is a code snippet showing a simple usage example. Note that you must supply Google SDK credentials for this service, not other forms of authentication listed in the [Authentication section](#authentication).
-
+Complete source code can be found at
+[UpdateAndListProjects.java](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/resourcemanager/snippets/UpdateAndListProjects.java).
 ```java
 import com.google.gcloud.resourcemanager.Project;
 import com.google.gcloud.resourcemanager.ResourceManager;
@@ -219,14 +235,15 @@ import com.google.gcloud.resourcemanager.ResourceManagerOptions;
 import java.util.Iterator;
 
 ResourceManager resourceManager = ResourceManagerOptions.defaultInstance().service();
-Project myProject = resourceManager.get("some-project-id"); // Use an existing project's ID
-Project newProject = myProject.toBuilder()
-    .addLabel("launch-status", "in-development")
-    .build()
-    .replace();
-System.out.println("Updated the labels of project " + newProject.projectId()
-    + " to be " + newProject.labels());
-// List all the projects you have permission to view.
+Project project = resourceManager.get("some-project-id"); // Use an existing project's ID
+if (project != null) {
+  Project newProject = project.toBuilder()
+      .addLabel("launch-status", "in-development")
+      .build()
+      .replace();
+  System.out.println("Updated the labels of project " + newProject.projectId()
+      + " to be " + newProject.labels());
+}
 Iterator<Project> projectIterator = resourceManager.list().iterateAll();
 System.out.println("Projects I can view:");
 while (projectIterator.hasNext()) {
@@ -244,13 +261,32 @@ Google Cloud Storage
 
 #### Preview
 
-Here is a code snippet showing a simple usage example from within Compute/App Engine.  Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
+Here are two code snippets showing simple usage examples from within Compute/App Engine.  Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere.
+
+The first snippet shows how to create a Storage blob. Complete source code can be found at
+[CreateBlob.java](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/storage/snippets/CreateBlob.java).
 
 ```java
 import static java.nio.charset.StandardCharsets.UTF_8;
 
 import com.google.gcloud.storage.Blob;
+import com.google.gcloud.storage.BlobId;
 import com.google.gcloud.storage.BlobInfo;
+import com.google.gcloud.storage.Storage;
+import com.google.gcloud.storage.StorageOptions;
+
+Storage storage = StorageOptions.defaultInstance().service();
+BlobId blobId = BlobId.of("bucket", "blob_name");
+BlobInfo blobInfo = BlobInfo.builder(blobId).contentType("text/plain").build();
+Blob blob = storage.create(blobInfo, "Hello, Cloud Storage!".getBytes(UTF_8));
+```
+The second snippet shows how to update a Storage blob if it exists. Complete source code can be
+found at
+[UpdateBlob.java](./gcloud-java-examples/src/main/java/com/google/gcloud/examples/storage/snippets/UpdateBlob.java).
+```java
+import static java.nio.charset.StandardCharsets.UTF_8;
+
+import com.google.gcloud.storage.Blob;
 import com.google.gcloud.storage.BlobId;
 import com.google.gcloud.storage.Storage;
 import com.google.gcloud.storage.StorageOptions;
@@ -261,11 +297,7 @@ import java.nio.channels.WritableByteChannel;
 Storage storage = StorageOptions.defaultInstance().service();
 BlobId blobId = BlobId.of("bucket", "blob_name");
 Blob blob = storage.get(blobId);
-if (blob == null) {
-  BlobInfo blobInfo = BlobInfo.builder(blobId).contentType("text/plain").build();
-  storage.create(blobInfo, "Hello, Cloud Storage!".getBytes(UTF_8));
-} else {
-  System.out.println("Updating content for " + blobId.name());
+if (blob != null) {
   byte[] prevContent = blob.content();
   System.out.println(new String(prevContent, UTF_8));
   WritableByteChannel channel = blob.writer();

diff --git a/gcloud-java-bigquery/README.md b/gcloud-java-bigquery/README.md
@@ -34,7 +34,7 @@ libraryDependencies += "com.google.gcloud" % "gcloud-java-bigquery" % "0.1.3"
 
 Example Application
 -------------------
-- [`BigQueryExample`](https://github.com/GoogleCloudPlatform/gcloud-java/blob/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/BigQueryExample.java) - A simple command line interface providing some of Cloud BigQuery's functionality.
+- [`BigQueryExample`](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/bigquery/BigQueryExample.java) - A simple command line interface providing some of Cloud BigQuery's functionality.
 Read more about using this application on the [`gcloud-java-examples` docs page](http://googlecloudplatform.github.io/gcloud-java/apidocs/?com/google/gcloud/examples/BigQueryExample.html).
 
 Authentication
@@ -200,91 +200,13 @@ while (rowIterator.hasNext()) {
 ```
 #### Complete source code
 
-Here we put together all the code shown above into one program. This program assumes that you are
-running on Compute Engine or from your own desktop. To run this example on App Engine, simply move
+In
+[InsertDataAndQueryTable.java](../gcloud-java-examples/src/main/java/com/google/gcloud/examples/bigquery/snippets/InsertDataAndQueryTable.java)
+we put together all the code shown above into one program. The program assumes that you are
+running on Compute Engine or from your own desktop. To run the example on App Engine, simply move
 the code from the main method to your application's servlet class and change the print statements to
 display on your webpage.
 
-```java
-import com.google.gcloud.bigquery.BigQuery;
-import com.google.gcloud.bigquery.BigQueryOptions;
-import com.google.gcloud.bigquery.DatasetInfo;
-import com.google.gcloud.bigquery.Field;
-import com.google.gcloud.bigquery.FieldValue;
-import com.google.gcloud.bigquery.InsertAllRequest;
-import com.google.gcloud.bigquery.InsertAllResponse;
-import com.google.gcloud.bigquery.QueryRequest;
-import com.google.gcloud.bigquery.QueryResponse;
-import com.google.gcloud.bigquery.Schema;
-import com.google.gcloud.bigquery.StandardTableDefinition;
-import com.google.gcloud.bigquery.Table;
-import com.google.gcloud.bigquery.TableId;
-import com.google.gcloud.bigquery.TableInfo;
-
-import java.util.HashMap;
-import java.util.Iterator;
-import java.util.List;
-import java.util.Map;
-
-public class GcloudBigQueryExample {
-
-  public static void main(String[] args) throws InterruptedException {
-
-    // Create a service instance
-    BigQuery bigquery = BigQueryOptions.defaultInstance().service();
-
-    // Create a dataset
-    String datasetId = "my_dataset_id";
-    bigquery.create(DatasetInfo.builder(datasetId).build());
-
-    TableId tableId = TableId.of(datasetId, "my_table_id");
-    // Table field definition
-    Field stringField = Field.of("StringField", Field.Type.string());
-    // Table schema definition
-    Schema schema = Schema.of(stringField);
-    // Create a table
-    StandardTableDefinition tableDefinition = StandardTableDefinition.of(schema);
-    Table createdTable = bigquery.create(TableInfo.of(tableId, tableDefinition));
-
-    // Define rows to insert
-    Map<String, Object> firstRow = new HashMap<>();
-    Map<String, Object> secondRow = new HashMap<>();
-    firstRow.put("StringField", "value1");
-    secondRow.put("StringField", "value2");
-    // Create an insert request
-    InsertAllRequest insertRequest = InsertAllRequest.builder(tableId)
-        .addRow(firstRow)
-        .addRow(secondRow)
-        .build();
-    // Insert rows
-    InsertAllResponse insertResponse = bigquery.insertAll(insertRequest);
-    // Check if errors occurred
-    if (insertResponse.hasErrors()) {
-      System.out.println("Errors occurred while inserting rows");
-    }
-
-    // Create a query request
-    QueryRequest queryRequest =
-        QueryRequest.builder("SELECT * FROM my_dataset_id.my_table_id")
-            .maxWaitTime(60000L)
-            .maxResults(1000L)
-            .build();
-    // Request query to be executed and wait for results
-    QueryResponse queryResponse = bigquery.query(queryRequest);
-    while (!queryResponse.jobCompleted()) {
-      Thread.sleep(1000L);
-      queryResponse = bigquery.getQueryResults(queryResponse.jobId());
-    }
-    // Read rows
-    Iterator<List<FieldValue>> rowIterator = queryResponse.result().iterateAll();
-    System.out.println("Table rows:");
-    while (rowIterator.hasNext()) {
-      System.out.println(rowIterator.next());
-    }
-  }
-}
-```
-
 Troubleshooting
 ---------------
 

diff --git a/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/package-info.java b/gcloud-java-bigquery/src/main/java/com/google/gcloud/bigquery/package-info.java
@@ -17,7 +17,10 @@
 /**
  * A client to Google Cloud BigQuery.
  *
- * <p>A simple usage example:
+ * <p>A simple usage example showing how to create a table if it does not exist and load data into
+ * it. For the complete source code see
+ * <a href="https://github.com/GoogleCloudPlatform/gcloud-java/tree/master/gcloud-java-examples/src/main/java/com/google/gcloud/examples/bigquery/snippets/CreateTableAndLoadData.java">
+ * CreateTableAndLoadData.java</a>.
  * <pre> {@code
  * BigQuery bigquery = BigQueryOptions.defaultInstance().service();
  * TableId tableId = TableId.of("dataset", "table");
@@ -26,19 +29,17 @@
  *   System.out.println("Creating table " + tableId);
  *   Field integerField = Field.of("fieldName", Field.Type.integer());
  *   Schema schema = Schema.of(integerField);
- *   bigquery.create(TableInfo.of(tableId, StandardTableDefinition.of(schema)));
+ *   table = bigquery.create(TableInfo.of(tableId, StandardTableDefinition.of(schema)));
+ * }
+ * System.out.println("Loading data into table " + tableId);
+ * Job loadJob = table.load(FormatOptions.csv(), "gs://bucket/path");
+ * while (!loadJob.isDone()) {
+ *   Thread.sleep(1000L);
+ * }
+ * if (loadJob.status().error() != null) {
+ *   System.out.println("Job completed with errors");
  * } else {
- *   System.out.println("Loading data into table " + tableId);
- *   LoadJobConfiguration configuration = LoadJobConfiguration.of(tableId, "gs://bucket/path");
- *   Job loadJob = bigquery.create(JobInfo.of(configuration));
- *   while (!loadJob.isDone()) {
- *     Thread.sleep(1000L);
- *   }
- *   if (loadJob.status().error() != null) {
- *     System.out.println("Job completed with errors");
- *   } else {
- *     System.out.println("Job succeeded");
- *   }
+ *   System.out.println("Job succeeded");
  * }}</pre>
  *
  * @see <a href="https://cloud.google.com/bigquery/">Google Cloud BigQuery</a>