com.azure.storage.file.datalake

Class DataLakeServiceClient

java.lang.Object

com.azure.storage.file.datalake.DataLakeServiceClient

public class DataLakeServiceClient
extends Object

Client to a storage account. It may only be instantiated through a DataLakeServiceClientBuilder. This class does not hold any state about a particular storage account but is instead a convenient way of sending off appropriate requests to the resource on the service. It may also be used to construct URLs to file systems, files and directories.

This client contains operations on a data lake service account. Operations on a file system are available on DataLakeFileSystemClient through DataLakeServiceClient.getFileSystemClient(String), and operations on a file or directory are available on DataLakeFileClient and DataLakeDirectoryClient respectively.

Method Summary

Modifier and Type	Method and Description
DataLakeFileSystemClient	createFileSystem(String fileSystemName) Creates a new file system within a storage account.
com.azure.core.http.rest.Response<DataLakeFileSystemClient>	createFileSystemWithResponse(String fileSystemName, Map<String,String> metadata, PublicAccessType accessType, com.azure.core.util.Context context) Creates a new file system within a storage account.
void	deleteFileSystem(String fileSystemName) Deletes the specified file system in the storage account.
com.azure.core.http.rest.Response<Void>	deleteFileSystemWithResponse(String fileSystemName, DataLakeRequestConditions requestConditions, com.azure.core.util.Context context) Deletes the specified file system in the storage account.
String	generateAccountSas(com.azure.storage.common.sas.AccountSasSignatureValues accountSasSignatureValues) Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.
String	generateAccountSas(com.azure.storage.common.sas.AccountSasSignatureValues accountSasSignatureValues, com.azure.core.util.Context context) Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.
String	getAccountName() Get associated account name.
String	getAccountUrl() Gets the URL of the storage account represented by this client.
DataLakeFileSystemClient	getFileSystemClient(String fileSystemName) Initializes a DataLakeFileSystemClient object pointing to the specified file system.
com.azure.core.http.HttpPipeline	getHttpPipeline() Gets the HttpPipeline powering this client.
DataLakeServiceVersion	getServiceVersion() Gets the service version the client is using.
UserDelegationKey	getUserDelegationKey(OffsetDateTime start, OffsetDateTime expiry) Gets a user delegation key for use with this account's data lake storage.
com.azure.core.http.rest.Response<UserDelegationKey>	getUserDelegationKeyWithResponse(OffsetDateTime start, OffsetDateTime expiry, Duration timeout, com.azure.core.util.Context context) Gets a user delegation key for use with this account's data lake storage.
com.azure.core.http.rest.PagedIterable<FileSystemItem>	listFileSystems() Returns a lazy loaded list of file systems in this account.
com.azure.core.http.rest.PagedIterable<FileSystemItem>	listFileSystems(ListFileSystemsOptions options, Duration timeout) Returns a lazy loaded list of file systems in this account.
DataLakeFileSystemClient	undeleteFileSystem(String deletedFileSystemName, String deletedFileSystemVersion) Restores a previously deleted file system.
com.azure.core.http.rest.Response<DataLakeFileSystemClient>	undeleteFileSystemWithResponse(FileSystemUndeleteOptions options, Duration timeout, com.azure.core.util.Context context) Restores a previously deleted file system.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getFileSystemClient

public DataLakeFileSystemClient getFileSystemClient(String fileSystemName)

Initializes a DataLakeFileSystemClient object pointing to the specified file system. This method does not create a file system. It simply constructs the URL to the file system and offers access to methods relevant to file systems.

Code Samples

 DataLakeFileSystemClient dataLakeFileSystemClient = client.getFileSystemClient("fileSystemName");
 

Parameters:

fileSystemName - The name of the file system to point to.

Returns:

A DataLakeFileSystemClient object pointing to the specified file system

getHttpPipeline

public com.azure.core.http.HttpPipeline getHttpPipeline()

Gets the HttpPipeline powering this client.

Returns:

The pipeline.

getServiceVersion

public DataLakeServiceVersion getServiceVersion()

Gets the service version the client is using.

Returns:

the service version the client is using.

createFileSystem

public DataLakeFileSystemClient createFileSystem(String fileSystemName)

Creates a new file system within a storage account. If a file system with the same name already exists, the operation fails. For more information, see the Azure Docs.

Code Samples

 DataLakeFileSystemClient dataLakeFileSystemClient = client.createFileSystem("fileSystemName");
 

Parameters:

fileSystemName - Name of the file system to create

Returns:

The DataLakeFileSystemClient used to interact with the file system created.

createFileSystemWithResponse

public com.azure.core.http.rest.Response<DataLakeFileSystemClient> createFileSystemWithResponse(String fileSystemName,
                                                                                                Map<String,String> metadata,
                                                                                                PublicAccessType accessType,
                                                                                                com.azure.core.util.Context context)

Creates a new file system within a storage account. If a file system with the same name already exists, the operation fails. For more information, see the Azure Docs.

