FileClient (Azure SDK for Java Reference Documentation)

java.lang.Object
- com.azure.storage.file.FileClient

```
public class FileClient
extends Object
```
This class provides a client that contains all the operations for interacting files under Azure Storage File Service. Operations allowed by the client are creating, uploading, copying, listing, downloading, and deleting files.
Instantiating a synchronous File Client
```
FileClient client = new FileClientBuilder()
    .connectionString("${connectionString}")
    .endpoint("${endpoint}")
    .buildFileClient();
```
View this for additional ways to construct the client.
See Also:

FileClientBuilder, FileAsyncClient, SharedKeyCredential

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`abortCopy(String copyId)` Aborts a pending Copy File operation, and leaves a destination file with zero length and full metadata.
`Response<Void>`	`abortCopyWithResponse(String copyId, Duration timeout, Context context)` Aborts a pending Copy File operation, and leaves a destination file with zero length and full metadata.
`FileUploadInfo`	`clearRange(long length)` Clears a range of bytes to specific of a file in storage file service.
`Response<FileUploadInfo>`	`clearRangeWithResponse(long length, long offset, Duration timeout, Context context)` Clears a range of bytes to specific of a file in storage file service.
`FileInfo`	`create(long maxSize)` Creates a file in the storage account and returns a response of `FileInfo` to interact with it.
`Response<FileInfo>`	`createWithResponse(long maxSize, FileHTTPHeaders httpHeaders, FileSmbProperties smbProperties, String filePermission, Map<String,String> metadata, Duration timeout, Context context)` Creates a file in the storage account and returns a response of FileInfo to interact with it.
`void`	`delete()` Deletes the file associate with the client.
`Response<Void>`	`deleteWithResponse(Duration timeout, Context context)` Deletes the file associate with the client.
`FileProperties`	`downloadToFile(String downloadFilePath)` Downloads a file from the system, including its metadata and properties into a file specified by the path.
`Response<FileProperties>`	`downloadToFileWithResponse(String downloadFilePath, FileRange range, Duration timeout, Context context)` Downloads a file from the system, including its metadata and properties into a file specified by the path.
`FileDownloadInfo`	`downloadWithProperties()` Downloads a file from the system, including its metadata and properties
`Response<FileDownloadInfo>`	`downloadWithPropertiesWithResponse(FileRange range, Boolean rangeGetContentMD5, Duration timeout, Context context)` Downloads a file from the system, including its metadata and properties
`PagedIterable<Integer>`	`forceCloseHandles(String handleId, Duration timeout, Context context)` Closes a handle or handles opened on a file at the service.
`String`	`getAccountName()` Get associated account name.
`StorageFileOutputStream`	`getFileOutputStream()` Creates and opens an output stream to write data to the file.
`StorageFileOutputStream`	`getFileOutputStream(long offset)` Creates and opens an output stream to write data to the file.
`String`	`getFilePath()` Get file path of the client.
`String`	`getFileUrl()` Get the url of the storage file client.
`FileProperties`	`getProperties()` Retrieves the properties of the storage account's file.
`Response<FileProperties>`	`getPropertiesWithResponse(Duration timeout, Context context)` Retrieves the properties of the storage account's file.
`String`	`getShareName()` Get the share name of file client.
`String`	`getShareSnapshotId()` Get snapshot id which attached to `FileClient`.
`PagedIterable<HandleItem>`	`listHandles()` List of open handles on a file.
`PagedIterable<HandleItem>`	`listHandles(Integer maxResults, Duration timeout, Context context)` List of open handles on a file.
`PagedIterable<FileRange>`	`listRanges()` List of valid ranges for a file.
`PagedIterable<FileRange>`	`listRanges(FileRange range, Duration timeout, Context context)` List of valid ranges for a file.
`StorageFileInputStream`	`openInputStream()` Opens a file input stream to download the file.
`StorageFileInputStream`	`openInputStream(FileRange range)` Opens a file input stream to download the specified range of the file.
`FileMetadataInfo`	`setMetadata(Map<String,String> metadata)` Sets the user-defined metadata to associate to the file.
`Response<FileMetadataInfo>`	`setMetadataWithResponse(Map<String,String> metadata, Duration timeout, Context context)` Sets the user-defined metadata to associate to the file.
`FileInfo`	`setProperties(long newFileSize, FileHTTPHeaders httpHeaders, FileSmbProperties smbProperties, String filePermission)` Sets the user-defined httpHeaders to associate to the file.
`Response<FileInfo>`	`setPropertiesWithResponse(long newFileSize, FileHTTPHeaders httpHeaders, FileSmbProperties smbProperties, String filePermission, Duration timeout, Context context)` Sets the user-defined httpHeaders to associate to the file.
`FileCopyInfo`	`startCopy(String sourceUrl, Map<String,String> metadata)` Copies a blob or file to a destination file within the storage account.
`Response<FileCopyInfo>`	`startCopyWithResponse(String sourceUrl, Map<String,String> metadata, Duration timeout, Context context)` Copies a blob or file to a destination file within the storage account.
`FileUploadInfo`	`upload(ByteBuffer data, long length)` Uploads a range of bytes to the beginning of a file in storage file service.
`void`	`uploadFromFile(String uploadFilePath)` Uploads file to storage file service.
`FileUploadRangeFromUrlInfo`	`uploadRangeFromUrl(long length, long destinationOffset, long sourceOffset, URI sourceURI)` Uploads a range of bytes from one file to another file.
`Response<FileUploadRangeFromUrlInfo>`	`uploadRangeFromUrlWithResponse(long length, long destinationOffset, long sourceOffset, URI sourceURI, Duration timeout, Context context)` Uploads a range of bytes from one file to another file.
`Response<FileUploadInfo>`	`uploadWithResponse(ByteBuffer data, long length, Duration timeout, Context context)` Uploads a range of bytes to the beginning of a file in storage file service.
`Response<FileUploadInfo>`	`uploadWithResponse(ByteBuffer data, long length, long offset, Duration timeout, Context context)` Uploads a range of bytes to specific of a file in storage file service.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getFileUrl
```
public String getFileUrl()
```
    Get the url of the storage file client.
    
    Returns:
    
    the URL of the storage file client.
  - openInputStream
