com.microsoft.azure.storage.file

Class CloudFileShare

java.lang.Object

com.microsoft.azure.storage.file.CloudFileShare

public final class CloudFileShare
extends Object

Represents a share in the Microsoft Azure File service.

Shares hold directories, which are encapsulated as CloudFileDirectory objects, and directories hold files. Directories can also contain sub-directories.

Constructor Summary

Constructors

Constructor and Description
CloudFileShare(StorageUri storageUri) Creates an instance of the CloudFileShare class using the specified URI.
CloudFileShare(StorageUri storageUri, CloudFileClient client) Deprecated. as of 3.0.0. Please use CloudFileShare(StorageUri, StorageCredentials)
CloudFileShare(StorageUri storageUri, StorageCredentials credentials) Creates an instance of the CloudFileShare class using the specified StorageUri and credentials.
CloudFileShare(String shareName, CloudFileClient client) Deprecated. as of 3.0.0. Please use CloudFileClient.getShareReference(String)
CloudFileShare(URI uri) Creates an instance of the CloudFileShare class using the specified URI.
CloudFileShare(URI uri, CloudFileClient client) Deprecated. as of 3.0.0. Please use CloudFileShare(URI, StorageCredentials)
CloudFileShare(URI uri, StorageCredentials credentials) Creates an instance of the CloudFileShare class using the specified URI and credentials.

Method Summary

Methods

