docs: Update documentation to be clearer on pseudo-directory pitfalls (…

…#980)
googleapis · Aug 9, 2022 · 5f6ac74 · 5f6ac74
1 parent 31dd30d
commit 5f6ac74
Show file tree

Hide file tree

Showing 3 changed files with 8 additions and 5 deletions.
diff --git a/.readme-partials.yaml b/.readme-partials.yaml
@@ -72,8 +72,9 @@ custom_content: |
   always be assumed to exist, without performing any I/O. Paths without the trailing
   slash will result in an I/O operation to check a file is present in that "directory".
   This allows you to do path manipulation in the same manner as you would with the normal UNIX file
-  system implementation. You can disable this feature with
-  `CloudStorageConfiguration.usePseudoDirectories()`.
+  system implementation. Using this feature with buckets or "directory" paths that do not exist
+  is not recommended, as at the time I/O is performed the failure may not be handled gracefully.
+  You can disable this feature with `CloudStorageConfiguration.usePseudoDirectories()`.
 
   #### Complete source code
 

diff --git a/README.md b/README.md
@@ -174,8 +174,9 @@ path that includes a trailing slash, will be considered a directory. It will
 always be assumed to exist, without performing any I/O. Paths without the trailing
 slash will result in an I/O operation to check a file is present in that "directory".
 This allows you to do path manipulation in the same manner as you would with the normal UNIX file
-system implementation. You can disable this feature with
-`CloudStorageConfiguration.usePseudoDirectories()`.
+system implementation. Using this feature with buckets or "directory" paths that do not exist
+is not recommended, as at the time I/O is performed the failure may not be handled gracefully.
+You can disable this feature with `CloudStorageConfiguration.usePseudoDirectories()`.
 
 #### Complete source code
 

diff --git a/...oud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java b/...oud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java
@@ -56,7 +56,8 @@ public abstract class CloudStorageConfiguration {
    * directories.
    *
    * <p>With this feature, if file "foo/bar.txt" exists then both "foo" and "foo/" will be treated
-   * as if they were existing directories.
+   * as if they were existing directories. On path construction no I/O will be performed, bucket and
+   * "directory" will treated as if they exist.
    */
   public abstract boolean usePseudoDirectories();