```
public final StorageFileInputStream openInputStream()
```
    Opens a file input stream to download the file.
    
    Returns:
    
    An InputStream object that represents the stream to use for reading from the file.
    
    Throws:
    
    StorageException - If a storage service error occurred.
  - openInputStream
```
public final StorageFileInputStream openInputStream(FileRange range)
```
    Opens a file input stream to download the specified range of the file.
    
    Parameters:
    
    range - FileRange
    
    Returns:
    
    An InputStream object that represents the stream to use for reading from the file.
    
    Throws:
    
    StorageException - If a storage service error occurred.
  - getFileOutputStream
```
public final StorageFileOutputStream getFileOutputStream()
```
    Creates and opens an output stream to write data to the file. If the file already exists on the service, it will be overwritten.
    
    Returns:
    
    A StorageFileOutputStream object used to write data to the file.
    
    Throws:
    
    StorageException - If a storage service error occurred.
  - getFileOutputStream
```
public final StorageFileOutputStream getFileOutputStream(long offset)
```
    Creates and opens an output stream to write data to the file. If the file already exists on the service, it will be overwritten.
    
    Parameters:
    
    offset - Optional starting point of the upload range. It will start from the beginning if it is null
    
    Returns:
    
    A StorageFileOutputStream object used to write data to the file.
    
    Throws:
    
    StorageException - If a storage service error occurred.
  - create
```
public FileInfo create(long maxSize)
```
    Creates a file in the storage account and returns a response of FileInfo to interact with it.
    Code Samples
    
    Create the file with length of 1024 bytes, some headers and metadata.
```
FileInfo response = fileClient.create(1024);
System.out.println("Complete creating the file.");
```
    For more information, see the Azure Docs.
    Parameters:
    
    maxSize - The maximum size in bytes for the file, up to 1 TiB.
    
    Returns:
    
    The file info
    
    Throws:
    
    StorageException - If the file has already existed, the parent directory does not exist or fileName is an invalid resource name.
  - createWithResponse
```
public Response<FileInfo> createWithResponse(long maxSize,
                                             FileHTTPHeaders httpHeaders,
                                             FileSmbProperties smbProperties,
                                             String filePermission,
                                             Map<String,String> metadata,
                                             Duration timeout,
                                             Context context)
```
    Creates a file in the storage account and returns a response of FileInfo to interact with it.
    Code Samples
    
    Create the file with length of 1024 bytes, some headers, file smb properties and metadata.
