From 5f6ac74cc50c819b5871a1a1d0b86e865801caec Mon Sep 17 00:00:00 2001 From: Sydney Munro <97561403+sydney-munro@users.noreply.github.com> Date: Tue, 9 Aug 2022 14:41:00 -0700 Subject: [PATCH] docs: Update documentation to be clearer on pseudo-directory pitfalls (#980) --- .readme-partials.yaml | 5 +++-- README.md | 5 +++-- .../cloud/storage/contrib/nio/CloudStorageConfiguration.java | 3 ++- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index ab46aaa3..b8abc6bf 100644 --- 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 index dd480554..e8021e24 100644 --- 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/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java b/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java index 3ed6d746..216147a2 100644 --- a/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java +++ b/google-cloud-nio/src/main/java/com/google/cloud/storage/contrib/nio/CloudStorageConfiguration.java @@ -56,7 +56,8 @@ public abstract class CloudStorageConfiguration { * directories. * *

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