Code Samples

 Map<String, String> metadata = Collections.singletonMap("metadata", "value");
 Context context = new Context("Key", "Value");
 
 DataLakeFileSystemClient dataLakeFileSystemClient = client.createFileSystemWithResponse(
     "fileSystemName",
     metadata,
     PublicAccessType.CONTAINER,
     context).getValue();
 

Parameters:

fileSystemName - Name of the file system to create

metadata - Metadata to associate with the file system. If there is leading or trailing whitespace in any metadata key or value, it must be removed or encoded.

accessType - Specifies how the data in this file system is available to the public. See the x-ms-blob-public-access header in the Azure Docs for more information. Pass null for no public access.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A Response whose value contains the DataLakeFileSystemClient used to interact with the file system created.

deleteFileSystem

public void deleteFileSystem(String fileSystemName)

Deletes the specified file system in the storage account. If the file system doesn't exist the operation fails. For more information see the Azure Docs.

Code Samples

 try {
     client.deleteFileSystem("fileSystemName");
     System.out.printf("Delete file system completed with status %n");
 } catch (UnsupportedOperationException error) {
     System.out.printf("Delete file system failed: %s%n", error);
 }
 

Parameters:

fileSystemName - Name of the file system to delete

deleteFileSystemWithResponse

public com.azure.core.http.rest.Response<Void> deleteFileSystemWithResponse(String fileSystemName,
                                                                            DataLakeRequestConditions requestConditions,
                                                                            com.azure.core.util.Context context)

Deletes the specified file system in the storage account. If the file system doesn't exist the operation fails. For more information see the Azure Docs.

Code Samples

 Context context = new Context("Key", "Value");
 System.out.printf("Delete file system completed with status %d%n",
     client.deleteFileSystemWithResponse("fileSystemName", new DataLakeRequestConditions(), context)
         .getStatusCode());
 

Parameters:

fileSystemName - Name of the file system to delete

requestConditions - DataLakeRequestConditions

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A response containing status code and HTTP headers

getAccountUrl

public String getAccountUrl()

Gets the URL of the storage account represented by this client.

Returns:

the URL.

listFileSystems

public com.azure.core.http.rest.PagedIterable<FileSystemItem> listFileSystems()

Returns a lazy loaded list of file systems in this account. The returned PagedIterable can be consumed while new items are automatically retrieved as needed. For more information, see the Azure Docs.

Code Samples

 client.listFileSystems().forEach(fileSystem -> System.out.printf("Name: %s%n", fileSystem.getName()));
 

Returns:

The list of file systems.

listFileSystems

public com.azure.core.http.rest.PagedIterable<FileSystemItem> listFileSystems(ListFileSystemsOptions options,
                                                                              Duration timeout)

Returns a lazy loaded list of file systems in this account. The returned PagedIterable can be consumed while new items are automatically retrieved as needed. For more information, see the Azure Docs.

Code Samples

 ListFileSystemsOptions options = new ListFileSystemsOptions()
     .setPrefix("filSystemNamePrefixToMatch")
     .setDetails(new FileSystemListDetails().setRetrieveMetadata(true));
 
 client.listFileSystems(options, timeout).forEach(fileSystem -> System.out.printf("Name: %s%n",
     fileSystem.getName()));
 

Parameters:

options - A ListFileSystemsOptions which specifies what data should be returned by the service.

timeout - An optional timeout value beyond which a RuntimeException will be raised.

Returns:

The list of file systems.

getUserDelegationKey

public UserDelegationKey getUserDelegationKey(OffsetDateTime start,
                                              OffsetDateTime expiry)

Gets a user delegation key for use with this account's data lake storage. Note: This method call is only valid when using TokenCredential in this object's HttpPipeline.

Code Samples

 System.out.printf("User delegation key: %s%n",
     client.getUserDelegationKey(delegationKeyStartTime, delegationKeyExpiryTime));
 

Parameters:

start - Start time for the key's validity. Null indicates immediate start.

expiry - Expiration of the key's validity.

Returns:

The user delegation key.

getUserDelegationKeyWithResponse

public com.azure.core.http.rest.Response<UserDelegationKey> getUserDelegationKeyWithResponse(OffsetDateTime start,
                                                                                             OffsetDateTime expiry,
                                                                                             Duration timeout,
                                                                                             com.azure.core.util.Context context)

Gets a user delegation key for use with this account's data lake storage. Note: This method call is only valid when using TokenCredential in this object's HttpPipeline.

Code Samples

 System.out.printf("User delegation key: %s%n",
     client.getUserDelegationKeyWithResponse(delegationKeyStartTime, delegationKeyExpiryTime, timeout, context));
 

Parameters:

start - Start time for the key's validity. Null indicates immediate start.

expiry - Expiration of the key's validity.

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A Response whose value contains the user delegation key.

getAccountName

public String getAccountName()

Get associated account name.

Returns:

account name associated with this storage resource.

generateAccountSas

public String generateAccountSas(com.azure.storage.common.sas.AccountSasSignatureValues accountSasSignatureValues)

Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.