```
FileHTTPHeaders httpHeaders = new FileHTTPHeaders()
    .setFileContentType("text/html")
    .setFileContentEncoding("gzip")
    .setFileContentLanguage("en")
    .setFileCacheControl("no-transform")
    .setFileContentDisposition("attachment");
FileSmbProperties smbProperties = new FileSmbProperties()
    .setNtfsFileAttributes(EnumSet.of(NtfsFileAttributes.READ_ONLY))
    .setFileCreationTime(OffsetDateTime.now())
    .setFileLastWriteTime(OffsetDateTime.now())
    .setFilePermissionKey("filePermissionKey");
String filePermission = "filePermission";
// NOTE: filePermission and filePermissionKey should never be both set
Response<FileInfo> response = fileClient.createWithResponse(1024, httpHeaders, smbProperties, filePermission,
    Collections.singletonMap("directory", "metadata"), Duration.ofSeconds(1), new Context(key1, value1));
System.out.printf("Creating the file completed with status code %d", response.getStatusCode());
```
    For more information, see the Azure Docs.
    Parameters:
    
    maxSize - The maximum size in bytes for the file, up to 1 TiB.
    
    httpHeaders - The user settable file http headers.
    
    smbProperties - The user settable file smb properties.
    
    filePermission - The file permission of the file.
    
    metadata - Optional name-value pairs associated with the file as metadata.
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    A response containing the file info and the status of creating the file.
    
    Throws:
    
    StorageException - If the directory has already existed, the parent directory does not exist or directory is an invalid resource name.
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
    
    See Also:
    
    C# identifiers
  - startCopy
```
public FileCopyInfo startCopy(String sourceUrl,
                              Map<String,String> metadata)
```
    Copies a blob or file to a destination file within the storage account.
    Code Samples
    
    Copy file from source getDirectoryUrl to the resourcePath
```
FileCopyInfo response = fileClient.startCopy(
    "https://{accountName}.file.core.windows.net?{SASToken}",
    Collections.singletonMap("file", "metadata"));
System.out.println("Complete copying the file with copy Id: " + response.getCopyId());
```
    For more information, see the Azure Docs.
    Parameters:
    
    sourceUrl - Specifies the URL of the source file or blob, up to 2 KB in length.
    
    metadata - Optional name-value pairs associated with the file as metadata. Metadata names must adhere to the naming rules.
    
    Returns:
    
    The file copy info
    
    See Also:
    
    C# identifiers
  - startCopyWithResponse
```
public Response<FileCopyInfo> startCopyWithResponse(String sourceUrl,
                                                    Map<String,String> metadata,
                                                    Duration timeout,
                                                    Context context)
```
    Copies a blob or file to a destination file within the storage account.
    Code Samples
    
    Copy file from source getDirectoryUrl to the resourcePath
```
Response<FileCopyInfo> response = fileClient.startCopyWithResponse(
    "https://{accountName}.file.core.windows.net?{SASToken}",
    Collections.singletonMap("file", "metadata"), Duration.ofSeconds(1), new Context(key1, value1));
System.out.println("Complete copying the file with copy Id: " + response.getValue().getCopyId());
```
    For more information, see the Azure Docs.
    Parameters:
    
    sourceUrl - Specifies the URL of the source file or blob, up to 2 KB in length.
    
    metadata - Optional name-value pairs associated with the file as metadata. Metadata names must adhere to the naming rules.
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    A response containing the file copy info and the status of copying the file.
    
    Throws:
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
    
    See Also:
    
    C# identifiers
  - abortCopy
```
public void abortCopy(String copyId)
```
    Aborts a pending Copy File operation, and leaves a destination file with zero length and full metadata.
    Code Samples
    
    Abort copy file from copy id("someCopyId")
```
fileClient.abortCopy("someCopyId");
System.out.printf("Abort copying the file completed.");
```
    For more information, see the Azure Docs.
    Parameters:
    
    copyId - Specifies the copy id which has copying pending status associate with it.
  - abortCopyWithResponse
```
public Response<Void> abortCopyWithResponse(String copyId,
                                            Duration timeout,
                                            Context context)
```
    Aborts a pending Copy File operation, and leaves a destination file with zero length and full metadata.
    Code Samples
    
    Abort copy file from copy id("someCopyId")
```
Response<Void> response = fileClient.abortCopyWithResponse("someCopyId", Duration.ofSeconds(1),
    new Context(key1, value1));
System.out.printf("Abort copying the file completed with status code %d", response.getStatusCode());
```
    For more information, see the Azure Docs.
    Parameters:
    
    copyId - Specifies the copy id which has copying pending status associate with it.
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    A response containing the status of aborting copy the file.
    
    Throws:
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - downloadToFile
```
public FileProperties downloadToFile(String downloadFilePath)
```
    Downloads a file from the system, including its metadata and properties into a file specified by the path.
    The file will be created and must not exist, if the file already exists a FileAlreadyExistsException will be thrown.
    
    Code Samples
    
    Download the file to current folder.
```
fileClient.downloadToFile("somelocalfilepath");
if (Files.exists(Paths.get("somelocalfilepath"))) {
    System.out.println("Complete downloading the file.");
}
```
    For more information, see the Azure Docs.
    Parameters:
    
    downloadFilePath - The path where store the downloaded file
    
    Returns:
    
    The properties of the file.
  - downloadToFileWithResponse
