Merge pull request #47 from aozarov/master

storage work in progress

Author: aozarov

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() {

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;
     }

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);
     }
 

src/main/java/com/google/gcloud/spi/DefaultStorageRpc.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;

src/main/java/com/google/gcloud/storage/Acl.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;
   }
 

src/main/java/com/google/gcloud/storage/BatchRequest.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;
     }
 

src/main/java/com/google/gcloud/storage/Blob.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;
     }
 

src/main/java/com/google/gcloud/storage/Bucket.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;

src/main/java/com/google/gcloud/storage/Cors.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);
 
-
 }

src/main/java/com/google/gcloud/storage/StorageService.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);
 }