com.emc.atmos.api

Interface AtmosApi

All Known Implementing Classes:

AbstractAtmosApi, AtmosApiBasicClient, AtmosApiClient, AtmosEncryptionClient

public interface AtmosApi

This interface defines the basic operations available through the Atmos REST web service.

Method Summary

Modifier and Type	Method and Description
long	calculateServerClockSkew() Calculates rough clock skew.
CreateAccessTokenResponse	createAccessToken(CreateAccessTokenRequest request) Creates an anonymous access token using all of the options provided in the request object.
ObjectId	createDirectory(ObjectPath path) Creates a directory in the subtenant namespace using the specified path.
ObjectId	createDirectory(ObjectPath path, Acl acl, Metadata... metadata) Creates a directory in the subtenant namespace using the specified path, acl and metadata.
CreateObjectResponse	createObject(CreateObjectRequest request) Creates a new object in the cloud using all of the options provided in the request object.
ObjectId	createObject(ObjectIdentifier identifier, java.lang.Object content, java.lang.String contentType) Creates a new object in the cloud with the specified identifier.
ObjectId	createObject(java.lang.Object content, java.lang.String contentType) Creates a new object in the cloud.
java.lang.String	createSubtenant(CreateSubtenantRequest request) Creates a new Atmos Subtenant in ECS.
ObjectId	createVersion(ObjectIdentifier identifier) Creates a new immutable version (snapshot) of the specified object from its current state.
void	delete(ObjectIdentifier identifier) Deletes an object from the cloud
void	deleteAccessToken(java.lang.String accessTokenId) Deletes the specified access token.
void	deleteAccessToken(java.net.URL url) Deletes the specified access token.
void	deleteSubtenant(java.lang.String subtenantId) Deletes an Atmos Subtenant in ECS.
void	deleteUserMetadata(ObjectIdentifier identifier, java.lang.String... names) Deletes metadata associated with the specified object.
void	deleteVersion(ObjectId versionId) Deletes the specified object version.
<T> GenericResponse<T>	execute(PreSignedRequest request, java.lang.Class<T> resultType, java.lang.Object content) Executes a pre-signed request, sending the specified content as a body (if provided) and returning the specified resultType (if provided).
GetAccessTokenResponse	getAccessToken(java.lang.String accessTokenId) Retrieves details about the specified access token.
GetAccessTokenResponse	getAccessToken(java.net.URL url) Retrieves details about the specified access token.
Acl	getAcl(ObjectIdentifier identifier) Gets the ACL for the specified object.
ObjectInfo	getObjectInfo(ObjectIdentifier identifier) Gets storage information for the specified object.
ObjectMetadata	getObjectMetadata(ObjectIdentifier identifier) Gets an object's metadata, ACL and content-type all in one call.
ServiceInformation	getServiceInformation()
java.net.URL	getShareableUrl(ObjectIdentifier identifier, java.util.Date expirationDate) Constructs a pre-signed URL to an object, which anyone can then use to retrieve the object.
java.net.URL	getShareableUrl(ObjectIdentifier identifier, java.util.Date expirationDate, java.lang.String disposition) Constructs a shareable URL with a specific content-disposition.
java.util.Map<java.lang.String,Metadata>	getSystemMetadata(ObjectIdentifier identifier, java.lang.String... metadataNames) Gets the system metadata associated with the specified object.
java.util.Map<java.lang.String,Metadata>	getUserMetadata(ObjectIdentifier identifier, java.lang.String... metadataNames) Gets the user metadata associated with the specified object.
java.util.Map<java.lang.String,java.lang.Boolean>	getUserMetadataNames(ObjectIdentifier identifier) Lists the names of all metadata associated with the specified object.
ListAccessTokensResponse	listAccessTokens(ListAccessTokensRequest request) Lists all access tokens owned by the user using all of the options provided in the request object.
ListDirectoryResponse	listDirectory(ListDirectoryRequest request) Lists the contents of a directory in the namespace.
java.util.Set<java.lang.String>	listMetadata(java.lang.String metadataName) Lists the children of the specified metadata path in the hierarchy of listable metadata for the subtenant.
ListObjectsResponse	listObjects(ListObjectsRequest request) Lists all objects that are assigned the specified listable metadata using all of the options provided in the request object.
ListVersionsResponse	listVersions(ListVersionsRequest request) Lists all versions (snapshots) of the specified object using all of the options provided in the request object.
void	move(ObjectPath oldPath, ObjectPath newPath, boolean overwrite) Moves an object in the namespace to a new location.
boolean	objectExists(ObjectIdentifier identifier) Determines whether an object exists with the specified identifier.
PreSignedRequest	preSignRequest(Request request, java.util.Date expiration) Pre-signs a request with a specified expiration time.
<T> T	readObject(ObjectIdentifier identifier, java.lang.Class<T> objectType) Reads an object's entire content from the cloud.
<T> T	readObject(ObjectIdentifier identifier, Range range, java.lang.Class<T> objectType) Reads an object's content from the cloud.
<T> ReadObjectResponse<T>	readObject(ReadObjectRequest request, java.lang.Class<T> objectType) Reads an object's content from the cloud using all of the options provided in the request object.
ReadObjectResponse<java.io.InputStream>	readObjectStream(ObjectIdentifier identifier, Range range) Provides an InputStream to read an object's content from the cloud.
void	restoreVersion(ObjectId objectId, ObjectId versionId) Restores the specified version (snapshot) of the specified object so that the object's current state reflects that of the version.
void	setAcl(ObjectIdentifier identifier, Acl acl) Sets the ACL for the specified object.
void	setUserMetadata(ObjectIdentifier identifier, Metadata... metadata) Adds or replaces user metadata associated with the specified object.
void	updateObject(ObjectIdentifier identifier, java.lang.Object content) Updates an object's content in the cloud.
void	updateObject(ObjectIdentifier identifier, java.lang.Object content, Range range) Updates an object's content in the cloud.
BasicResponse	updateObject(UpdateObjectRequest request) Updates an object's content in the cloud using all of the options provided in the request object.