```
public Response<FileProperties> downloadToFileWithResponse(String downloadFilePath,
                                                           FileRange range,
                                                           Duration timeout,
                                                           Context context)
```
    Downloads a file from the system, including its metadata and properties into a file specified by the path.
    The file will be created and must not exist, if the file already exists a FileAlreadyExistsException will be thrown.
    
    Code Samples
    
    Download the file from 1024 to 2048 bytes to current folder.
```
Response<FileProperties> response =
    fileClient.downloadToFileWithResponse("somelocalfilepath", new FileRange(1024, 2047L),
    Duration.ofSeconds(1), Context.NONE);
if (Files.exists(Paths.get("somelocalfilepath"))) {
    System.out.println("Complete downloading the file with status code " + response.getStatusCode());
}
```
    For more information, see the Azure Docs.
    Parameters:
    
    downloadFilePath - The path where store the downloaded file
    
    range - Optional byte range which returns file data only from the specified range.
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    The response of the file properties.
  - downloadWithProperties
```
public FileDownloadInfo downloadWithProperties()
```
    Downloads a file from the system, including its metadata and properties
    Code Samples
    
    Download the file with its metadata and properties.
```
FileDownloadInfo response = fileClient.downloadWithProperties();
System.out.println("Complete downloading the data.");
response.getBody().subscribe(
    byteBuffer ->  System.out.println("Complete downloading the data with body: "
        + new String(byteBuffer.array(), StandardCharsets.UTF_8)),
    error -> System.err.print(error.toString()),
    () -> System.out.println("Complete downloading the data!")
);
```
    For more information, see the Azure Docs.
    Returns:
    
    The file download info
  - downloadWithPropertiesWithResponse
```
public Response<FileDownloadInfo> downloadWithPropertiesWithResponse(FileRange range,
                                                                     Boolean rangeGetContentMD5,
                                                                     Duration timeout,
                                                                     Context context)
```
    Downloads a file from the system, including its metadata and properties
    Code Samples
    
    Download the file from 1024 to 2048 bytes with its metadata and properties and without the contentMD5.
```
Response<FileDownloadInfo> response = fileClient.downloadWithPropertiesWithResponse(new FileRange(1024, 2047L),
    false, Duration.ofSeconds(1), new Context(key1, value1));
System.out.println("Complete downloading the data with status code: " + response.getStatusCode());
response.getValue().getBody().subscribe(
    byteBuffer ->  System.out.println("Complete downloading the data with body: "
        + new String(byteBuffer.array(), StandardCharsets.UTF_8)),
    error -> System.err.print(error.toString()),
    () -> System.out.println("Complete downloading the data!")
);
```
    For more information, see the Azure Docs.
    Parameters:
    
    range - Optional byte range which returns file data only from the specified range.
    
    rangeGetContentMD5 - Optional boolean which the service returns the MD5 hash for the range when it sets to true, as long as the range is less than or equal to 4 MB in size.
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    A response containing the file download info headers and response status code
    
    Throws:
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - delete
```
public void delete()
```
    Deletes the file associate with the client.
    Code Samples
    
    Delete the file
```
fileClient.delete();
System.out.println("Complete deleting the file.");
```
    For more information, see the Azure Docs.
    Throws:
    
    StorageException - If the directory doesn't exist or the file doesn't exist.
  - deleteWithResponse
```
public Response<Void> deleteWithResponse(Duration timeout,
                                         Context context)
```
    Deletes the file associate with the client.
    Code Samples
    
    Delete the file
```
Response<Void> response = fileClient.deleteWithResponse(Duration.ofSeconds(1), new Context(key1, value1));
System.out.println("Complete deleting the file with status code: " + response.getStatusCode());
```
    For more information, see the Azure Docs.
    Parameters:
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    A response that only contains headers and response status code
    
    Throws:
    
    StorageException - If the directory doesn't exist or the file doesn't exist.
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - getProperties
```
public FileProperties getProperties()
```
    Retrieves the properties of the storage account's file. The properties includes file metadata, last modified date, is server encrypted, and eTag.
    Code Samples
    
    Retrieve file properties
```
FileProperties properties = fileClient.getProperties();
System.out.printf("File latest modified date is %s.", properties.getLastModified());
```
    For more information, see the Azure Docs.
    Returns:
    
    Storage file properties
  - getPropertiesWithResponse
```
public Response<FileProperties> getPropertiesWithResponse(Duration timeout,
                                                          Context context)
```
    Retrieves the properties of the storage account's file. The properties includes file metadata, last modified date, is server encrypted, and eTag.
    Code Samples
    
    Retrieve file properties
