ShareClient Class

  • Reference

Definition

Package:
com.azure.storage.file.share
Maven Artifact:
com.azure:azure-storage-file-share:12.12.1
  • java.lang.Object
    • com.azure.storage.file.share.ShareClient

This class provides a client that contains all the operations for interacting with a share in Azure Storage Share. Operations allowed by the client are creating and deleting the share, creating snapshots for the share, creating and deleting directories in the share and retrieving and updating properties metadata and access policies of the share.

Instantiating a Synchronous Share Client

ShareClient client = new ShareClientBuilder()
     .connectionString("${connectionString}")
     .endpoint("${endpoint}")
     .buildClient();

View ShareClientBuilder for additional ways to construct the client.

public class ShareClient

Methods

create()

Creates the share in the storage account.

Code Samples

Create the share

ShareInfo response = shareClient.create();
 System.out.println("Complete creating the shares with status code: " + response);

For more information, see the Azure Docs.
createDirectory(String directoryName)

Creates the directory in the share with the given name.

Code Samples

Create the directory "documents"

ShareDirectoryClient response = shareClient.createDirectory("mydirectory");
 System.out.println("Complete creating the directory.");

For more information, see the Azure Docs.
createDirectoryWithResponse(String directoryName, FileSmbProperties smbProperties, String filePermission, Map<String,String> metadata, Duration timeout, Context context)

Creates the directory in the share with the given name and associates the passed metadata to it.

Code Samples

Create the directory "documents" with metadata "directory:metadata"