Method Detail

getServiceInformation

ServiceInformation getServiceInformation()

calculateServerClockSkew

long calculateServerClockSkew()

Calculates rough clock skew. Implementations will likely use the date response header from an inert HTTP request.

Returns:

The clock skew between the target Atmos node and the local machine.

createObject

ObjectId createObject(java.lang.Object content,
                      java.lang.String contentType)

Creates a new object in the cloud.

Parameters:

content - The initial content of the object. May be appended to later. May be null to create an object with no content. The content object can be any object type that is supported by the implementation.

contentType - the MIME type of the content. Optional, may be null. If null, defaults to application/octet-stream.

Returns:

ObjectId of the newly created object.

createObject

ObjectId createObject(ObjectIdentifier identifier,
                      java.lang.Object content,
                      java.lang.String contentType)

Creates a new object in the cloud with the specified identifier.

Parameters:

identifier - The identifier to use for the new object. This may be an ObjectPath or an ObjectKey.

content - The initial content of the object. May be appended to later. May be null to create an object with no content. The content object can be any object type that is supported by the implementation.

contentType - the MIME type of the content. Optional, may be null. If null, defaults to application/octet-stream.

Returns:

ObjectId of the newly created object.

createObject

CreateObjectResponse createObject(CreateObjectRequest request)

Creates a new object in the cloud using all of the options provided in the request object.

Parameters:

request - The request object (click on the class name to get more information).

Returns:

The response received from Atmos. This object contains the ObjectId of the newly created object plus additional details about the response, such as headers (click on the class name to get more information).

readObject

<T> T readObject(ObjectIdentifier identifier,
                 java.lang.Class<T> objectType)
          throws java.io.IOException

Reads an object's entire content from the cloud.

Parameters:

identifier - The identifier of the object to read. May be any ObjectIdentifier.

objectType - The type of object to return. This can be any object type supported by the implementation.

Returns:

An object (of type objectType) representing the content of the object in the cloud.

Throws:

java.io.IOException - if an exception occurs while reading the object. Note that IOExceptions are generally retried automatically (configured in AtmosConfig).

readObject

<T> T readObject(ObjectIdentifier identifier,
                 Range range,
                 java.lang.Class<T> objectType)
          throws java.io.IOException

Reads an object's content from the cloud.

Parameters:

identifier - The identifier of the object to read. May be any ObjectIdentifier.

range - (optional) The range of bytes to read from the object. A null value will read the entire object.

objectType - The type of object to return. This can be any object type supported by the implementation.

Returns:

An object (of type objectType) representing the content of the object in the cloud.

Throws:

java.io.IOException - if an exception occurs while reading the object. Note that IOExceptions are generally retried automatically (configured in AtmosConfig).

readObject

<T> ReadObjectResponse<T> readObject(ReadObjectRequest request,
                                     java.lang.Class<T> objectType)
                              throws java.io.IOException

Reads an object's content from the cloud using all of the options provided in the request object.

Parameters:

request - The request object (click on the class name to get more information)

objectType - The type of object to return. This can be any object type supported by the implementation.

Returns:

The response received from Atmos. This object contains an object (of type objectType) representing the content of the object in the cloud, plus additional details about the response, such as headers (click on the class name to get more information).

Throws:

java.io.IOException - if an exception occurs while reading the object. Note that IOExceptions are generally retried automatically (configured in AtmosConfig).

readObjectStream

ReadObjectResponse<java.io.InputStream> readObjectStream(ObjectIdentifier identifier,
                                                         Range range)

Provides an InputStream to read an object's content from the cloud.

Parameters:

identifier - The identifier of the object to read. May be any ObjectIdentifier.

range - (optional) The range of bytes to read from the object. A null value will read the entire object.

Returns:

The response received from Atmos. This object contains the InputStream to read the object from the cloud, plus additional details about the response, such as headers (click on the class name to get more information).

updateObject

void updateObject(ObjectIdentifier identifier,
                  java.lang.Object content)

Updates an object's content in the cloud.

Parameters:

identifier - The identifier of the object to update. May be any ObjectIdentifier.

content - The new content of the object. The content object can be any object type that is supported by the implementation.

updateObject

void updateObject(ObjectIdentifier identifier,
                  java.lang.Object content,
                  Range range)

Updates an object's content in the cloud.

Parameters:

identifier - The identifier of the object to update. May be any ObjectIdentifier.

content - The new content of the object. The content object can be any object type that is supported by the implementation.

range - (optional) The portion of the object to update (expressed as a range of bytes). A null value will overwrite the entire object.

updateObject

BasicResponse updateObject(UpdateObjectRequest request)

Updates an object's content in the cloud using all of the options provided in the request object.

Parameters:

request - The request object (click on the class name to get more information)

Returns:

The response received from Atmos. This object contains details about the response, such as headers (click on the class name to get more information).

delete

void delete(ObjectIdentifier identifier)

Deletes an object from the cloud

Parameters:

identifier - The identifier of the object to delete. May be any ObjectIdentifier.

createDirectory

ObjectId createDirectory(ObjectPath path)

Creates a directory in the subtenant namespace using the specified path.

Parameters:

path - The path of the directory to create.

Returns:

The ObjectId of the newly created directory.

createDirectory

ObjectId createDirectory(ObjectPath path,
                         Acl acl,
                         Metadata... metadata)

Creates a directory in the subtenant namespace using the specified path, acl and metadata.

Parameters:

path - The path of the directory to create.

acl - The ACL to assign to the new directory.

metadata - The metadata to associate with the new directory.

Returns:

The ObjectId of the newly created directory.

listDirectory

ListDirectoryResponse listDirectory(ListDirectoryRequest request)

Lists the contents of a directory in the namespace.

Parameters:

request - The request object (click on the class name to get more information)

Returns:

The response received from Atmos. This object contains the list of directory entries, plus details about the response, such as headers (click on the class name to get more information). Note that if a paging token is present in the response, it will be set on the request object.

move

void move(ObjectPath oldPath,
          ObjectPath newPath,
          boolean overwrite)

Moves an object in the namespace to a new location.

Parameters:

oldPath - The existing path of the object.

newPath - The new path that the object should have.

overwrite - If true and an object already exists at newPath, this call will overwrite that object.

getUserMetadataNames

java.util.Map<java.lang.String,java.lang.Boolean> getUserMetadataNames(ObjectIdentifier identifier)

Lists the names of all metadata associated with the specified object.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

Returns:

A list of the names of all user metadata associated with the object.

getUserMetadata

java.util.Map<java.lang.String,Metadata> getUserMetadata(ObjectIdentifier identifier,
                                                         java.lang.String... metadataNames)

Gets the user metadata associated with the specified object.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

metadataNames - (optional) Constrains the result to include only the metadata named in this list.

Returns:

A map of metadata names to Metadata objects.

getSystemMetadata

java.util.Map<java.lang.String,Metadata> getSystemMetadata(ObjectIdentifier identifier,
                                                           java.lang.String... metadataNames)

Gets the system metadata associated with the specified object.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

metadataNames - (optional) Constrains the result to include only the metadata named in this list.

Returns:

A map of metadata names to Metadata objects.

objectExists

boolean objectExists(ObjectIdentifier identifier)

Determines whether an object exists with the specified identifier. Implementations will probably make a get-system-metadata call and return false if the server returns a 404.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

Returns:

true if an object exists in the cloud with the specified identifier.

getObjectMetadata