Note : The client must be authenticated via StorageSharedKeyCredential

See AccountSasSignatureValues for more information on how to construct an account SAS.

The snippet below generates a SAS that lasts for two days and gives the user read and list access to file systems and file shares.

 AccountSasPermission permissions = new AccountSasPermission()
     .setListPermission(true)
     .setReadPermission(true);
 AccountSasResourceType resourceTypes = new AccountSasResourceType().setContainer(true);
 AccountSasService services = new AccountSasService().setBlobAccess(true).setFileAccess(true);
 OffsetDateTime expiryTime = OffsetDateTime.now().plus(Duration.ofDays(2));
 
 AccountSasSignatureValues sasValues =
     new AccountSasSignatureValues(expiryTime, permissions, services, resourceTypes);
 
 // Client must be authenticated via StorageSharedKeyCredential
 String sas = client.generateAccountSas(sasValues);
 

Parameters:

accountSasSignatureValues - AccountSasSignatureValues

Returns:

A String representing the SAS query parameters.

generateAccountSas

public String generateAccountSas(com.azure.storage.common.sas.AccountSasSignatureValues accountSasSignatureValues,
                                 com.azure.core.util.Context context)

Generates an account SAS for the Azure Storage account using the specified AccountSasSignatureValues.

Note : The client must be authenticated via StorageSharedKeyCredential

See AccountSasSignatureValues for more information on how to construct an account SAS.

The snippet below generates a SAS that lasts for two days and gives the user read and list access to file systems and file shares.

 AccountSasPermission permissions = new AccountSasPermission()
     .setListPermission(true)
     .setReadPermission(true);
 AccountSasResourceType resourceTypes = new AccountSasResourceType().setContainer(true);
 AccountSasService services = new AccountSasService().setBlobAccess(true).setFileAccess(true);
 OffsetDateTime expiryTime = OffsetDateTime.now().plus(Duration.ofDays(2));
 
 AccountSasSignatureValues sasValues =
     new AccountSasSignatureValues(expiryTime, permissions, services, resourceTypes);
 
 // Client must be authenticated via StorageSharedKeyCredential
 String sas = client.generateAccountSas(sasValues, new Context("key", "value"));
 

Parameters:

accountSasSignatureValues - AccountSasSignatureValues

context - Additional context that is passed through the code when generating a SAS.

Returns:

A String representing the SAS query parameters.

undeleteFileSystem

public DataLakeFileSystemClient undeleteFileSystem(String deletedFileSystemName,
                                                   String deletedFileSystemVersion)

Restores a previously deleted file system. If the file system associated with provided deletedFileSystemName already exists, this call will result in a 409 (conflict). This API is only functional if Container Soft Delete is enabled for the storage account associated with the file system.

Code Samples

 ListFileSystemsOptions listFileSystemsOptions = new ListFileSystemsOptions();
 listFileSystemsOptions.getDetails().setRetrieveDeleted(true);
 client.listFileSystems(listFileSystemsOptions, null).forEach(
     deletedFileSystem -> {
         DataLakeFileSystemClient fileSystemClient = client.undeleteFileSystem(
             deletedFileSystem.getName(), deletedFileSystem.getVersion());
     }
 );
 

Parameters:

deletedFileSystemName - The name of the previously deleted file system.

deletedFileSystemVersion - The version of the previously deleted file system.

Returns:

The DataLakeFileSystemClient used to interact with the restored file system.

undeleteFileSystemWithResponse

public com.azure.core.http.rest.Response<DataLakeFileSystemClient> undeleteFileSystemWithResponse(FileSystemUndeleteOptions options,
                                                                                                  Duration timeout,
                                                                                                  com.azure.core.util.Context context)

Restores a previously deleted file system. The restored file system will be renamed to the destinationFileSystemName if provided in options. Otherwise deletedFileSystemName is used as destination file system name. If the file system associated with provided destinationFileSYstemName already exists, this call will result in a 409 (conflict). This API is only functional if Container Soft Delete is enabled for the storage account associated with the file system.

Code Samples

 ListFileSystemsOptions listFileSystemsOptions = new ListFileSystemsOptions();
 listFileSystemsOptions.getDetails().setRetrieveDeleted(true);
 client.listFileSystems(listFileSystemsOptions, null).forEach(
     deletedFileSystem -> {
         DataLakeFileSystemClient fileSystemClient = client.undeleteFileSystemWithResponse(
             new FileSystemUndeleteOptions(deletedFileSystem.getName(), deletedFileSystem.getVersion())
                 .setDestinationFileSystemName(deletedFileSystem.getName() + "V2"), timeout,
             context).getValue();
     }
 );
 

Parameters:

options - FileSystemUndeleteOptions.

timeout - An optional timeout value beyond which a RuntimeException will be raised.

context - Additional context that is passed through the Http pipeline during the service call.

Returns:

A Response whose value contains the DataLakeFileSystemClient used to interact with the restored file system.