```
Response<FileProperties> response = fileClient.getPropertiesWithResponse(
    Duration.ofSeconds(1), new Context(key1, value1));
System.out.printf("File latest modified date is %s.", response.getValue().getLastModified());
```
    For more information, see the Azure Docs.
    Parameters:
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    A response containing the Storage file properties with headers and status code
    
    Throws:
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - setProperties
```
public FileInfo setProperties(long newFileSize,
                              FileHTTPHeaders httpHeaders,
                              FileSmbProperties smbProperties,
                              String filePermission)
```
    Sets the user-defined httpHeaders to associate to the file.
    If null is passed for the httpHeaders it will clear the httpHeaders associated to the file.
    
    Code Samples
    
    Set the httpHeaders of contentType of "text/plain"
```
FileHTTPHeaders httpHeaders = new FileHTTPHeaders()
    .setFileContentType("text/html")
    .setFileContentEncoding("gzip")
    .setFileContentLanguage("en")
    .setFileCacheControl("no-transform")
    .setFileContentDisposition("attachment");
FileSmbProperties smbProperties = new FileSmbProperties()
    .setNtfsFileAttributes(EnumSet.of(NtfsFileAttributes.READ_ONLY))
    .setFileCreationTime(OffsetDateTime.now())
    .setFileLastWriteTime(OffsetDateTime.now())
    .setFilePermissionKey("filePermissionKey");
String filePermission = "filePermission";
// NOTE: filePermission and filePermissionKey should never be both set
fileClient.setProperties(1024, httpHeaders, smbProperties, filePermission);
System.out.printf("Setting the file httpHeaders completed.");
```
    Clear the httpHeaders of the file and preserve the SMB properties
```
FileInfo response = fileClient.setProperties(1024, null, null, null);
System.out.printf("Setting the file httpHeaders completed.");
```
    For more information, see the Azure Docs.
    Parameters:
    
    newFileSize - New file size of the file
    
    httpHeaders - The user settable file http headers.
    
    smbProperties - The user settable file smb properties.
    
    filePermission - The file permission of the file
    
    Returns:
    
    The file info
    
    Throws:
    
    IllegalArgumentException - thrown if parameters fail the validation.
  - setPropertiesWithResponse
```
public Response<FileInfo> setPropertiesWithResponse(long newFileSize,
                                                    FileHTTPHeaders httpHeaders,
                                                    FileSmbProperties smbProperties,
                                                    String filePermission,
                                                    Duration timeout,
                                                    Context context)
```
    Sets the user-defined httpHeaders to associate to the file.
    If null is passed for the httpHeaders it will clear the httpHeaders associated to the file.
    
    Code Samples
    
    Set the httpHeaders of contentType of "text/plain"
```
FileHTTPHeaders httpHeaders = new FileHTTPHeaders()
    .setFileContentType("text/html")
    .setFileContentEncoding("gzip")
    .setFileContentLanguage("en")
    .setFileCacheControl("no-transform")
    .setFileContentDisposition("attachment");
FileSmbProperties smbProperties = new FileSmbProperties()
    .setNtfsFileAttributes(EnumSet.of(NtfsFileAttributes.READ_ONLY))
    .setFileCreationTime(OffsetDateTime.now())
    .setFileLastWriteTime(OffsetDateTime.now())
    .setFilePermissionKey("filePermissionKey");
String filePermission = "filePermission";
// NOTE: filePermission and filePermissionKey should never be both set
Response<FileInfo> response = fileClient.setPropertiesWithResponse(1024, httpHeaders, smbProperties,
    filePermission, Duration.ofSeconds(1), new Context(key1, value1));
System.out.printf("Setting the file httpHeaders completed with status code %d", response.getStatusCode());
```
    Clear the httpHeaders of the file and preserve the SMB properties
```
Response<FileInfo> response = fileClient.setPropertiesWithResponse(1024, null, null, null,
    Duration.ofSeconds(1), new Context(key1, value1));
System.out.printf("Setting the file httpHeaders completed with status code %d", response.getStatusCode());
```
    For more information, see the Azure Docs.
    Parameters:
    
    newFileSize - New file size of the file
    
    httpHeaders - The user settable file http headers.
    
    smbProperties - The user settable file smb properties.
    
    filePermission - The file permission of the file
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    Response containing the file info with headers and status code
    
    Throws:
    
    IllegalArgumentException - thrown if parameters fail the validation.
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - setMetadata
```
public FileMetadataInfo setMetadata(Map<String,String> metadata)
```
    Sets the user-defined metadata to associate to the file.
    If null is passed for the metadata it will clear the metadata associated to the file.
    
    Code Samples
    
    Set the metadata to "file:updatedMetadata"
```
fileClient.setMetadata(Collections.singletonMap("file", "updatedMetadata"));
System.out.println("Setting the file metadata completed.");
```
    Clear the metadata of the file
