Nio javadocs

sdk/storage/azure-storage-blob-nio/README.md

@@ -116,7 +116,7 @@ fallback and retry options available.
 The view of the FileSystem from within an instance of the JVM will be consistent, but the AzureFileSystem makes no 
 guarantees on behavior or state should other processes operate on the same data. The AzureFileSystem will assume that it 
 has exclusive access to the resources stored in Azure Blob Storage and will behave without regard for potential 
-interfering applications
+interfering applications.
 
 Finally, this implementation has currently chosen to always read/write directly to/from Azure Storage without a local 
 cache. Our team has determined that with the tradeoffs of complexity, correctness, safety, performance, debuggability, 
@@ -146,19 +146,20 @@ Create a `FileSystem` using the [`shared key`](#get-credentials) retrieved above
 Note that you can further configure the file system using constants available in `AzureFileSystem`.
 Please see the docs for `AzureFileSystemProvider` for a full explanation of initializing and configuring a filesystem
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L39-L42 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L39-L43 -->
 ```java
 Map<String, Object> config = new HashMap<>();
+String[] stores = {"<your_container_name", "another_container_name"}; // Any iterable is acceptable
 config.put(AzureFileSystem.AZURE_STORAGE_ACCOUNT_KEY, "<your_account_key>");
-config.put(AzureFileSystem.AZURE_STORAGE_FILE_STORES, "<container_names>");
+config.put(AzureFileSystem.AZURE_STORAGE_FILE_STORES, stores);
 FileSystem myFs = FileSystems.newFileSystem(new URI("azb://?account=<your_account_name"), config);
 ```
 
 ### Create a directory
 
 Create a directory using the `Files` api
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L46-L47 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L47-L48 -->
 ```java
 Path dirPath = myFs.getPath("dir");
 Files.createDirectory(dirPath);
@@ -168,7 +169,7 @@ Files.createDirectory(dirPath);
 
 Iterate over a directory using a `DirectoryStream`
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L51-L53 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L52-L54 -->
 ```java
 for (Path p : Files.newDirectoryStream(dirPath)) {
     System.out.println(p.toString());
@@ -179,7 +180,7 @@ for (Path p : Files.newDirectoryStream(dirPath)) {
 
 Read the contents of a file using an `InputStream`. Skipping, marking, and resetting are all supported.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L57-L60 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L58-L61 -->
 ```java
 Path filePath = myFs.getPath("file");
 InputStream is = Files.newInputStream(filePath);
@@ -192,7 +193,7 @@ is.close();
 Write to a file. Only writing whole files is supported. Random IO is not supported. The stream must be closed in order 
 to guarantee that the data is available to be read.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L64-L66 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L65-L67 -->
 ```java
 OutputStream os = Files.newOutputStream(filePath);
 os.write(0);
@@ -201,15 +202,15 @@ os.close();
 
 ### Copy a file
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L70-L71 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L71-L72 -->
 ```java
 Path destinationPath = myFs.getPath("destinationFile");
 Files.copy(filePath, destinationPath, StandardCopyOption.COPY_ATTRIBUTES);
 ```
 
 ### Delete a file
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L75-L75 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L76-L76 -->
 ```java
 Files.delete(filePath);
 ```
@@ -218,7 +219,7 @@ Files.delete(filePath);
 
 Read attributes of a file through the `AzureBlobFileAttributes`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L79-L80 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L80-L81 -->
 ```java
 AzureBlobFileAttributes attr = Files.readAttributes(filePath, AzureBlobFileAttributes.class);
 BlobHttpHeaders headers = attr.blobHttpHeaders();
@@ -228,7 +229,7 @@ Or read attributes dynamically by specifying a string of desired attributes. Thi
 to retrieve any attribute will always retrieve all of them as an atomic bulk operation. You may specify "*" instead of a 
 list of specific attributes to have all attributes returned in the map.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L84-L84 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L85-L85 -->
 ```java
 Map<String, Object> attributes = Files.readAttributes(filePath, "azureBlob:metadata,headers");
 ```
@@ -237,15 +238,15 @@ Map<String, Object> attributes = Files.readAttributes(filePath, "azureBlob:metad
 
 Set attributes of a file through the `AzureBlobFileAttributeView`.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L88-L89 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L89-L90 -->
 ```java
 AzureBlobFileAttributeView view = Files.getFileAttributeView(filePath, AzureBlobFileAttributeView.class);
 view.setMetadata(Collections.EMPTY_MAP);
 ```
 
 Or set an attribute dynamically by specifying the attribute as a string.
 
-<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L93-L93 -->
+<!-- embedme ./src/samples/java/com/azure/storage/blob/nio/ReadmeSamples.java#L94-L94 -->
 ```java
 Files.setAttribute(filePath, "azureBlob:blobHttpHeaders", new BlobHttpHeaders());
 ```
@@ -282,6 +283,7 @@ not be possible or otherwise may conflict with established design goals and ther
 - Hidden files
 - Random writes
 - File locks
+- Read only files or file stores
 - Watches on directory events
 - Support for other Azure Storage services such as ADLS Gen 2 (Datalake) and Azure Files (shares)
 - Token authentication

sdk/storage/azure-storage-blob-nio/src/main/java/com/azure/storage/blob/nio/AzureBasicFileAttributeView.java

@@ -10,14 +10,12 @@
 
 /**
  * Provides support for basic file attributes.
- *
+ * <p>
  * The operations supported by this view and the attributes it reads are a strict subset of
  * {@link AzureBlobFileAttributeView} and has the same network behavior. Therefore, while this type is offered for
  * compliance with the NIO spec, {@link AzureBlobFileAttributeView} is generally preferred.
- *
+ * <p>
  * {@link #setTimes(FileTime, FileTime, FileTime)} is not supported.
- *
- * {@inheritDoc}
  */
 public final class AzureBasicFileAttributeView implements BasicFileAttributeView {
 
@@ -30,16 +28,21 @@ public final class AzureBasicFileAttributeView implements BasicFileAttributeView
     }
 
     /**
-     * Returns {@code "azureBasic"}
-     * {@inheritDoc}
+     * Returns the name of the attribute view: {@code "azureBasic"}
+     *
+     * @return the name of the attribute view: {@code "azureBasic"}
      */
     @Override
     public String name() {
         return NAME;
     }
 
     /**
-     * {@inheritDoc}
+     * Reads the basic file attributes as a bulk operation.
+     * <p>
+     * All file attributes are read as an atomic operation with respect to other file system operations.
+     *
+     * @return {@link AzureBasicFileAttributes}
      */
     @Override
     public AzureBasicFileAttributes readAttributes() throws IOException {
@@ -49,8 +52,11 @@ public AzureBasicFileAttributes readAttributes() throws IOException {
     /**
      * Unsupported.
      *
+     * @param lastModifiedTime the new last modified time, or null to not change the value
+     * @param lastAccessTime the last access time, or null to not change the value
+     * @param createTime the file's create time, or null to not change the value
      * @throws UnsupportedOperationException Operation not supported.
-     * {@inheritDoc}
+     * @throws IOException never
      */
     @Override
     public void setTimes(FileTime lastModifiedTime, FileTime lastAccessTime, FileTime createTime) throws IOException {

sdk/storage/azure-storage-blob-nio/src/main/java/com/azure/storage/blob/nio/AzureBasicFileAttributes.java

@@ -24,9 +24,8 @@
  * {@link AzureBlobFileAttributes} is generally preferred.
  * <p>
  * Some attributes are not supported. Refer to the javadocs on each method for more information.
- * {@inheritDoc}
  */
-public class AzureBasicFileAttributes implements BasicFileAttributes {
+public final class AzureBasicFileAttributes implements BasicFileAttributes {
     private final ClientLogger logger = new ClientLogger(AzureBasicFileAttributes.class);
 
     // For verifying parameters on FileSystemProvider.readAttributes
@@ -62,52 +61,65 @@ public class AzureBasicFileAttributes implements BasicFileAttributes {
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the time of last modification.
+     *
+     * @return the time of last modification.
      */
     @Override
     public FileTime lastModifiedTime() {
         return FileTime.from(properties.getLastModified().toInstant());
     }
 
     /**
-     * Unsupported.
-     * @throws UnsupportedOperationException Operation not supported.
-     * {@inheritDoc}
+     * Returns the time of last modification.
+     * <p>
+     * Last access time is not supported by the blob service. In this case, it is typical for implementations to return
+     * the {@link #lastModifiedTime()}.
+     *
+     * @return the time of last modification.
      */
     @Override
     public FileTime lastAccessTime() {
-        throw new UnsupportedOperationException();
+        return this.lastModifiedTime();
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the creation time. The creation time is the time that the file was created.
+     *
+     * @return The creation time.
      */
     @Override
     public FileTime creationTime() {
         return FileTime.from(properties.getCreationTime().toInstant());
     }
 
     /**
-     * {@inheritDoc}
+     * Tells whether the file is a regular file with opaque content.
+     *
+     * @return whether the file is a regular file.
      */
     @Override
     public boolean isRegularFile() {
         return !this.properties.getMetadata().getOrDefault(AzureResource.DIR_METADATA_MARKER, "false").equals("true");
     }
 
     /**
-     * {@inheritDoc}
+     * Tells whether the file is a directory.
      * <p>
      * Will only return true if the directory is a concrete directory. See
      * {@link AzureFileSystemProvider#createDirectory(Path, FileAttribute[])} for more information on virtual and
      * concrete directories.
+     *
+     * @return whether the file is a directory
      */
     @Override
     public boolean isDirectory() {
         return !this.isRegularFile();
     }
 
     /**
+     * Tells whether the file is a symbolic link.
+     *
      * @return false. Symbolic links are not supported.
      */
     @Override
@@ -116,15 +128,19 @@ public boolean isSymbolicLink() {
     }
 
     /**
-     * @return false
+     * Tells whether the file is something other than a regular file, directory, or symbolic link.
+     *
+     * @return false. No other object types are supported.
      */
     @Override
     public boolean isOther() {
         return false;
     }
 
     /**
-     * {@inheritDoc}
+     * Returns the size of the file (in bytes).
+     *
+     * @return the size of the file
      */
     @Override
     public long size() {
@@ -133,8 +149,8 @@ public long size() {
 
     /**
      * Unsupported.
+     *
      * @throws UnsupportedOperationException Operation not supported.
-     * {@inheritDoc}
      */
     @Override
     public Object fileKey() {

sdk/storage/azure-storage-blob-nio/src/main/java/com/azure/storage/blob/nio/AzureBlobFileAttributeView.java

@@ -70,8 +70,9 @@ static Map<String, Consumer<Object>> setAttributeConsumers(AzureBlobFileAttribut
     }
 
     /**
-     * Returns "azureBlob".
-     * {@inheritDoc}
+     * Returns the name of the attribute view: {@code "azureBlob"}
+     *
+     * @return the name of the attribute view: {@code "azureBlob"}
      */
     @Override
     public String name() {
@@ -80,8 +81,9 @@ public String name() {
 
     /**
      * Reads the file attributes as a bulk operation.
-     *
-     * Gets a fresh copy every time it is called.
+     * <p>
+     * All file attributes are read as an atomic operation with respect to other file system operations. A fresh copy is
+     * retrieved every time this method is called.
      * @return {@link AzureBlobFileAttributes}
      * @throws IOException if an IOException occurs.
      */
@@ -122,7 +124,7 @@ public void setMetadata(Map<String, String> metadata) throws IOException {
 
     /**
      * Sets the {@link AccessTier} on the file.
-     *
+     * <p>
      * See {@link BlobClientBase#setAccessTier(AccessTier)} for more information.
      * @param tier {@link AccessTier}
      * @throws IOException if an IOException occurs.
@@ -138,11 +140,14 @@ public void setTier(AccessTier tier) throws IOException {
     /**
      * Unsupported.
      *
+     * @param lastModifiedTime the new last modified time, or null to not change the value
+     * @param lastAccessTime the last access time, or null to not change the value
+     * @param createTime the file's create time, or null to not change the value
      * @throws UnsupportedOperationException Operation not supported.
-     * {@inheritDoc}
+     * @throws IOException never
      */
     @Override
-    public void setTimes(FileTime fileTime, FileTime fileTime1, FileTime fileTime2) throws IOException {
+    public void setTimes(FileTime lastModifiedTime, FileTime lastAccessTime, FileTime createTime) throws IOException {
         throw new UnsupportedOperationException();
     }
 }