ObjectMetadata getObjectMetadata(ObjectIdentifier identifier)

Gets an object's metadata, ACL and content-type all in one call.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

Returns:

Object metadata (click on the class for more information).

setUserMetadata

void setUserMetadata(ObjectIdentifier identifier,
                     Metadata... metadata)

Adds or replaces user metadata associated with the specified object. Note that this method will not delete metadata. That must be done via deleteUserMetadata(ObjectIdentifier, String...).

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

metadata - The metadata to add to or replace on the object.

deleteUserMetadata

void deleteUserMetadata(ObjectIdentifier identifier,
                        java.lang.String... names)

Deletes metadata associated with the specified object.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

names - The names of the metadata to delete/remove from the object.

listMetadata

java.util.Set<java.lang.String> listMetadata(java.lang.String metadataName)

Lists the children of the specified metadata path in the hierarchy of listable metadata for the subtenant. For example, if a hierarchy of listable metadata exists as such: /ford/mustang/gt, then listing "ford" would probably yield "mustang", "f150", "crown victoria", etc.

Parameters:

metadataName - The metadata name (sometime called a "tag") whose children should be returned. If null, all root-level names will be returned (i.e. "ford", "chevy", "chrysler").

Returns:

The names of all children of the specified listable metadata path.

listObjects

ListObjectsResponse listObjects(ListObjectsRequest request)

Lists all objects that are assigned the specified listable metadata using all of the options provided in the request object.

Parameters:

request - The request object (click on the class name to get more information)

Returns:

The response received from Atmos. This object contains the list of object entries, plus details about the response, such as headers (click on the class name to get more information). Note that if a paging token is present in the response, it will be set on the request object.

getAcl

Acl getAcl(ObjectIdentifier identifier)

Gets the ACL for the specified object.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

Returns:

The ACL for the specified object.

setAcl

void setAcl(ObjectIdentifier identifier,
            Acl acl)

Sets the ACL for the specified object.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

acl - The new ACL for the specified object.

getObjectInfo

ObjectInfo getObjectInfo(ObjectIdentifier identifier)

Gets storage information for the specified object.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

Returns:

Storage information for the specified object.

createVersion

ObjectId createVersion(ObjectIdentifier identifier)

Creates a new immutable version (snapshot) of the specified object from its current state.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

Returns:

The ObjectId of the new version. Use this identifier to retrieve the snapshot created by this call.

listVersions

ListVersionsResponse listVersions(ListVersionsRequest request)

Lists all versions (snapshots) of the specified object using all of the options provided in the request object.

Parameters:

request - The request object (click on the class name to get more information)

Returns:

The response received from Atmos. This object contains the list of object versions, plus details about the response, such as headers (click on the class name to get more information). Note that if a paging token is present in the response, it will be set on the request object.

restoreVersion

void restoreVersion(ObjectId objectId,
                    ObjectId versionId)

Restores the specified version (snapshot) of the specified object so that the object's current state reflects that of the version. Note this will overwrite the current state of the object.

Parameters:

objectId - The ObjectId of the object.

versionId - The ObjectId of the version (must be a version of the specified object).

deleteVersion

void deleteVersion(ObjectId versionId)

Deletes the specified object version.

Parameters:

versionId - The ObjectId of the version to delete (must point to a version and not an object).

getShareableUrl

java.net.URL getShareableUrl(ObjectIdentifier identifier,
                             java.util.Date expirationDate)
                      throws java.net.MalformedURLException

Constructs a pre-signed URL to an object, which anyone can then use to retrieve the object. The URL expires at the specified time and is tamper proof. However, it does reveal the full tokenId of the user. If this is undesirable and the Atmos cloud is at version 2.1 and above, look at createAccessToken(com.emc.atmos.api.request.CreateAccessTokenRequest).

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

expirationDate - The date at which the generated URL will no longer be valid.

Returns:

A public URL that will retrieve the contents of the specified object until expirationDate.

Throws:

java.net.MalformedURLException - if the configured Atmos endpoint is syntactically invalid.

getShareableUrl

java.net.URL getShareableUrl(ObjectIdentifier identifier,
                             java.util.Date expirationDate,
                             java.lang.String disposition)
                      throws java.net.MalformedURLException

Constructs a shareable URL with a specific content-disposition. The disposition value will be set in the Content-Disposition header of the response when the URL is accessed. Requires the browser-compat feature, check ServiceInformation for supported features.

Parameters:

identifier - The identifier of the object. Can be any ObjectIdentifier.