```
fileClient.setMetadata(null);
System.out.printf("Setting the file metadata completed.");
```
    For more information, see the Azure Docs.
    Parameters:
    
    metadata - Options.Metadata to set on the file, if null is passed the metadata for the file is cleared
    
    Returns:
    
    The file meta info
    
    Throws:
    
    StorageException - If the file doesn't exist or the metadata contains invalid keys
  - setMetadataWithResponse
```
public Response<FileMetadataInfo> setMetadataWithResponse(Map<String,String> metadata,
                                                          Duration timeout,
                                                          Context context)
```
    Sets the user-defined metadata to associate to the file.
    If null is passed for the metadata it will clear the metadata associated to the file.
    
    Code Samples
    
    Set the metadata to "file:updatedMetadata"
```
Response<FileMetadataInfo> response = fileClient.setMetadataWithResponse(
    Collections.singletonMap("file", "updatedMetadata"), Duration.ofSeconds(1), new Context(key1, value1));
System.out.printf("Setting the file metadata completed with status code %d", response.getStatusCode());
```
    Clear the metadata of the file
```
Response<FileMetadataInfo> response = fileClient.setMetadataWithResponse(null,
    Duration.ofSeconds(1), new Context(key1, value1));
System.out.printf("Setting the file metadata completed with status code %d", response.getStatusCode());
```
    For more information, see the Azure Docs.
    Parameters:
    
    metadata - Options.Metadata to set on the file, if null is passed the metadata for the file is cleared
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    Response containing the file meta info with headers and status code
    
    Throws:
    
    StorageException - If the file doesn't exist or the metadata contains invalid keys
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - upload
```
public FileUploadInfo upload(ByteBuffer data,
                             long length)
```
    Uploads a range of bytes to the beginning of a file in storage file service. Upload operations performs an in-place write on the specified file.
    Code Samples
    
    Upload data "default" to the file in Storage File Service.
```
ByteBuffer defaultData = ByteBuffer.wrap("default".getBytes(StandardCharsets.UTF_8));
FileUploadInfo response = fileClient.upload(defaultData, defaultData.remaining());
System.out.println("Complete uploading the data with eTag: " + response.getETag());
```
    For more information, see the Azure Docs.
    Parameters:
    
    data - The data which will upload to the storage file.
    
    length - Specifies the number of bytes being transmitted in the request body. When the FileRangeWriteType is set to clear, the value of this header must be set to zero..
    
    Returns:
    
    The file upload info
    
    Throws:
    
    StorageException - If you attempt to upload a range that is larger than 4 MB, the service returns status code 413 (Request Entity Too Large)
  - uploadWithResponse
```
public Response<FileUploadInfo> uploadWithResponse(ByteBuffer data,
                                                   long length,
                                                   Duration timeout,
                                                   Context context)
```
    Uploads a range of bytes to the beginning of a file in storage file service. Upload operations performs an in-place write on the specified file.
    Code Samples
    
    Upload "default" to the file.
```
ByteBuffer defaultData = ByteBuffer.wrap("default".getBytes(StandardCharsets.UTF_8));
Response<FileUploadInfo> response = fileClient.uploadWithResponse(defaultData, defaultData.remaining(),
    Duration.ofSeconds(1), new Context(key1, value1));
System.out.println("Complete uploading the data with status code: " + response.getStatusCode());
```
    For more information, see the Azure Docs.
    Parameters:
    
    data - The data which will upload to the storage file.
    
    length - Specifies the number of bytes being transmitted in the request body. When the FileRangeWriteType is set to clear, the value of this header must be set to zero.
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    The file upload info
    
    Throws:
    
    StorageException - If you attempt to upload a range that is larger than 4 MB, the service returns status code 413 (Request Entity Too Large)
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - uploadWithResponse
```
public Response<FileUploadInfo> uploadWithResponse(ByteBuffer data,
                                                   long length,
                                                   long offset,
                                                   Duration timeout,
                                                   Context context)
```
    Uploads a range of bytes to specific of a file in storage file service. Upload operations performs an in-place write on the specified file.
    Code Samples
    
    Upload data "default" starting from 1024.
```
ByteBuffer defaultData = ByteBuffer.wrap("default".getBytes(StandardCharsets.UTF_8));
Response<FileUploadInfo> response = fileClient.uploadWithResponse(defaultData, defaultData.remaining(),
    1024, Duration.ofSeconds(1), new Context(key1, value1));
System.out.println("Complete uploading the data with status code: " + response.getStatusCode());
```
    For more information, see the Azure Docs.
    Parameters:
    
    data - The data which will upload to the storage file.
    
    length - Specifies the number of bytes being transmitted in the request body.
    
    offset - Optional starting point of the upload range. It will start from the beginning if it is null
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    A response containing the file upload info with headers and response status code
    
    Throws:
    
    StorageException - If you attempt to upload a range that is larger than 4 MB, the service returns status code 413 (Request Entity Too Large)
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - uploadRangeFromUrl
```
public FileUploadRangeFromUrlInfo uploadRangeFromUrl(long length,
                                                     long destinationOffset,
                                                     long sourceOffset,
                                                     URI sourceURI)
```
    Uploads a range of bytes from one file to another file.
    Code Samples
    
    Upload a number of bytes from a file at defined source and destination offsets
