Multithreaded prefetcher option for newReadChannel

google-cloud-contrib/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java

@@ -31,31 +31,31 @@ public abstract class CloudStorageConfiguration {
   public static final CloudStorageConfiguration DEFAULT = builder().build();
 
   /**
-   * Returns path of current working directory. This defaults to the root directory.
+   * @return path of current working directory. This defaults to the root directory.
    */
   public abstract String workingDirectory();
 
   /**
-   * Returns {@code true} if we <i>shouldn't</i> throw an exception when encountering object names
+   * @return {@code true} if we <i>shouldn't</i> throw an exception when encountering object names
    * containing superfluous slashes, e.g. {@code a//b}.
    */
   public abstract boolean permitEmptyPathComponents();
 
   /**
-   * Returns {@code true} if '/' prefix on absolute object names should be removed before I/O.
+   * @return {@code true} if '/' prefix on absolute object names should be removed before I/O.
    *
    * <p>If you disable this feature, please take into consideration that all paths created from a
    * URI will have the leading slash.
    */
   public abstract boolean stripPrefixSlash();
 
   /**
-   * Returns {@code true} if paths with a trailing slash should be treated as fake directories.
+   * @return {@code true} if paths with a trailing slash should be treated as fake directories.
    */
   public abstract boolean usePseudoDirectories();
 
   /**
-   * Returns block size (in bytes) used when talking to the Google Cloud Storage HTTP server.
+   * @return block size (in bytes) used when talking to the Google Cloud Storage HTTP server.
    */
   public abstract int blockSize();
 
@@ -67,6 +67,8 @@ public abstract class CloudStorageConfiguration {
    * <li>The prefix slash on absolute paths will be removed when converting to an object name.
    * <li>Pseudo-directories are enabled, so any path with a trailing slash is a fake directory.
    * </ul>
+   *
+   * @return builder
    */
   public static Builder builder() {
     return new Builder();
@@ -89,6 +91,8 @@ public static final class Builder {
      * {@link CloudStorageFileSystem} object.
      *
      * @throws IllegalArgumentException if {@code path} is not absolute.
+     * @param path the new current working directory
+     * @return builder
      */
     public Builder workingDirectory(String path) {
       checkArgument(UnixPath.getPath(false, path).isAbsolute(), "not absolute: %s", path);
@@ -99,6 +103,9 @@ public Builder workingDirectory(String path) {
     /**
      * Configures whether or not we should throw an exception when encountering object names
      * containing superfluous slashes, e.g. {@code a//b}.
+     *
+     * @param value whether to permit empty path components (will throw if false)
+     * @return builder
      */
     public Builder permitEmptyPathComponents(boolean value) {
       permitEmptyPathComponents = value;
@@ -110,6 +117,9 @@ public Builder permitEmptyPathComponents(boolean value) {
      *
      * <p>If you disable this feature, please take into consideration that all paths created from a
      * URI will have the leading slash.
+     *
+     * @param value if true, remove the '/' prefix on absolute object names
+     * @return builder
      */
     public Builder stripPrefixSlash(boolean value) {
       stripPrefixSlash = value;
@@ -118,6 +128,9 @@ public Builder stripPrefixSlash(boolean value) {
 
     /**
      * Configures if paths with a trailing slash should be treated as fake directories.
+     *
+     * @param value whether paths with a trailing slash should be treated as fake directories.
+     * @return builder
      */
     public Builder usePseudoDirectories(boolean value) {
       usePseudoDirectories = value;
@@ -128,6 +141,9 @@ public Builder usePseudoDirectories(boolean value) {
      * Sets the block size in bytes that should be used for each HTTP request to the API.
      *
      * <p>The default is {@value CloudStorageFileSystem#BLOCK_SIZE_DEFAULT}.
+     *
+     * @param value block size in bytes that should be used for each HTTP request to the API.
+     * @return builder
      */
     public Builder blockSize(int value) {
       blockSize = value;
@@ -136,6 +152,8 @@ public Builder blockSize(int value) {
 
     /**
      * Creates new instance without destroying builder.
+     *
+     * @return CloudStorageConfiguration with the parameters you asked for.
      */
     public CloudStorageConfiguration build() {
       return new AutoValue_CloudStorageConfiguration(

google-cloud-contrib/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileAttributes.java

@@ -29,49 +29,49 @@
 public interface CloudStorageFileAttributes extends BasicFileAttributes {
 
   /**
-   * Returns HTTP etag hash of object contents.
+   * @return HTTP etag hash of object contents.
    *
    * @see "https://developers.google.com/storage/docs/hashes-etags"
    */
   Optional<String> etag();
 
   /**
-   * Returns mime type (e.g. text/plain), if set.
+   * @return mime type (e.g. text/plain), if set.
    *
    * @see "http://en.wikipedia.org/wiki/Internet_media_type#List_of_common_media_types"
    */
   Optional<String> mimeType();
 
   /**
-   * Returns access control list.
+   * @return access control list.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#acl"
    */
   Optional<List<Acl>> acl();
 
   /**
-   * Returns {@code Cache-Control} HTTP header value, if set.
+   * @return {@code Cache-Control} HTTP header value, if set.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#cachecontrol"
    */
   Optional<String> cacheControl();
 
   /**
-   * Returns {@code Content-Encoding} HTTP header value, if set.
+   * @return {@code Content-Encoding} HTTP header value, if set.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#contentencoding"
    */
   Optional<String> contentEncoding();
 
   /**
-   * Returns {@code Content-Disposition} HTTP header value, if set.
+   * @return {@code Content-Disposition} HTTP header value, if set.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#contentdisposition"
    */
   Optional<String> contentDisposition();
 
   /**
-   * Returns user-specified metadata.
+   * @return user-specified metadata.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#contentdisposition"
    */

google-cloud-contrib/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystem.java

@@ -84,6 +84,8 @@ public static CloudStorageFileSystem forBucket(String bucket) {
   /**
    * Creates new file system instance for {@code bucket}, with customizable settings.
    *
+   * @param bucket the bucket to access
+   * @param config configuration
    * @see #forBucket(String)
    */
   @CheckReturnValue
@@ -107,6 +109,10 @@ public static CloudStorageFileSystem forBucket(String bucket, CloudStorageConfig
    * from using that if possible, for the reasons documented in
    * {@link CloudStorageFileSystemProvider#newFileSystem(URI, java.util.Map)}
    *
+   * @param bucket the bucket to access
+   * @param config configuration
+   * @param storageOptions storage options
+   *
    * @see java.nio.file.FileSystems#getFileSystem(URI)
    */
   @CheckReturnValue
@@ -132,21 +138,24 @@ public CloudStorageFileSystemProvider provider() {
   }
 
   /**
-   * Returns Cloud Storage bucket name being served by this file system.
+   * @return Cloud Storage bucket name being served by this file system.
    */
   public String bucket() {
     return bucket;
   }
 
   /**
-   * Returns configuration object for this file system instance.
+   * @return configuration object for this file system instance.
    */
   public CloudStorageConfiguration config() {
     return config;
   }
 
   /**
    * Converts Cloud Storage object name to a {@link Path} object.
+   *
+   * @param first cloud storage object name
+   * @return Path object
    */
   @Override
   public CloudStoragePath getPath(String first, String... more) {
@@ -168,23 +177,23 @@ public void close() throws IOException {
   }
 
   /**
-   * Returns {@code true}, even if you previously called the {@link #close()} method.
+   * @return {@code true}, even if you previously called the {@link #close()} method.
    */
   @Override
   public boolean isOpen() {
     return true;
   }
 
   /**
-   * Returns {@code false}.
+   * @return {@code false}.
    */
   @Override
   public boolean isReadOnly() {
     return false;
   }
 
   /**
-   * Returns {@value UnixPath#SEPARATOR}.
+   * @return {@value UnixPath#SEPARATOR}.
    */
   @Override
   public String getSeparator() {

google-cloud-contrib/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageFileSystemProvider.java

@@ -121,6 +121,8 @@ protected Path computeNext() {
 
   /**
    * Sets options that are only used by the constructor.
+   *
+   * @param newStorageOptions options that are only used by the constructor
    */
   @VisibleForTesting
   public static void setStorageOptions(StorageOptions newStorageOptions) {
@@ -170,7 +172,7 @@ public CloudStorageFileSystem getFileSystem(URI uri) {
   }
 
   /**
-   * Returns Cloud Storage file system, provided a URI with no path, e.g. {@code gs://bucket}.
+   * @return Cloud Storage file system, provided a URI with no path, e.g. {@code gs://bucket}.
    *
    * @param uri bucket and current working directory, e.g. {@code gs://bucket}
    * @param env map of configuration options, whose keys correspond to the method names of
@@ -226,8 +228,13 @@ public SeekableByteChannel newByteChannel(
   private SeekableByteChannel newReadChannel(Path path, Set<? extends OpenOption> options)
       throws IOException {
     initStorage();
+    // null indicates we shouldn't add a prefetcher
+    SeekableByteChannelPrefetcherOptions prefetcherOptions = null;
+
     for (OpenOption option : options) {
-      if (option instanceof StandardOpenOption) {
+      if (option instanceof SeekableByteChannelPrefetcherOptions) {
+        prefetcherOptions = (SeekableByteChannelPrefetcherOptions)option;
+      } else if (option instanceof StandardOpenOption) {
         switch ((StandardOpenOption) option) {
           case READ:
             // Default behavior.
@@ -255,6 +262,15 @@ private SeekableByteChannel newReadChannel(Path path, Set<? extends OpenOption>
     if (cloudPath.seemsLikeADirectoryAndUsePseudoDirectories()) {
       throw new CloudStoragePseudoDirectoryException(cloudPath);
     }
+    if (prefetcherOptions!=null) {
+      // layer a prefetcher on top, using the provided options
+      List<SeekableByteChannel> chans = new ArrayList<>();
+      for (int i=0; i<prefetcherOptions.extraThreads + prefetcherOptions.prefetchingThreads; i++) {
+        chans.add(CloudStorageReadChannel.create(storage, cloudPath.getBlobId(), 0));
+      }
+      return new SeekableByteChannelPrefetcher(prefetcherOptions, chans);
+    }
+    // normal case
     return CloudStorageReadChannel.create(storage, cloudPath.getBlobId(), 0);
   }
 

google-cloud-contrib/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageOptions.java

@@ -25,13 +25,17 @@ public final class CloudStorageOptions {
 
   /**
    * Sets the mime type header on an object, e.g. {@code "text/plain"}.
+   *
+   * @param mimeType MIME type
+   * @return the corresponding option
    */
   public static CloudStorageOption.OpenCopy withMimeType(String mimeType) {
     return OptionMimeType.create(mimeType);
   }
 
   /**
    * Disables caching on an object. Same as: {@code withCacheControl("no-cache")}.
+   * @return the corresponding option
    */
   public static CloudStorageOption.OpenCopy withoutCaching() {
     return withCacheControl("no-cache");
@@ -41,6 +45,9 @@ public static CloudStorageOption.OpenCopy withoutCaching() {
    * Sets the {@code Cache-Control} HTTP header on an object.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#cachecontrol"
+   *
+   * @param cacheControl Cache-Control HTTP header
+   * @return the corresponding option
    */
   public static CloudStorageOption.OpenCopy withCacheControl(String cacheControl) {
     return OptionCacheControl.create(cacheControl);
@@ -50,6 +57,9 @@ public static CloudStorageOption.OpenCopy withCacheControl(String cacheControl)
    * Sets the {@code Content-Disposition} HTTP header on an object.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#contentdisposition"
+   *
+   * @param contentDisposition Content-Disposition HTTP header
+   * @return the corresponding option
    */
   public static CloudStorageOption.OpenCopy withContentDisposition(String contentDisposition) {
     return OptionContentDisposition.create(contentDisposition);
@@ -59,6 +69,9 @@ public static CloudStorageOption.OpenCopy withContentDisposition(String contentD
    * Sets the {@code Content-Encoding} HTTP header on an object.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#contentencoding"
+   *
+   * @param contentEncoding content encoding
+   * @return the corresponding option
    */
   public static CloudStorageOption.OpenCopy withContentEncoding(String contentEncoding) {
     return OptionContentEncoding.create(contentEncoding);
@@ -68,6 +81,9 @@ public static CloudStorageOption.OpenCopy withContentEncoding(String contentEnco
    * Sets the ACL value on a Cloud Storage object.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#acl"
+   *
+   * @param acl ACL value
+   * @return the corresponding option
    */
   public static CloudStorageOption.OpenCopy withAcl(Acl acl) {
     return OptionAcl.create(acl);
@@ -77,6 +93,10 @@ public static CloudStorageOption.OpenCopy withAcl(Acl acl) {
    * Sets an unmodifiable piece of user metadata on a Cloud Storage object.
    *
    * @see "https://developers.google.com/storage/docs/reference-headers#xgoogmeta"
+   *
+   * @param key metadata key
+   * @param value metadata value
+   * @return the corresponding option
    */
   public static CloudStorageOption.OpenCopy withUserMetadata(String key, String value) {
     return OptionUserMetadata.create(key, value);
@@ -86,6 +106,9 @@ public static CloudStorageOption.OpenCopy withUserMetadata(String key, String va
    * Sets the block size (in bytes) when talking to the Google Cloud Storage server.
    *
    * <p>The default is {@value CloudStorageFileSystem#BLOCK_SIZE_DEFAULT}.
+   *
+   * @param size block size (in bytes)
+   * @return the corresponding option
    */
   public static CloudStorageOption.OpenCopy withBlockSize(int size) {
     return OptionBlockSize.create(size);