Merge pull request #47 from aozarov/master

aozarov · aozarov · commit 1f6cefe79f89 · 2015-05-08T13:32:43.000-07:00
storage work in progress
diff --git a/src/main/java/com/google/gcloud/datastore/DatastoreServiceFactory.java b/src/main/java/com/google/gcloud/datastore/DatastoreServiceFactory.java
@@ -17,7 +17,9 @@
 package com.google.gcloud.datastore;
 
 
-
+/**
+ * A base class for DatasoreService factories.
+ */
 public abstract class DatastoreServiceFactory {
 
   private static final DatastoreServiceFactory INSTANCE = new DatastoreServiceFactory() {
diff --git a/src/main/java/com/google/gcloud/examples/DatastoreExample.java b/src/main/java/com/google/gcloud/examples/DatastoreExample.java
@@ -46,7 +46,7 @@
  * <li>compile using maven - {@code mvn compile}</li>
  * <li>run using maven - {@code mvn exec:java
  * -Dexec.mainClass="com.google.gcloud.examples.DatastoreExample"
- * -Dexec.args="projectId [user] [delete|display|add comment]"}</li>
+ * -Dexec.args="[projectId] [user] [delete|display|add comment]"}</li>
  * </ol>
  */
 public class DatastoreExample {
@@ -174,25 +174,23 @@ public static void main(String... args) {
     DatastoreAction action = null;
     DatastoreService datastore = null;
     Key key = null;
-    if (args.length > 0) {
-      String projectId = args[0];
-      // If you want to access a local Datastore running via the gcd sdk, do
-//          DatastoreServiceOptions options = DatastoreServiceOptions.builder()
-//              .projectId(projectId)
-//              .namespace(NAMESPACE)
-//              .host("http://localhost:8080")
-//              .build();
-      DatastoreServiceOptions options = DatastoreServiceOptions.builder()
-          .projectId(projectId)
-          .namespace(NAMESPACE)
-          .build();
-      String name = args.length > 1 ? args[1] : System.getProperty("user.name");
-      datastore = DatastoreServiceFactory.instance().get(options);
-      KeyFactory keyFactory = datastore.newKeyFactory().kind(USER_KIND);
-      key = keyFactory.newKey(name);
-      String actionName = args.length > 2 ? args[2].toLowerCase() : DEFAULT_ACTION;
-      action = ACTIONS.get(actionName);
-    }
+    String projectId = args.length > 0 ? args[0] : null;
+    // If you want to access a local Datastore running via the gcd sdk, do
+    //   DatastoreServiceOptions options = DatastoreServiceOptions.builder()
+    //       .projectId(projectId)
+    //       .namespace(NAMESPACE)
+    //       .host("http://localhost:8080")
+    //       .build();
+    DatastoreServiceOptions options = DatastoreServiceOptions.builder()
+        .projectId(projectId)
+        .namespace(NAMESPACE)
+        .build();
+    String name = args.length > 1 ? args[1] : System.getProperty("user.name");
+    datastore = DatastoreServiceFactory.instance().get(options);
+    KeyFactory keyFactory = datastore.newKeyFactory().kind(USER_KIND);
+    key = keyFactory.newKey(name);
+    String actionName = args.length > 2 ? args[2].toLowerCase() : DEFAULT_ACTION;
+    action = ACTIONS.get(actionName);
     if (action == null) {
       StringBuilder actionAndParams = new StringBuilder();
       for (Map.Entry<String, DatastoreAction> entry : ACTIONS.entrySet()) {
@@ -204,7 +202,7 @@ public static void main(String... args) {
         actionAndParams.append('|');
       }
       actionAndParams.setLength(actionAndParams.length() - 1);
-      System.out.printf("Usage: %s projectId [user] [%s]%n",
+      System.out.printf("Usage: %s [projectId] [user] [%s]%n",
           DatastoreExample.class.getSimpleName(), actionAndParams);
       return;
     }
diff --git a/src/main/java/com/google/gcloud/examples/StorageExample.java b/src/main/java/com/google/gcloud/examples/StorageExample.java
@@ -270,14 +270,15 @@ Tuple<Blob, Path> parse(String... args) {
       if (args.length < 2 || args.length > 3) {
         throw new IllegalArgumentException();
       }
-      Path path = null;
+      Path path;
       if (args.length > 2) {
         path = Paths.get(args[2]);
         if (Files.isDirectory(path)) {
           path = path.resolve(Paths.get(args[1]).getFileName());
         }
+      } else {
+        path = null;
       }
-      String blob = args.length < 3 ? path.getFileName().toString() : args[2];
       return Tuple.of(Blob.of(args[0], args[1]), path);
     }
 
diff --git a/src/main/java/com/google/gcloud/spi/DefaultStorageRpc.java b/src/main/java/com/google/gcloud/spi/DefaultStorageRpc.java
diff --git a/src/main/java/com/google/gcloud/storage/Acl.java b/src/main/java/com/google/gcloud/storage/Acl.java
@@ -21,6 +21,9 @@
 
 import java.io.Serializable;
 
+/**
+ *  Access Control List on for buckets or blobs.
+ */
 public final class Acl implements Serializable {
 
   private static final long serialVersionUID = 6435575339887912222L;
diff --git a/src/main/java/com/google/gcloud/storage/BatchRequest.java b/src/main/java/com/google/gcloud/storage/BatchRequest.java
@@ -43,14 +43,23 @@ public static class Builder {
 
     private Builder() {}
 
+    /**
+     * Delete the given blob.
+     */
     public void delete(Blob blob, BlobSourceOption... options) {
       toDelete.put(blob, options);
     }
 
+    /**
+     * Update the given blob.
+     */
     public void update(Blob blob, BlobTargetOption... options) {
       toUpdate.put(blob, options);
     }
 
+    /**
+     * Retrieve metadata for the given blob.
+     */
     public void get(Blob blob, BlobSourceOption... options) {
       toGet.put(blob, options);
     }
@@ -66,15 +75,15 @@ private BatchRequest(Builder builder) {
     toGet = ImmutableMap.copyOf(builder.toGet);
   }
 
-  public Map<Blob, BlobSourceOption[]> toDelete() {
+  Map<Blob, BlobSourceOption[]> toDelete() {
     return toDelete;
   }
 
-  public Map<Blob, BlobTargetOption[]> toUpdate() {
+  Map<Blob, BlobTargetOption[]> toUpdate() {
     return toUpdate;
   }
 
-  public Map<Blob, BlobSourceOption[]> toGet() {
+  Map<Blob, BlobSourceOption[]> toGet() {
     return toGet;
   }
 
diff --git a/src/main/java/com/google/gcloud/storage/Blob.java b/src/main/java/com/google/gcloud/storage/Blob.java
@@ -33,6 +33,11 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * A Google Storage object.
+ *
+ * @see <a href="https://cloud.google.com/storage/docs/concepts-techniques#concepts">Concepts and Terminology</a>
+ */
 public class Blob implements Serializable {
 
   private static final long serialVersionUID = 2228487739943277159L;
@@ -148,7 +153,7 @@ public Builder cacheControl(String cacheControl) {
     }
 
     public Builder acl(List<Acl> acl) {
-      this.acl = ImmutableList.copyOf(acl);
+      this.acl = acl != null ? ImmutableList.copyOf(acl) : null;
       return this;
     }
 
@@ -188,7 +193,7 @@ public Builder mediaLink(String mediaLink) {
     }
 
     public Builder metadata(Map<String, String> metadata) {
-      this.metadata = ImmutableMap.copyOf(metadata);
+      this.metadata = metadata != null ? ImmutableMap.copyOf(metadata) : null;
       return this;
     }
 
diff --git a/src/main/java/com/google/gcloud/storage/Bucket.java b/src/main/java/com/google/gcloud/storage/Bucket.java
@@ -40,6 +40,11 @@
 import java.io.Serializable;
 import java.util.List;
 
+/**
+ * A Google Storage bucket.
+ *
+ * @see <a href="https://cloud.google.com/storage/docs/concepts-techniques#concepts">Concepts and Terminology</a>
+ */
 public final class Bucket implements Serializable {
 
   private static final long serialVersionUID = -3946094202176916586L;
@@ -431,17 +436,17 @@ Builder metageneration(Long metageneration) {
     }
 
     public Builder cors(Iterable<Cors> cors) {
-      this.cors = ImmutableList.copyOf(cors);
+      this.cors = cors != null ? ImmutableList.copyOf(cors) : null;
       return this;
     }
 
     public Builder acl(Iterable<Acl> acl) {
-      this.acl = ImmutableList.copyOf(acl);
+      this.acl = acl != null ? ImmutableList.copyOf(acl) : null;
       return this;
     }
 
     public Builder defaultAcl(Iterable<Acl> acl) {
-      this.defaultAcl = ImmutableList.copyOf(acl);
+      this.defaultAcl = acl != null ? ImmutableList.copyOf(acl) : null;
       return this;
     }
 
diff --git a/src/main/java/com/google/gcloud/storage/Cors.java b/src/main/java/com/google/gcloud/storage/Cors.java
@@ -30,6 +30,9 @@
 import java.net.URISyntaxException;
 import java.util.List;
 
+/**
+ * Cross-Origin Resource Sharing (CORS) configuration for a bucket.
+ */
 public final class Cors implements Serializable {
 
   private static final long serialVersionUID = -8637770919343335655L;
diff --git a/src/main/java/com/google/gcloud/storage/StorageService.java b/src/main/java/com/google/gcloud/storage/StorageService.java
@@ -30,11 +30,13 @@
 import java.util.List;
 import java.util.Set;
 
+/**
+ * An interface for Google Cloud Storage.
+ *
+ * @see <a href="https://cloud.google.com/storage/docs">Google Cloud Storage</a>
+ */
 public interface StorageService extends Service<StorageServiceOptions> {
 
-  // todo: provide way for construct signed URLs -
-  // https://cloud.google.com/storage/docs/access-control#Signed-URLs
-
   enum PredefinedAcl {
     AUTHENTICATED_READ("authenticatedRead"),
     ALL_AUTHENTICATED_USERS("allAuthenticatedUsers"),
@@ -347,17 +349,26 @@ public static Builder builder() {
     }
   }
 
+
   /**
+   * Create a new bucket.
+   *
+   * @return a complete bucket information.
    * @throws StorageServiceException upon failure
    */
   Bucket create(Bucket bucket, BucketTargetOption... options);
 
   /**
+   * Create a new blob.
+   *
+   * @return a complete blob information.
    * @throws StorageServiceException upon failure
    */
   Blob create(Blob blob, byte[] content, BlobTargetOption... options);
 
   /**
+   * Returns a complete bucket information.
+   *
    * @throws StorageServiceException upon failure
    */
   Bucket get(Bucket bucket, BucketSourceOption... options);
@@ -426,5 +437,4 @@ public static Builder builder() {
    */
   BlobWriteChannel writer(Blob blob, BlobTargetOption... options);
 
-
 }
diff --git a/src/main/java/com/google/gcloud/storage/StorageServiceFactory.java b/src/main/java/com/google/gcloud/storage/StorageServiceFactory.java
@@ -17,7 +17,9 @@
 package com.google.gcloud.storage;
 
 
-
+/**
+ * A base class for StorageService factories.
+ */
 public abstract class StorageServiceFactory {
 
   private static final StorageServiceFactory INSTANCE = new StorageServiceFactory() {
@@ -27,9 +29,15 @@ public StorageService get(StorageServiceOptions options) {
     }
   };
 
+  /**
+   * Returns the default factory instance.
+   */
   public static StorageServiceFactory instance() {
     return INSTANCE;
   }
 
+  /**
+   * Returns a {@code StorageService} for the given options.
+   */
   public abstract StorageService get(StorageServiceOptions options);
 }

Original file line number	Diff line number	Diff line change
`@@ -270,14 +270,15 @@ Tuple<Blob, Path> parse(String... args) {`
`270`	`270`	`if (args.length < 2 \|\| args.length > 3) {`
`271`	`271`	`throw new IllegalArgumentException();`
`272`	`272`	`}`
`273`		`- Path path = null;`
	`273`	`+ Path path;`
`274`	`274`	`if (args.length > 2) {`
`275`	`275`	`path = Paths.get(args[2]);`
`276`	`276`	`if (Files.isDirectory(path)) {`
`277`	`277`	`path = path.resolve(Paths.get(args[1]).getFileName());`
`278`	`278`	`}`
	`279`	`+ } else {`
	`280`	`+ path = null;`
`279`	`281`	`}`
`280`		`- String blob = args.length < 3 ? path.getFileName().toString() : args[2];`
`281`	`282`	`return Tuple.of(Blob.of(args[0], args[1]), path);`
`282`	`283`	`}`
`283`	`284`
Original file line number	Diff line number	Diff line change
`@@ -43,14 +43,23 @@ public static class Builder {`
`43`	`43`
`44`	`44`	`private Builder() {}`
`45`	`45`
	`46`	`+ /**`
	`47`	`+ * Delete the given blob.`
	`48`	`+ */`
`46`	`49`	`public void delete(Blob blob, BlobSourceOption... options) {`
`47`	`50`	`toDelete.put(blob, options);`
`48`	`51`	`}`
`49`	`52`
	`53`	`+ /**`
	`54`	`+ * Update the given blob.`
	`55`	`+ */`
`50`	`56`	`public void update(Blob blob, BlobTargetOption... options) {`
`51`	`57`	`toUpdate.put(blob, options);`
`52`	`58`	`}`
`53`	`59`
	`60`	`+ /**`
	`61`	`+ * Retrieve metadata for the given blob.`
	`62`	`+ */`
`54`	`63`	`public void get(Blob blob, BlobSourceOption... options) {`
`55`	`64`	`toGet.put(blob, options);`
`56`	`65`	`}`
`@@ -66,15 +75,15 @@ private BatchRequest(Builder builder) {`
`66`	`75`	`toGet = ImmutableMap.copyOf(builder.toGet);`
`67`	`76`	`}`
`68`	`77`
`69`		`- public Map<Blob, BlobSourceOption[]> toDelete() {`
	`78`	`+ Map<Blob, BlobSourceOption[]> toDelete() {`
`70`	`79`	`return toDelete;`
`71`	`80`	`}`
`72`	`81`
`73`		`- public Map<Blob, BlobTargetOption[]> toUpdate() {`
	`82`	`+ Map<Blob, BlobTargetOption[]> toUpdate() {`
`74`	`83`	`return toUpdate;`
`75`	`84`	`}`
`76`	`85`
`77`		`- public Map<Blob, BlobSourceOption[]> toGet() {`
	`86`	`+ Map<Blob, BlobSourceOption[]> toGet() {`
`78`	`87`	`return toGet;`
`79`	`88`	`}`
`80`	`89`
Original file line number	Diff line number	Diff line change
`@@ -33,6 +33,11 @@`
`33`	`33`	`import java.util.List;`
`34`	`34`	`import java.util.Map;`
`35`	`35`
	`36`	`+/**`
	`37`	`+ * A Google Storage object.`
	`38`	`+ *`
	`39`	`+ * @see <a href="https://cloud.google.com/storage/docs/concepts-techniques#concepts">Concepts and Terminology</a>`
	`40`	`+ */`
`36`	`41`	`public class Blob implements Serializable {`
`37`	`42`
`38`	`43`	`private static final long serialVersionUID = 2228487739943277159L;`
`@@ -148,7 +153,7 @@ public Builder cacheControl(String cacheControl) {`
`148`	`153`	`}`
`149`	`154`
`150`	`155`	`public Builder acl(List<Acl> acl) {`
`151`		`- this.acl = ImmutableList.copyOf(acl);`
	`156`	`+ this.acl = acl != null ? ImmutableList.copyOf(acl) : null;`
`152`	`157`	`return this;`
`153`	`158`	`}`
`154`	`159`
`@@ -188,7 +193,7 @@ public Builder mediaLink(String mediaLink) {`
`188`	`193`	`}`
`189`	`194`
`190`	`195`	`public Builder metadata(Map<String, String> metadata) {`
`191`		`- this.metadata = ImmutableMap.copyOf(metadata);`
	`196`	`+ this.metadata = metadata != null ? ImmutableMap.copyOf(metadata) : null;`
`192`	`197`	`return this;`
`193`	`198`	`}`
`194`	`199`