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, StorageCredentials credentials) Creates an instance of the CloudFileShare class using the specified StorageUri and credentials.
CloudFileShare(String shareName, String snapshotID, CloudFileClient client) Creates an instance of the CloudFileShare class using the specified name and client.
CloudFileShare(URI uri) Creates an instance of the CloudFileShare class using the specified URI.
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.
CloudFileShare	createSnapshot() Creates a snapshot of the share.
CloudFileShare	createSnapshot(AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Creates a snapshot of the file share using the specified request options and operation context.
CloudFileShare	createSnapshot(HashMap<String,String> metadata, AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Creates a snapshot of the file share 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.
void	delete(DeleteShareSnapshotsOption deleteSnapshotsOption, AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Deletes the share using the specified snapshot and 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.
boolean	deleteIfExists(DeleteShareSnapshotsOption deleteSnapshotsOption, AccessCondition accessCondition, FileRequestOptions options, OperationContext opContext) Deletes the share if it exists, using the specified snapshot and 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.
String	generateSharedAccessSignature(SharedAccessFilePolicy policy, String groupPolicyIdentifier, IPRange ipRange, SharedAccessProtocols protocols) 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.
URI	getQualifiedUri() Returns the snapshot or shared access signature qualified URI for this 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.
String	getSnapshot() Returns the snapshotID for 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.
boolean	isSnapshot() Indicates whether this share is a snapshot.
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	setProperties(FileShareProperties properties) Sets the properties for the share.
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

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

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.

snapshotID - A String that represents the snapshot version, if applicable.

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.

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.

delete

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

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

A share that has snapshots cannot be deleted unless the snapshots are also deleted. If a share has snapshots, use the DeleteShareSnapshotsOption.INCLUDE_SNAPSHOTS value in the deleteSnapshotsOption parameter to include the snapshots when deleting the base share.

Parameters:

deleteSnapshotsOption - A DeleteShareSnapshotsOption object that indicates whether to delete only snapshots, or the share and its snapshots.

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.

deleteIfExists

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

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

A share that has snapshots cannot be deleted unless the snapshots are also deleted. If a share has snapshots, use the DeleteShareSnapshotsOption.INCLUDE_SNAPSHOTS value in the deleteSnapshotsOption parameter to include the snapshots when deleting the base share.

Parameters:

deleteSnapshotsOption - A DeleteShareSnapshotsOption object that indicates whether to delete only snapshots, or the share and its snapshots.

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.

createSnapshot

@DoesServiceRequest
public final CloudFileShare createSnapshot()
                                    throws StorageException

Creates a snapshot of the share.

Returns:

A CloudFileShare object that represents the snapshot of the share.

Throws:

StorageException - If a storage service error occurred.

createSnapshot

@DoesServiceRequest
public final CloudFileShare createSnapshot(AccessCondition accessCondition,
                                               FileRequestOptions options,
                                               OperationContext opContext)
                                    throws StorageException

Creates a snapshot of the file 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 CloudFileShare object that represents the snapshot of the file share.

Throws:

StorageException - If a storage service error occurred.

createSnapshot

@DoesServiceRequest
public final CloudFileShare createSnapshot(HashMap<String,String> metadata,
                                               AccessCondition accessCondition,
                                               FileRequestOptions options,
                                               OperationContext opContext)
                                    throws StorageException

Creates a snapshot of the file share using the specified request options and operation context.

Parameters:

metadata - A collection of name-value pairs defining the metadata of the snapshot, or null.

accessCondition - An AccessCondition object that represents the access conditions for the file 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 CloudFileShare object that represents the snapshot of the file share.

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.

generateSharedAccessSignature

public String generateSharedAccessSignature(SharedAccessFilePolicy policy,
                                   String groupPolicyIdentifier,
                                   IPRange ipRange,
                                   SharedAccessProtocols protocols)
                                     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.

ipRange - A IPRange object containing the range of allowed IP addresses.

protocols - A SharedAccessProtocols representing the allowed Internet protocols.

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.

getSnapshot

public final String getSnapshot()

Returns the snapshotID for this share.

Returns:

The snapshotID as a string for this share.

isSnapshot

public final boolean isSnapshot()

Indicates whether this share is a snapshot.

Returns:

true if the share is a snapshot, otherwise false.

See Also:

DeleteSnapshotsOption

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.

getQualifiedUri

public final URI getQualifiedUri()
                          throws URISyntaxException,
                                 StorageException

Returns the snapshot or shared access signature qualified URI for this share.

Returns:

A java.net.URI object that represents the snapshot or shared access signature.

Throws:

StorageException - If a storage service error occurred.

URISyntaxException - If the resource URI is invalid.

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.

setProperties

public void setProperties(FileShareProperties properties)

Sets the properties for the share.

Parameters:

properties - A FileShareProperties object that represents the properties being assigned to the share.