```
FileUploadRangeFromUrlInfo response = fileClient.uploadRangeFromUrl(6, 8, 0, new URI("filewithSAStoken"));
System.out.println("Completed upload range from url!");
```
    For more information, see the Azure Docs.
    Parameters:
    
    length - Specifies the number of bytes being transmitted in the request body.
    
    destinationOffset - Starting point of the upload range on the destination.
    
    sourceOffset - Starting point of the upload range on the source.
    
    sourceURI - Specifies the URL of the source file.
    
    Returns:
    
    The file upload range from url info
  - uploadRangeFromUrlWithResponse
```
public Response<FileUploadRangeFromUrlInfo> uploadRangeFromUrlWithResponse(long length,
                                                                           long destinationOffset,
                                                                           long sourceOffset,
                                                                           URI sourceURI,
                                                                           Duration timeout,
                                                                           Context context)
```
    Uploads a range of bytes from one file to another file.
    Code Samples
    
    Upload a number of bytes from a file at defined source and destination offsets
```
Response<FileUploadRangeFromUrlInfo> response = fileClient.uploadRangeFromUrlWithResponse(6,
    8, 0, new URI("filewithSAStoken"), Duration.ofSeconds(1), Context.NONE);
System.out.println("Completed upload range from url!");
```
    For more information, see the Azure Docs.
    Parameters:
    
    length - Specifies the number of bytes being transmitted in the request body.
    
    destinationOffset - Starting point of the upload range on the destination.
    
    sourceOffset - Starting point of the upload range on the source.
    
    sourceURI - Specifies the URL of the source file.
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    A response containing the file upload range from url info with headers and response status code.
    
    Throws:
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - clearRange
```
public FileUploadInfo clearRange(long length)
```
    Clears a range of bytes to specific of a file in storage file service. Clear operations performs an in-place write on the specified file.
    Code Samples
    
    Clears the first 1024 bytes.
```
FileUploadInfo response = fileClient.clearRange(1024);
System.out.println("Complete clearing the range with eTag: " + response.getETag());
```
    For more information, see the Azure Docs.
    Parameters:
    
    length - Specifies the number of bytes being cleared.
    
    Returns:
    
    The file upload info
  - clearRangeWithResponse
```
public Response<FileUploadInfo> clearRangeWithResponse(long length,
                                                       long offset,
                                                       Duration timeout,
                                                       Context context)
```
    Clears a range of bytes to specific of a file in storage file service. Upload operations performs an in-place write on the specified file.
    Code Samples
    
    Clear the range starting from 1024 with length of 1024.
```
Response<FileUploadInfo> response = fileClient.clearRangeWithResponse(1024, 1024,
    Duration.ofSeconds(1), new Context(key1, value1));
System.out.println("Complete clearing the range with status code: " + response.getStatusCode());
```
    For more information, see the Azure Docs.
    Parameters:
    
    length - Specifies the number of bytes being transmitted in the request body.
    
    offset - Optional starting point of the upload range. It will start from the beginning if it is null
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    A response containing the file upload info with headers and response status code
    
    Throws:
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - uploadFromFile
```
public void uploadFromFile(String uploadFilePath)
```
    Uploads file to storage file service.
    Code Samples
    
    Upload the file from the source file path.
```
fileClient.uploadFromFile("someFilePath");
```
    For more information, see the Azure Docs Create File and Azure Docs Upload.
    Parameters:
    
    uploadFilePath - The path where store the source file to upload
  - listRanges
```
public PagedIterable<FileRange> listRanges()
```
    List of valid ranges for a file.
    Code Samples
    
    List all ranges for the file client.
```
Iterable<FileRange> ranges = fileClient.listRanges();
ranges.forEach(range ->
    System.out.printf("List ranges completed with start: %d, end: %d", range.getStart(), range.getEnd()));
```
    For more information, see the Azure Docs.
    Returns:
    
    ranges in the files.
  - listRanges
```
public PagedIterable<FileRange> listRanges(FileRange range,
                                           Duration timeout,
                                           Context context)
```
    List of valid ranges for a file.
    Code Samples
    
    List all ranges within the file range from 1KB to 2KB.