FileSmbProperties smbProperties = new FileSmbProperties();
 String filePermission = "filePermission";
 Response<ShareDirectoryClient> response = shareClient.createDirectoryWithResponse("documents",
     smbProperties, filePermission, Collections.singletonMap("directory", "metadata"),
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Creating the directory completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.
createFile(String fileName, long maxSize)

Creates the file in the share with the given name and file max size.

Code Samples

Create the file "myfile" with size of 1024 bytes.

ShareFileClient response = shareClient.createFile("myfile", 1024);
 System.out.println("Complete creating the file with snapshot Id:" + response.getShareSnapshotId());

For more information, see the Azure Docs.
createFileWithResponse(String fileName, long maxSize, ShareFileHttpHeaders httpHeaders, FileSmbProperties smbProperties, String filePermission, Map<String,String> metadata, ShareRequestConditions requestConditions, Duration timeout, Context context)

Creates the file in the share with the given name, file max size and associates the passed properties to it.

Code Samples

Create the file "myfile" with length of 1024 bytes, some headers, file smb properties and metadata

ShareFileHttpHeaders httpHeaders = new ShareFileHttpHeaders()
     .setContentType("text/html")
     .setContentEncoding("gzip")
     .setContentLanguage("en")
     .setCacheControl("no-transform")
     .setContentDisposition("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

 ShareRequestConditions requestConditions = new ShareRequestConditions().setLeaseId(leaseId);

 Response<ShareFileClient> response = shareClient.createFileWithResponse("myfile", 1024,
     httpHeaders, smbProperties, filePermission, Collections.singletonMap("directory", "metadata"),
     requestConditions, 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.
createFileWithResponse(String fileName, long maxSize, ShareFileHttpHeaders httpHeaders, FileSmbProperties smbProperties, String filePermission, Map<String,String> metadata, Duration timeout, Context context)

Creates the file in the share with the given name, file max size and associates the passed properties to it.

Code Samples

Create the file "myfile" with length of 1024 bytes, some headers, file smb properties and metadata

ShareFileHttpHeaders httpHeaders = new ShareFileHttpHeaders()
     .setContentType("text/html")
     .setContentEncoding("gzip")
     .setContentLanguage("en")
     .setCacheControl("no-transform")
     .setContentDisposition("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<ShareFileClient> response = shareClient.createFileWithResponse("myfile", 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.
createPermission(String filePermission)

Creates a permission at the share level. If a permission already exists, it returns the key of it, else creates a new permission and returns the key.

Code Samples

String response = shareClient.createPermission("filePermission");
 System.out.printf("The file permission key is %s", response);
createPermissionWithResponse(String filePermission, Context context)

Creates a permission t the share level. If a permission already exists, it returns the key of it, else creates a new permission and returns the key.

Code Samples

Response<String> response = shareClient.createPermissionWithResponse("filePermission", Context.NONE);
 System.out.printf("The file permission key is %s", response.getValue());
createSnapshot()

Creates a snapshot of the share with the same metadata associated to the share at the time of creation.

Code Samples

Create a snapshot

ShareSnapshotInfo response = shareClient.createSnapshot();
 System.out.println("Complete creating the share snpashot with snapshot id: " + response.getSnapshot());

For more information, see the Azure Docs.
createSnapshotWithResponse(Map<String,String> metadata, Duration timeout, Context context)

Creates a snapshot of the share with the metadata that was passed associated to the snapshot.

Code Samples

Create a snapshot with metadata "snapshot:metadata"

Response<ShareSnapshotInfo> response =
     shareClient.createSnapshotWithResponse(Collections.singletonMap("snpashot", "metadata"),
         Duration.ofSeconds(1), new Context(key1, value1));
 System.out.println("Complete creating the share snpashot with snapshot id: " + response.getValue().getSnapshot());

For more information, see the Azure Docs.
createWithResponse(ShareCreateOptions options, Duration timeout, Context context)

Creates the share in the storage account with the specified options.

Code Samples

Response<ShareInfo> response = shareClient.createWithResponse(new ShareCreateOptions()
         .setMetadata(Collections.singletonMap("share", "metadata")).setQuotaInGb(1)
         .setAccessTier(ShareAccessTier.HOT), Duration.ofSeconds(1), new Context(key1, value1));
 System.out.println("Complete creating the shares with status code: " + response.getStatusCode());

For more information, see the Azure Docs.
createWithResponse(Map<String,String> metadata, Integer quotaInGB, Duration timeout, Context context)

Creates the share in the storage account with the specified metadata and quota.

Code Samples

Create the share with metadata "share:metadata"

Response<ShareInfo> response = shareClient.createWithResponse(Collections.singletonMap("share", "metadata"),
     null, Duration.ofSeconds(1), new Context(key1, value1));
 System.out.println("Complete creating the shares with status code: " + response.getStatusCode());

Create the share with a quota of 10 GB

Response<ShareInfo> response = shareClient.createWithResponse(null, 10,
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.println("Complete creating the shares with status code: " + response.getStatusCode());

For more information, see the Azure Docs.
delete()

Deletes the share in the storage account

Code Samples

Delete the share

shareClient.delete();
 System.out.println("Completed deleting the share.");

For more information, see the Azure Docs.
deleteDirectory(String directoryName)

Deletes the specified directory in the share.

Code Samples

Delete the directory "mydirectory"

shareClient.deleteDirectory("mydirectory");
 System.out.println("Completed deleting the directory.");

For more information, see the Azure Docs.
deleteDirectoryWithResponse(String directoryName, Duration timeout, Context context)

Deletes the specified directory in the share.

Code Samples

Delete the directory "mydirectory"

Response<Void> response = shareClient.deleteDirectoryWithResponse("mydirectory",
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.println("Complete deleting the directory with status code: " + response.getStatusCode());

For more information, see the Azure Docs.
deleteFile(String fileName)

Deletes the specified file in the share.

Code Samples

Delete the file "myfile"

shareClient.deleteFile("myfile");
 System.out.println("Complete deleting the file.");

For more information, see the Azure Docs.
deleteFileWithResponse(String fileName, ShareRequestConditions requestConditions, Duration timeout, Context context)

Deletes the specified file in the share.

Code Samples

Delete the file "myfile"

ShareRequestConditions requestConditions = new ShareRequestConditions().setLeaseId(leaseId);
 Response<Void> response = shareClient.deleteFileWithResponse("myfile", requestConditions,
     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.
deleteFileWithResponse(String fileName, Duration timeout, Context context)

Deletes the specified file in the share.

Code Samples

Delete the file "myfile"

Response<Void> response = shareClient.deleteFileWithResponse("myfile",
     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.
deleteWithResponse(ShareDeleteOptions options, Duration timeout, Context context)

Deletes the share in the storage account

Code Samples

Delete the share

Response<Void> response = shareClient.deleteWithResponse(new ShareDeleteOptions()
         .setRequestConditions(new ShareRequestConditions().setLeaseId(leaseId)),
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.println("Complete deleting the share with status code: " + response.getStatusCode());

For more information, see the Azure Docs.
deleteWithResponse(Duration timeout, Context context)

Deletes the share in the storage account

Code Samples

Delete the share

Response<Void> response = shareClient.deleteWithResponse(Duration.ofSeconds(1), new Context(key1, value1));
 System.out.println("Complete deleting the share with status code: " + response.getStatusCode());

For more information, see the Azure Docs.
exists()

Determines if the share this client represents exists in the cloud.

Code Samples

System.out.printf("Exists? %b%n", client.exists());
existsWithResponse(Duration timeout, Context context)

Determines if the share this client represents exists in the cloud.

Code Samples

Context context = new Context("Key", "Value");
 System.out.printf("Exists? %b%n", client.existsWithResponse(timeout, context).getValue());
generateSas(ShareServiceSasSignatureValues shareServiceSasSignatureValues)

Generates a service sas for the queue using the specified ShareServiceSasSignatureValues

Note : The client must be authenticated via StorageSharedKeyCredential

See ShareServiceSasSignatureValues for more information on how to construct a service SAS.

Code Samples

OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);
 ShareSasPermission permission = new ShareSasPermission().setReadPermission(true);

 ShareServiceSasSignatureValues values = new ShareServiceSasSignatureValues(expiryTime, permission)
     .setStartTime(OffsetDateTime.now());

 shareAsyncClient.generateSas(values); // Client must be authenticated via StorageSharedKeyCredential
generateSas(ShareServiceSasSignatureValues shareServiceSasSignatureValues, Context context)

Generates a service sas for the queue using the specified ShareServiceSasSignatureValues

Note : The client must be authenticated via StorageSharedKeyCredential

See ShareServiceSasSignatureValues for more information on how to construct a service SAS.

Code Samples

OffsetDateTime expiryTime = OffsetDateTime.now().plusDays(1);
 ShareSasPermission permission = new ShareSasPermission().setReadPermission(true);

 ShareServiceSasSignatureValues values = new ShareServiceSasSignatureValues(expiryTime, permission)
     .setStartTime(OffsetDateTime.now());

 // Client must be authenticated via StorageSharedKeyCredential
 shareAsyncClient.generateSas(values, new Context("key", "value"));
getAccessPolicy()

Retrieves stored access policies specified for the share.

Code Samples

List the stored access policies

for (ShareSignedIdentifier result : shareClient.getAccessPolicy()) {
     System.out.printf("Access policy %s allows these permissions: %s",
         result.getId(), result.getAccessPolicy().getPermissions());
 }

For more information, see the Azure Docs.
getAccessPolicy(ShareGetAccessPolicyOptions options)

Retrieves stored access policies specified for the share.

Code Samples

List the stored access policies

for (ShareSignedIdentifier result : shareClient
     .getAccessPolicy(new ShareGetAccessPolicyOptions()
         .setRequestConditions(new ShareRequestConditions().setLeaseId(leaseId)))) {
     System.out.printf("Access policy %s allows these permissions: %s",
         result.getId(), result.getAccessPolicy().getPermissions());
 }

For more information, see the Azure Docs.
getAccountName()

Get associated account name.
getAccountUrl()

Get the url of the storage account.
getDirectoryClient(String directoryName)

Constructs a ShareDirectoryClient that interacts with the specified directory.

If the directory doesn't exist in the share create() in the client will need to be called before interaction with the directory can happen.
getFileClient(String filePath)

Constructs a ShareFileClient that interacts with the specified file.

If the file doesn't exist in the share create(long maxSize) ) create} in the client will need to be called before interaction with the file can happen.
getHttpPipeline()

Gets the HttpPipeline powering this client.
getPermission(String filePermissionKey)

Gets a permission for a given key

Code Samples

String response = shareClient.getPermission("filePermissionKey");
 System.out.printf("The file permission is %s", response);
getPermissionWithResponse(String filePermissionKey, Context context)

Gets a permission for a given key.

Code Samples

Response<String> response = shareClient.getPermissionWithResponse("filePermissionKey", Context.NONE);
 System.out.printf("The file permission is %s", response.getValue());
getProperties()

Retrieves the properties of the share, these include the metadata associated to it and the quota that the share is restricted to.

Code Samples

Retrieve the share properties

ShareProperties properties = shareClient.getProperties();
 System.out.printf("Share quota: %d, Metadata: %s", properties.getQuota(), properties.getMetadata());

For more information, see the Azure Docs.
getPropertiesWithResponse(ShareGetPropertiesOptions options, Duration timeout, Context context)

Retrieves the properties of the share, these include the metadata associated to it and the quota that the share is restricted to.

Code Samples

Retrieve the share properties

ShareProperties properties = shareClient.getPropertiesWithResponse(new ShareGetPropertiesOptions()
     .setRequestConditions(new ShareRequestConditions().setLeaseId(leaseId)),
     Duration.ofSeconds(1), new Context(key1, value1)).getValue();
 System.out.printf("Share quota: %d, Metadata: %s", properties.getQuota(), properties.getMetadata());

For more information, see the Azure Docs.
getPropertiesWithResponse(Duration timeout, Context context)

Retrieves the properties of the share, these include the metadata associated to it and the quota that the share is restricted to.

Code Samples

Retrieve the share properties

ShareProperties properties = shareClient.getPropertiesWithResponse(
     Duration.ofSeconds(1), new Context(key1, value1)).getValue();
 System.out.printf("Share quota: %d, Metadata: %s", properties.getQuota(), properties.getMetadata());

For more information, see the Azure Docs.
getRootDirectoryClient()

Constructs a ShareDirectoryClient that interacts with the root directory in the share.

If the directory doesn't exist in the share create() in the client will need to be called before interaction with the directory can happen.
getServiceVersion()

Gets the service version the client is using.
getShareName()

Get share name from share client.

Code Samples

String shareName = shareClient.getShareName();
 System.out.println("The name of the share is " + shareName);
getShareUrl()

Get the url of the storage share client.
getSnapshotClient(String snapshot)

Creates a new ShareAsyncClient linked to the snapshot of this share resource.
getSnapshotId()

Get snapshot id which attached to ShareClient. Return null if no snapshot id attached.

Code Samples

Get the share snapshot id.

OffsetDateTime currentTime = OffsetDateTime.of(LocalDateTime.now(), ZoneOffset.UTC);
 ShareClient shareClient = new ShareClientBuilder().endpoint("https://${accountName}.file.core.windows.net")
     .sasToken("${SASToken}")
     .shareName("myshare")
     .snapshot(currentTime.toString())
     .buildClient();

 System.out.printf("Snapshot ID: %s%n", shareClient.getSnapshotId());
getStatistics()

Retrieves storage statistics about the share.

Code Samples

Retrieve the storage statistics

ShareStatistics response = shareClient.getStatistics();
 System.out.printf("The share is using %d GB", response.getShareUsageInGB());

For more information, see the Azure Docs.
getStatisticsWithResponse(ShareGetStatisticsOptions options, Duration timeout, Context context)

Retrieves storage statistics about the share.

Code Samples

Retrieve the storage statistics

Response<ShareStatistics> response = shareClient.getStatisticsWithResponse(
     new ShareGetStatisticsOptions().setRequestConditions(new ShareRequestConditions().setLeaseId(leaseId)),
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("The share is using %d GB", response.getValue().getShareUsageInGB());

For more information, see the Azure Docs.
getStatisticsWithResponse(Duration timeout, Context context)

Retrieves storage statistics about the share.

Code Samples

Retrieve the storage statistics

Response<ShareStatistics> response = shareClient.getStatisticsWithResponse(
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("The share is using %d GB", response.getValue().getShareUsageInGB());

For more information, see the Azure Docs.
setAccessPolicy(List<ShareSignedIdentifier> permissions)

Sets stored access policies for the share.

Code Samples

Set a read only stored access policy

ShareAccessPolicy accessPolicy = new ShareAccessPolicy().setPermissions("r")
     .setStartsOn(OffsetDateTime.now(ZoneOffset.UTC))
     .setExpiresOn(OffsetDateTime.now(ZoneOffset.UTC).plusDays(10));

 ShareSignedIdentifier permission = new ShareSignedIdentifier().setId("mypolicy").setAccessPolicy(accessPolicy);

 shareClient.setAccessPolicy(Collections.singletonList(permission));
 System.out.println("Setting access policies completed.");

For more information, see the Azure Docs.
setAccessPolicyWithResponse(ShareSetAccessPolicyOptions options, Duration timeout, Context context)

Sets stored access policies for the share.

Code Samples

Set a read only stored access policy

ShareAccessPolicy accessPolicy = new ShareAccessPolicy().setPermissions("r")
     .setStartsOn(OffsetDateTime.now(ZoneOffset.UTC))
     .setExpiresOn(OffsetDateTime.now(ZoneOffset.UTC).plusDays(10));

 ShareSignedIdentifier permission = new ShareSignedIdentifier().setId("mypolicy").setAccessPolicy(accessPolicy);

 Response<ShareInfo> response = shareClient.setAccessPolicyWithResponse(
     new ShareSetAccessPolicyOptions().setPermissions(Collections.singletonList(permission))
         .setRequestConditions(new ShareRequestConditions().setLeaseId(leaseId)),
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting access policies completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.
setAccessPolicyWithResponse(List<ShareSignedIdentifier> permissions, Duration timeout, Context context)

Sets stored access policies for the share.

Code Samples

Set a read only stored access policy

ShareAccessPolicy accessPolicy = new ShareAccessPolicy().setPermissions("r")
     .setStartsOn(OffsetDateTime.now(ZoneOffset.UTC))
     .setExpiresOn(OffsetDateTime.now(ZoneOffset.UTC).plusDays(10));

 ShareSignedIdentifier permission = new ShareSignedIdentifier().setId("mypolicy").setAccessPolicy(accessPolicy);

 Response<ShareInfo> response = shareClient.setAccessPolicyWithResponse(Collections.singletonList(permission),
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting access policies completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.
setMetadata(Map<String,String> metadata)

Sets the user-defined metadata to associate to the share.

If null is passed for the metadata it will clear the metadata associated to the share.

Code Samples

Set the metadata to "share:updatedMetadata"

shareClient.setMetadata(Collections.singletonMap("share", "updatedMetadata"));
 System.out.println("Setting the share metadata.");

Clear the metadata of the share

shareClient.setMetadata(null);
 System.out.println("Clear metadata completed.");

For more information, see the Azure Docs.
setMetadataWithResponse(ShareSetMetadataOptions options, Duration timeout, Context context)

Sets the user-defined metadata to associate to the share.

If null is passed for the metadata it will clear the metadata associated to the share.

Code Samples

Set the metadata to "share:updatedMetadata"

Response<ShareInfo> response = shareClient.setMetadataWithResponse(new ShareSetMetadataOptions()
         .setMetadata(Collections.singletonMap("share", "updatedMetadata"))
         .setRequestConditions(new ShareRequestConditions().setLeaseId(leaseId)),
     Duration.ofSeconds(1),
     new Context(key1, value1));
 System.out.printf("Setting the share metadata completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.
setMetadataWithResponse(Map<String,String> metadata, Duration timeout, Context context)

Sets the user-defined metadata to associate to the share.

If null is passed for the metadata it will clear the metadata associated to the share.

Code Samples

Set the metadata to "share:updatedMetadata"

Response<ShareInfo> response = shareClient.setMetadataWithResponse(
     Collections.singletonMap("share", "updatedMetadata"), Duration.ofSeconds(1),
     new Context(key1, value1));
 System.out.printf("Setting the share metadata completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.
setProperties(ShareSetPropertiesOptions options)

Sets the share's properties.

Code Samples

System.out.println("Setting the share access tier completed." + shareClient.setProperties(
     new ShareSetPropertiesOptions().setAccessTier(ShareAccessTier.HOT).setQuotaInGb(1024)));

For more information, see the Azure Docs.
setPropertiesWithResponse(ShareSetPropertiesOptions options, Duration timeout, Context context)

Sets the share's properties.

Code Samples

Response<ShareInfo> response = shareClient.setPropertiesWithResponse(
     new ShareSetPropertiesOptions().setAccessTier(ShareAccessTier.HOT).setQuotaInGb(1024),
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting the share access tier completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.
setQuota(int quotaInGB)

Sets the maximum size in GB that the share is allowed to grow.

Code Samples

Set the quota to 1024 GB

System.out.println("Setting the share quota completed." + shareClient.setQuota(1024));

For more information, see the Azure Docs.

Deprecated. Use setProperties(ShareSetPropertiesOptions options)
setQuotaWithResponse(int quotaInGB, Duration timeout, Context context)

Sets the maximum size in GB that the share is allowed to grow.

Code Samples

Set the quota to 1024 GB

Response<ShareInfo> response = shareClient.setQuotaWithResponse(1024,
     Duration.ofSeconds(1), new Context(key1, value1));
 System.out.printf("Setting the share quota completed with status code %d", response.getStatusCode());

For more information, see the Azure Docs.

Deprecated. Use setPropertiesWithResponse(ShareSetPropertiesOptions options, Duration timeout, Context context)

Inherited Members

java.lang.Object.clone() java.lang.Object.equals(java.lang.Object) java.lang.Object.finalize() java.lang.Object.getClass() java.lang.Object.hashCode() java.lang.Object.notify() java.lang.Object.notifyAll() java.lang.Object.toString() java.lang.Object.wait() java.lang.Object.wait(long) java.lang.Object.wait(long,int)

Applies to