expirationDate - The date at which the generated URL will no longer be valid.

disposition - the value of the Content-Disposition header, e.g. "attachment; filename=\"filename.txt\""

Returns:

A public URL that will retrieve the contents of the specified object and set the specified content-disposition until expirationDate.

Throws:

java.net.MalformedURLException - if the configured Atmos endpoint is syntactically invalid.

createAccessToken

CreateAccessTokenResponse createAccessToken(CreateAccessTokenRequest request)
                                     throws java.net.MalformedURLException

Creates an anonymous access token using all of the options provided in the request object.

Parameters:

request - The request object (click on the class name to get more information)

Returns:

The response received from Atmos. This object contains the access token URL, plus details about the response, such as headers (click on the class name to get more information).

Throws:

java.net.MalformedURLException - if the configured Atmos endpoint is syntactically invalid.

getAccessToken

GetAccessTokenResponse getAccessToken(java.net.URL url)

Retrieves details about the specified access token. Implementation simply extracts the token ID from the URL and calls getAccessToken(String).

Parameters:

url - The URL of the access token.

Returns:

The response received from Atmos. This object contains the AccessToken, plus details about the response, such as headers (click on the class name to get more information).

getAccessToken

GetAccessTokenResponse getAccessToken(java.lang.String accessTokenId)

Retrieves details about the specified access token.

Parameters:

accessTokenId - The ID of the access token.

Returns:

The response received from Atmos. This object contains the AccessToken, plus details about the response, such as headers (click on the class name to get more information).

deleteAccessToken

void deleteAccessToken(java.net.URL url)

Deletes the specified access token. Implementation simply extracts the token ID from the URL and calls deleteAccessToken(String).

Parameters:

url - The URL of the access token.

deleteAccessToken

void deleteAccessToken(java.lang.String accessTokenId)

Deletes the specified access token.

Parameters:

accessTokenId - The ID of the access token.

listAccessTokens

ListAccessTokensResponse listAccessTokens(ListAccessTokensRequest request)

Lists all access tokens owned by the user using all of the options provided in the request object.

Parameters:

request - The request object (click on the class name to get more information)

Returns:

The response received from Atmos. This object contains the list of access tokens, plus details about the response, such as headers (click on the class name to get more information). Note that if a paging token is present in the response, it will be set on the request object.

preSignRequest

PreSignedRequest preSignRequest(Request request,
                                java.util.Date expiration)
                         throws java.net.MalformedURLException

Pre-signs a request with a specified expiration time. The pre-signed request can be executed at a later time via the execute(com.emc.atmos.api.request.PreSignedRequest, Class, Object) method. This feature is useful if you intend to serialize the pre-signed request to some other system which does not have access to Atmos credentials.

Parameters:

request - the request to pre-sign (can be executed at a later time)

expiration - the date at which the pre-signed request becomes invalid and will no longer be accepted

Returns:

a pre-signed request that can be executed at a later time and expires at expiration

Throws:

java.net.MalformedURLException - if the configured Atmos endpoint is syntactically invalid.

execute

<T> GenericResponse<T> execute(PreSignedRequest request,
                               java.lang.Class<T> resultType,
                               java.lang.Object content)
                        throws java.net.URISyntaxException

Executes a pre-signed request, sending the specified content as a body (if provided) and returning the specified resultType (if provided). The content object and result type can be any object type that is supported by the implementation.

Parameters:

request - A pre-signed request generated by calling preSignRequest(com.emc.atmos.api.request.Request, java.util.Date).

resultType - (optional) The type of object to return. This can be any object type supported by the implementation.

content - (optional) The body content to send in the request (i.e. the object content for a create-object request). Can be any object type supported by the implementation.

Returns:

The response received from Atmos. This object contains an object (of type resultType) representing the content of the response (i.e. the object content of a read-object request), plus additional details about the response, such as headers (click on the class name to get more information).

Throws:

java.net.URISyntaxException - if the URL in the pre-signed request is syntactically invalid.

createSubtenant

java.lang.String createSubtenant(CreateSubtenantRequest request)

Creates a new Atmos Subtenant in ECS. This operation is not supported on pure Atmos systems.

Parameters:

request - The CreateSubtenantRequest containing the parameters for the new subtenant.

Returns:

The ID of the new subtenant, e.g. "75077194912140aaa95911c237103695"

deleteSubtenant

void deleteSubtenant(java.lang.String subtenantId)

Deletes an Atmos Subtenant in ECS. This operation is not supported on pure Atmos systems. Note: the subtenant must be completely empty before deleting.