```
Iterable<FileRange> ranges = fileClient.listRanges(new FileRange(1024, 2048L), Duration.ofSeconds(1),
    new Context(key1, value1));
ranges.forEach(range ->
    System.out.printf("List ranges completed with start: %d, end: %d", range.getStart(), range.getEnd()));
```
    For more information, see the Azure Docs.
    Parameters:
    
    range - Optional byte range which returns file data only from the specified range.
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    ranges in the files that satisfy the requirements
    
    Throws:
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - listHandles
```
public PagedIterable<HandleItem> listHandles()
```
    List of open handles on a file.
    Code Samples
    
    List all handles for the file client.
```
fileClient.listHandles()
    .forEach(handleItem -> System.out.printf("List handles completed with handleId %s",
        handleItem.getHandleId()));
```
    For more information, see the Azure Docs.
    Returns:
    
    handles in the files that satisfy the requirements
  - listHandles
```
public PagedIterable<HandleItem> listHandles(Integer maxResults,
                                             Duration timeout,
                                             Context context)
```
    List of open handles on a file.
    Code Samples
    
    List 10 handles for the file client.
```
fileClient.listHandles(10, Duration.ofSeconds(1), new Context(key1, value1))
    .forEach(handleItem -> System.out.printf("List handles completed with handleId %s",
        handleItem.getHandleId()));
```
    For more information, see the Azure Docs.
    Parameters:
    
    maxResults - Optional max number of results returned per page
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    handles in the file that satisfy the requirements
    
    Throws:
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - forceCloseHandles
```
public PagedIterable<Integer> forceCloseHandles(String handleId,
                                                Duration timeout,
                                                Context context)
```
    Closes a handle or handles opened on a file at the service. It is intended to be used alongside FileClient.listHandles() (Integer)} .
    Code Samples
    
    Force close handles with handles returned by list handles in recursive.
```
fileClient.listHandles(10, Duration.ofSeconds(1), new Context(key1, value1))
    .forEach(result ->
        fileClient.forceCloseHandles(result.getHandleId(), Duration.ofSeconds(1),
            new Context(key1, value1)).forEach(numOfClosedHandles ->
            System.out.printf("Close %d handles.", numOfClosedHandles)
        ));
```
    For more information, see the Azure Docs.
    Parameters:
    
    handleId - Specifies the handle ID to be closed. Use an asterisk ('*') as a wildcard string to specify all handles.
    
    timeout - An optional timeout applied to the operation. If a response is not returned before the timeout concludes a RuntimeException will be thrown.
    
    context - Additional context that is passed through the Http pipeline during the service call.
    
    Returns:
    
    The counts of number of handles closed
    
    Throws:
    
    RuntimeException - if the operation doesn't complete before the timeout concludes.
  - getShareSnapshotId
```
public String getShareSnapshotId()
```
    Get snapshot id which attached to FileClient. Return null if no snapshot id attached.
    Code Samples
    
    Get the share snapshot id.
```
OffsetDateTime currentTime = OffsetDateTime.of(LocalDateTime.now(), ZoneOffset.UTC);
FileClient fileClient = new FileClientBuilder()
    .endpoint("https://${accountName}.file.core.windows.net")
    .sasToken("${SASToken}")
    .shareName("myshare")
    .resourcePath("myfile")
    .snapshot(currentTime.toString())
    .buildFileClient();

System.out.printf("Snapshot ID: %s%n", fileClient.getShareSnapshotId());
```
    Returns:
    
    The snapshot id which is a unique DateTime value that identifies the share snapshot to its base share.
  - getShareName
```
public String getShareName()
```
    Get the share name of file client.
    Get the share name.
```
String shareName = fileClient.getShareName();
System.out.println("The share name of the directory is " + shareName);
```
    Returns:
    
    The share name of the file.
  - getFilePath
```
public String getFilePath()
```
    Get file path of the client.
    Get the file path.
```
String filePath = fileClient.getFilePath();
System.out.println("The name of the file is " + filePath);
```
    Returns:
    
    The path of the file.
  - getAccountName
```
public String getAccountName()
```
    Get associated account name.
    
    Returns:
    
    account name associated with this storage resource.

Class FileClient

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getFileUrl

openInputStream

openInputStream

getFileOutputStream

getFileOutputStream

create

createWithResponse

startCopy

startCopyWithResponse

abortCopy

abortCopyWithResponse

downloadToFile

downloadToFileWithResponse

downloadWithProperties

downloadWithPropertiesWithResponse

delete

deleteWithResponse

getProperties

getPropertiesWithResponse

setProperties

setPropertiesWithResponse

setMetadata

setMetadataWithResponse

upload

uploadWithResponse

uploadWithResponse

uploadRangeFromUrl

uploadRangeFromUrlWithResponse

clearRange

clearRangeWithResponse

uploadFromFile

listRanges

listRanges

listHandles

listHandles

forceCloseHandles

getShareSnapshotId

getShareName

getFilePath

getAccountName