Modifier and Type	Method and Description
void	create() Creates the share.
void	create(FileRequestOptions options, OperationContext opContext) Creates the share using the specified options and operation context.
boolean	createIfNotExists() Creates the share if it does not exist.
boolean	createIfNotExists(FileRequestOptions options, OperationContext opContext) Creates the share if it does not exist, using the specified request options and operation context.
void	delete() Deletes the share.
void	delete(AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Deletes the share using the specified request options and operation context.
boolean	deleteIfExists() Deletes the share if it exists.
boolean	deleteIfExists(AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Deletes the share if it exists using the specified request options and operation context.
void	downloadAttributes() Downloads the share's attributes, which consist of metadata and properties.
void	downloadAttributes(AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Downloads the share's attributes, which consist of metadata and properties, using the specified request options and operation context.
FileSharePermissions	downloadPermissions() Downloads the permission settings for the share.
FileSharePermissions	downloadPermissions(AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Downloads the permissions settings for the share using the specified request options and operation context.
boolean	exists() Returns a value that indicates whether the share exists.
boolean	exists(AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Returns a value that indicates whether the share exists, using the specified request options and operation context.
String	generateSharedAccessSignature(SharedAccessFilePolicy policy, String groupPolicyIdentifier) Returns a shared access signature for the share.
HashMap<String,String>	getMetadata() Returns the metadata for the share.
String	getName() Returns the name of the share.
FileShareProperties	getProperties() Returns the properties for the share.
CloudFileDirectory	getRootDirectoryReference() Returns a reference to a CloudFileDirectory object that represents the root file directory within this share.
CloudFileClient	getServiceClient() Returns the File service client associated with this share.
ShareStats	getStats() Queries the service for this share's ShareStats.
ShareStats	getStats(FileRequestOptions options, OperationContext opContext) Queries the service for this share's ShareStats.
StorageUri	getStorageUri() Returns the list of URIs for all locations.
URI	getUri() Returns the URI for this share.
void	setMetadata(HashMap<String,String> metadata) Sets the metadata collection of name-value pairs to be set on the share with an uploadMetadata() call.
void	uploadMetadata() Uploads the share's metadata.
void	uploadMetadata(AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Uploads the share's metadata using the specified request options and operation context.
void	uploadPermissions(FileSharePermissions permissions) Uploads the share's permissions.
void	uploadPermissions(FileSharePermissions permissions, AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Uploads the share's permissions using the specified request options and operation context.
void	uploadProperties() Updates the share's properties on the storage service.
void	uploadProperties(AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Updates the share's properties using the request options, and operation context.

Methods inherited from class java.lang.Object

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

Constructor Detail

CloudFileShare

@Deprecated
public CloudFileShare(String shareName,
                         CloudFileClient client)
               throws URISyntaxException,
                      StorageException

Deprecated. as of 3.0.0. Please use CloudFileClient.getShareReference(String)

Creates an instance of the CloudFileShare class using the specified name and client.

Parameters:

shareName - A String which represents the name of the share, which must adhere to share naming rules. The share name should not include any path separator characters (/). Share names must be lowercase, between 3-63 characters long and must start with a letter or number. Share names may contain only letters, numbers, and the dash (-) character.

client - A CloudFileClient object that represents the associated service client, and that specifies the endpoint for the File service.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI constructed based on the shareName is invalid.

See Also:

Naming and Referencing Shares, Directories, Files, and Metadata

CloudFileShare

public CloudFileShare(URI uri)
               throws StorageException

Creates an instance of the CloudFileShare class using the specified URI.

Parameters:

uri - A java.net.URI object that represents the absolute URI of the share.

Throws:

StorageException - If a storage service error occurred.

CloudFileShare

public CloudFileShare(StorageUri storageUri)
               throws StorageException

Creates an instance of the CloudFileShare class using the specified URI.

Parameters:

storageUri - A StorageUri object which represents the absolute URI of the share.

Throws:

StorageException - If a storage service error occurred.

CloudFileShare

public CloudFileShare(URI uri,
              StorageCredentials credentials)
               throws StorageException

Creates an instance of the CloudFileShare class using the specified URI and credentials.

Parameters:

uri - A java.net.URI object that represents the absolute URI of the share.

credentials - A StorageCredentials object used to authenticate access.

Throws:

StorageException - If a storage service error occurred.

CloudFileShare

public CloudFileShare(StorageUri storageUri,
              StorageCredentials credentials)
               throws StorageException

Creates an instance of the CloudFileShare class using the specified StorageUri and credentials.

Parameters:

storageUri - A StorageUri object which represents the absolute StorageUri of the share.

credentials - A StorageCredentials object used to authenticate access.

Throws:

StorageException - If a storage service error occurred.

CloudFileShare

@Deprecated
public CloudFileShare(URI uri,
                         CloudFileClient client)
               throws StorageException,
                      URISyntaxException

Deprecated. as of 3.0.0. Please use CloudFileShare(URI, StorageCredentials)

Creates an instance of the CloudFileShare class using the specified URI and client.

Parameters:

uri - A java.net.URI object that represents the absolute URI of the share.

client - A CloudFileClient object that represents the associated service client, and that specifies the endpoint for the File service.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException

CloudFileShare

@Deprecated
public CloudFileShare(StorageUri storageUri,
                         CloudFileClient client)
               throws StorageException,
                      URISyntaxException

Deprecated. as of 3.0.0. Please use CloudFileShare(StorageUri, StorageCredentials)

Creates an instance of the CloudFileShare class using the specified URI and client.

Parameters:

storageUri - A StorageUri object which represents the absolute URI of the share.

client - A CloudFileClient object that represents the associated service client, and that specifies the endpoint for the File service.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException

Method Detail

create

@DoesServiceRequest
public void create()
            throws StorageException

Creates the share.

Throws:

StorageException - If a storage service error occurred.

create

@DoesServiceRequest
public void create(FileRequestOptions options,
                             OperationContext opContext)
            throws StorageException

Creates the share using the specified options and operation context.

Parameters:

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

StorageException - If a storage service error occurred.

createIfNotExists

@DoesServiceRequest
public boolean createIfNotExists()
                          throws StorageException

Creates the share if it does not exist.

Returns:

true if the share did not already exist and was created; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

createIfNotExists

@DoesServiceRequest
public boolean createIfNotExists(FileRequestOptions options,
                                           OperationContext opContext)
                          throws StorageException

Creates the share if it does not exist, using the specified request options and operation context.

Parameters:

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client (CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

true if the share did not already exist and was created; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

delete

@DoesServiceRequest
public void delete()
            throws StorageException

Deletes the share.

Throws:

StorageException - If a storage service error occurred.

delete

@DoesServiceRequest
public void delete(AccessCondition accessCondition,
                             FileRequestOptions options,
                             OperationContext opContext)
            throws StorageException

Deletes the share using the specified request options and operation context.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the share.

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

StorageException - If a storage service error occurred.

deleteIfExists

@DoesServiceRequest
public boolean deleteIfExists()
                       throws StorageException

Deletes the share if it exists.

Returns:

true if the share existed and was deleted; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

deleteIfExists

@DoesServiceRequest
public boolean deleteIfExists(AccessCondition accessCondition,
                                        FileRequestOptions options,
                                        OperationContext opContext)
                       throws StorageException

Deletes the share if it exists using the specified request options and operation context.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the share.

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

true if the share existed and was deleted; otherwise, false.

Throws:

StorageException - If a storage service error occurred.

downloadAttributes

@DoesServiceRequest
public void downloadAttributes()
                        throws StorageException

Downloads the share's attributes, which consist of metadata and properties.

Throws:

StorageException - If a storage service error occurred.

downloadAttributes

@DoesServiceRequest
public void downloadAttributes(AccessCondition accessCondition,
                                         FileRequestOptions options,
                                         OperationContext opContext)
                        throws StorageException

Downloads the share's attributes, which consist of metadata and properties, using the specified request options and operation context.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the share.

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

StorageException - If a storage service error occurred.

downloadPermissions

@DoesServiceRequest
public FileSharePermissions downloadPermissions()
                                         throws StorageException

Downloads the permission settings for the share.

Returns:

A FileSharePermissions object that represents the share's permissions.

Throws:

StorageException - If a storage service error occurred.

downloadPermissions

@DoesServiceRequest
public FileSharePermissions downloadPermissions(AccessCondition accessCondition,
                                                          FileRequestOptions options,
                                                          OperationContext opContext)
                                         throws StorageException

Downloads the permissions settings for the share using the specified request options and operation context.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the share.

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

A FileSharePermissions object that represents the share's permissions.

Throws:

StorageException - If a storage service error occurred.

getStats

@DoesServiceRequest
public ShareStats getStats()
                    throws StorageException

Queries the service for this share's ShareStats.

Returns:

A ShareStats object for the given storage service.

Throws:

StorageException - If a storage service error occurred.

getStats

@DoesServiceRequest
public ShareStats getStats(FileRequestOptions options,
                                     OperationContext opContext)
                    throws StorageException

Queries the service for this share's ShareStats.

Parameters:

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client (CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

A ShareStats object for the given storage service.

Throws:

StorageException - If a storage service error occurred.

exists

@DoesServiceRequest
public boolean exists()
               throws StorageException

Returns a value that indicates whether the share exists.

Returns:

true if the share exists, otherwise false.

Throws:

StorageException - If a storage service error occurred.

exists

@DoesServiceRequest
public boolean exists(AccessCondition accessCondition,
                                FileRequestOptions options,
                                OperationContext opContext)
               throws StorageException

Returns a value that indicates whether the share exists, using the specified request options and operation context.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the share.

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Returns:

true if the share exists, otherwise false.

Throws:

StorageException - If a storage service error occurred.

generateSharedAccessSignature

public String generateSharedAccessSignature(SharedAccessFilePolicy policy,
                                   String groupPolicyIdentifier)
                                     throws InvalidKeyException,
                                            StorageException

Returns a shared access signature for the share. Note this does not contain the leading "?".

Parameters:

policy - An SharedAccessFilePolicy object that represents the access policy for the shared access signature.

groupPolicyIdentifier - A String which represents the share-level access policy.

Returns:

A String which represents a shared access signature for the share.

Throws:

StorageException - If a storage service error occurred.

InvalidKeyException - If the key is invalid.

uploadMetadata

@DoesServiceRequest
public void uploadMetadata()
                    throws StorageException

Uploads the share's metadata.

Throws:

StorageException - If a storage service error occurred.

uploadMetadata

@DoesServiceRequest
public void uploadMetadata(AccessCondition accessCondition,
                                     FileRequestOptions options,
                                     OperationContext opContext)
                    throws StorageException

Uploads the share's metadata using the specified request options and operation context.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the share.

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

StorageException - If a storage service error occurred.

uploadProperties

@DoesServiceRequest
public final void uploadProperties()
                            throws StorageException

Updates the share's properties on the storage service.

Use downloadAttributes() to retrieve the latest values for the share's properties and metadata from the Microsoft Azure storage service.

Throws:

StorageException - If a storage service error occurred.

uploadProperties

@DoesServiceRequest
public final void uploadProperties(AccessCondition accessCondition,
                                       FileRequestOptions options,
                                       OperationContext opContext)
                            throws StorageException

Updates the share's properties using the request options, and operation context.

Use downloadAttributes() to retrieve the latest values for the share's properties and metadata from the Microsoft Azure storage service.

Parameters:

accessCondition - An AccessCondition object that represents the access conditions for the share.

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

StorageException - If a storage service error occurred.

uploadPermissions

@DoesServiceRequest
public void uploadPermissions(FileSharePermissions permissions)
                       throws StorageException

Uploads the share's permissions.

Parameters:

permissions - A FileSharePermissions object that represents the permissions to upload.

Throws:

StorageException - If a storage service error occurred.

uploadPermissions

@DoesServiceRequest
public void uploadPermissions(FileSharePermissions permissions,
                                        AccessCondition accessCondition,
                                        FileRequestOptions options,
                                        OperationContext opContext)
                       throws StorageException

Uploads the share's permissions using the specified request options and operation context.

Parameters:

permissions - A FileSharePermissions object that represents the permissions to upload.

accessCondition - An AccessCondition object that represents the access conditions for the share.

options - A FileRequestOptions object that specifies any additional options for the request. Specifying null will use the default request options from the associated service client ( CloudFileClient).

opContext - An OperationContext object that represents the context for the current operation. This object is used to track requests to the storage service, and to provide additional runtime information about the operation.

Throws:

StorageException - If a storage service error occurred.

getRootDirectoryReference

public CloudFileDirectory getRootDirectoryReference()
                                             throws StorageException,
                                                    URISyntaxException

Returns a reference to a CloudFileDirectory object that represents the root file directory within this share.

Returns:

A CloudFileDirectory reference to the root directory for this share.

Throws:

StorageException

URISyntaxException

getServiceClient

public CloudFileClient getServiceClient()

Returns the File service client associated with this share.

Returns:

A CloudFileClient object that represents the service client associated with this share.

getUri

public URI getUri()

Returns the URI for this share.

Returns:

The absolute URI to the share.

getStorageUri

public StorageUri getStorageUri()

Returns the list of URIs for all locations.

Returns:

A StorageUri object which represents the list of URIs for all locations.

getName

public String getName()

Returns the name of the share.

Returns:

A String that represents the name of the share.

getMetadata

public HashMap<String,String> getMetadata()

Returns the metadata for the share. This value is initialized with the metadata from the share by a call to downloadAttributes(), and is set on the share with a call to uploadMetadata().

Returns:

A java.util.HashMap object that represents the metadata for the share.

getProperties

public FileShareProperties getProperties()

Returns the properties for the share.

Returns:

A FileShareProperties object that represents the properties for the share.

setMetadata

public void setMetadata(HashMap<String,String> metadata)

Sets the metadata collection of name-value pairs to be set on the share with an uploadMetadata() call. This collection will overwrite any existing share metadata. If this is set to an empty collection, the share metadata will be cleared on an uploadMetadata() call.

Parameters:

metadata - A java.util.HashMap object that represents the metadata being assigned to the share.