[BUG] Misleading NIO URI format documentation

[ejschoen]

Describe the bug

Not really a bug. More a documentation issue, although some additional validation of azb: URI's might help.

The README for NIO documents the URI format as azb://?endpoint=storage-account-name.blob.core.windows.net. It's very easy to think you should create a URI of the form azb://container-name:/path/to/file?endpoint=... This is technically wrong because the container name is in the host name spot and not the first element of the path. However, this works, but only if the file being referenced is in the first container in the list of containers passed to the newFileSystem call when the Azure file system is initialized. The file system will happily create azb://second-container-name:/path/to/another/file?endpoint=... as a path, but that path won't work. It only works if the URI is of the form azb:/second-container-name:/path/to/another/file?endpoint=...

Code Snippet
Add the code snippet that causes the issue.

                    StorageSharedKeyCredential creds = new StorageSharedKeyCredential(keyconfig.get("accountname"),
                                                                                      keyconfig.get("accountkey"));
                    HashMap config = new HashMap();
                    config.put(AzureFileSystem.AZURE_STORAGE_SHARED_KEY_CREDENTIAL, creds);
                    config.put(AzureFileSystem.AZURE_STORAGE_FILE_STORES, azure_containers);
                    FileSystems.newFileSystem(new URI(String.format("azb://?endpoint=%s", azure_endpoint)), 

where azure_containers is something like `"container1,container2"

Then:

path1 = Paths.get(new URI("azb://container1:/path/to/existing-file-in-container1"))
path1.exists() => true

but

path2 = Paths.get(new URI("azb://container2:/path/to/existing-file-in-container2"))
path2.exists() => false

whereas:

path2a = Paths.get(new URI("azb:/container2:/path/to/existing-file-in-container2"))
path2a.exists() => true

Expected behavior
Naively reading the docs for NIO, I'd expect both .exists tests to return true. If I use a single slash after the scheme, it works as expected, but the docs example shows 2 slashes. It does say that the container name has to be the first element of the URI path, but that's a little bit subtle. Some warning that double slashes after the azb: scheme are not needed, and could be harmful would be helpful.

Setup (please complete the following information):

• OS: Linux
• IDE: None
• Library/Libraries: azure-storage-blob-nio
• Java version: [e.g. 8] 8
• App Server/Environment: Clojure
• Frameworks: [None

I

[github-actions]

@ibrahimrabab @ibrandes @seanmcc-msft

[github-actions]

Thank you for your feedback. Tagging and routing to the team member best able to assist.

[ibrandes]

Thanks for filing this issue @ejschoen, could you provide a runnable code snippet so we can verify this behavior with the container path creations?

[ejschoen]

I did provide a code snippet in my submission above. Maybe I misunderstood what you need--is there a reference to what you expect for code snippets somewhere? Do I need to set up a couple of publicly readable storage containers, or do you maintain some that I can assume exist in a snippet?

[ibrahimrabab]

Hi @ejschoen
We tried to reproduce the issue using what you gave us but we were unable to do so since the snippet you provided did not have a Path.exist() method. How are you checking the existence of the path? Can you provide us a working sample for us to directly run and reproduce?
Thanks!

[ejschoen]

Apologies. Transcription error while converting code from Clojure to Java. It should have been Files.exists(path1), etc.