com.emc.atmos.api.jersey

Class AtmosApiClient

java.lang.Object

com.emc.atmos.AbstractJerseyClient<AtmosConfig>

com.emc.atmos.api.AbstractAtmosApi

com.emc.atmos.api.jersey.AtmosApiClient

All Implemented Interfaces:

AtmosApi

Direct Known Subclasses:

AtmosApiBasicClient

public class AtmosApiClient
extends AbstractAtmosApi

Reference implementation of AtmosApi.

This implementation uses the JAX-RS reference implementation (Jersey) as it's REST client. When sending or receiving data, the following content handlers are supported by default. You may add your own MessageBodyReader/MessageBodyWriter implementations by using the optional constructor, however be sure to return a positive value from MessageBodyWriter.getSize() as this sets the content-length of the request, which is required by Atmos. Be sure to use the appropriate content-type associated with each object type or the handlers will not understand the request.

Object Type (class)	Expected Content-Type(s)
byte[]	*any*
java.lang.String	*any*
java.io.File (send-only)	*any*
java.io.InputStream (send-only)	*any*
com.emc.atmos.api.BufferSegment (send-only)	*any*
any annotated JAXB root element bean	text/xml, application/xml
com.emc.atmos.api.multipart.MultipartEntity (receive-only)	multipart/*

Also keep in mind that you can always send/receive byte[] and do your own conversion as that has always been supported.

Note: this implementation is not supported with Atmos versions below 1.4.2.

To use, simply pass a new AtmosConfig object to the constructor like so:

     URI atmosEndpoint = new URI( "http://api.atmosonline.com" ); // or use your private cloud endpoint/load balancer
     AtmosApi atmos = new AtmosApiClient( new AtmosConfig( "my_full_token_id", "my_secret_key", atmosEndpoint ) );
 

You can also specify multiple endpoints and have each request round-robin between them like so:

     URI endpoint1 = new URI( "https://10.0.0.101" ); // 1st Atmos node
     URI endpoint2 = new URI( "https://10.0.0.102" ); // 2nd Atmos node
     URI endpoint3 = new URI( "https://10.0.0.103" ); // 3rd Atmos node
     URI endpoint4 = new URI( "https://10.0.0.104" ); // 4th Atmos node
     AtmosApi atmos = new AtmosApiClient( new AtmosConfig( "my_full_token_id", "my_secret_key",
                                          endpoint1, endpoint2, endpoint3, endpoint4 ) );
 

To create an object, simply pass the object in to one of the createObject methods. The object type must be one of the supported types above.

     String stringContent = "Hello World!";
     ObjectId oid1 = atmos.createObject( stringContent, "text/plain" );

     File fileContent = new File( "spreadsheet.xls" );
     ObjectId oid2 = atmos.createObject( fileContent, "application/vnd.ms-excel" );

     byte[] binaryContent;
     ... // load binary content to store as an object
     ObjectId oid3 = atmos.createObject( binaryContent, null ); // default content-type is application/octet-stream
 

To read an object, specify the type of object you want to receive from a readObject method. The same rules apply to this type.

     String stringContent = atmos.readObject( oid1, String.class );

     byte[] fileContent = atmos.readObject( oid2, byte[].class );
     // do something with file content (stream to client? save in local filesystem?)

     byte[] binaryContent = atmos.readObject( oid3, byte[].class );
 

Field Summary

Fields

Modifier and Type	Field and Description
protected com.sun.jersey.api.client.Client	client
protected com.sun.jersey.api.client.Client	client100

Fields inherited from class com.emc.atmos.api.AbstractAtmosApi

DEFAULT_CONTENT_TYPE

Fields inherited from class com.emc.atmos.AbstractJerseyClient

config

Constructor Summary

Constructors

Modifier	Constructor and Description
	AtmosApiClient(AtmosConfig config)
protected	AtmosApiClient(AtmosConfig config, com.sun.jersey.api.client.Client client, com.sun.jersey.api.client.Client client100)
	AtmosApiClient(AtmosConfig config, java.util.List<java.lang.Class<javax.ws.rs.ext.MessageBodyReader<?>>> readers, java.util.List<java.lang.Class<javax.ws.rs.ext.MessageBodyWriter<?>>> writers)

Method Summary

Modifier and Type	Method and Description
void	addClientFilter(com.sun.jersey.api.client.filter.ClientFilter filter) Adds a ClientFilter to the Jersey client used to make REST requests.
protected com.sun.jersey.api.client.WebResource.Builder	addHeaders(com.sun.jersey.api.client.WebResource.Builder builder, java.util.Map<java.lang.String,java.util.List<java.lang.Object>> headers)
protected com.sun.jersey.api.client.WebResource.Builder	build(Request request)
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.
protected com.sun.jersey.api.client.Client	createClient(AtmosConfig config)
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.
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	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.
Acl	getAcl(ObjectIdentifier identifier) Gets the ACL for the specified object.
protected java.lang.Object	getContent(ContentRequest request)
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.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.
<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.
BasicResponse	updateObject(UpdateObjectRequest request) Updates an object's content in the cloud using all of the options provided in the request object.

Methods inherited from class com.emc.atmos.api.AbstractAtmosApi

createObject, createObject, deleteAccessToken, getAccessToken, getShareableUrl, getShareableUrl, preSignRequest, readObject, readObject, updateObject, updateObject

Methods inherited from class com.emc.atmos.AbstractJerseyClient

buildRequest, executeAndClose, fillResponse

Methods inherited from class java.lang.Object

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

Field Detail

client

protected com.sun.jersey.api.client.Client client

client100

protected com.sun.jersey.api.client.Client client100

Constructor Detail

AtmosApiClient

public AtmosApiClient(AtmosConfig config)

AtmosApiClient

public AtmosApiClient(AtmosConfig config,
                      java.util.List<java.lang.Class<javax.ws.rs.ext.MessageBodyReader<?>>> readers,
                      java.util.List<java.lang.Class<javax.ws.rs.ext.MessageBodyWriter<?>>> writers)

AtmosApiClient

protected AtmosApiClient(AtmosConfig config,
                         com.sun.jersey.api.client.Client client,
                         com.sun.jersey.api.client.Client client100)

Method Detail

createClient

protected com.sun.jersey.api.client.Client createClient(AtmosConfig config)

Specified by:

createClient in class AbstractJerseyClient<AtmosConfig>

addClientFilter

public void addClientFilter(com.sun.jersey.api.client.filter.ClientFilter filter)

Adds a ClientFilter to the Jersey client used to make REST requests. Useful to provide your own in-line content or header manipulation.

getServiceInformation

public ServiceInformation getServiceInformation()

calculateServerClockSkew

public long calculateServerClockSkew()

Description copied from interface: AtmosApi

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

public CreateObjectResponse createObject(CreateObjectRequest request)

Description copied from interface: AtmosApi

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

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

Description copied from interface: AtmosApi

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

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

Description copied from interface: AtmosApi

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

public BasicResponse updateObject(UpdateObjectRequest request)

Description copied from interface: AtmosApi

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

public void delete(ObjectIdentifier identifier)

Description copied from interface: AtmosApi

Deletes an object from the cloud

Parameters:

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

createDirectory

public ObjectId createDirectory(ObjectPath path)

Description copied from interface: AtmosApi

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

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

Description copied from interface: AtmosApi

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

public ListDirectoryResponse listDirectory(ListDirectoryRequest request)

Description copied from interface: AtmosApi

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

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

Description copied from interface: AtmosApi

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

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

Description copied from interface: AtmosApi

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

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

Description copied from interface: AtmosApi

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

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

Description copied from interface: AtmosApi

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

public boolean objectExists(ObjectIdentifier identifier)

Description copied from interface: AtmosApi

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

public ObjectMetadata getObjectMetadata(ObjectIdentifier identifier)

Description copied from interface: AtmosApi

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

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

Description copied from interface: AtmosApi

Adds or replaces user metadata associated with the specified object. Note that this method will not delete metadata. That must be done via AtmosApi.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

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

Description copied from interface: AtmosApi

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

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

Description copied from interface: AtmosApi

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

public ListObjectsResponse listObjects(ListObjectsRequest request)

Description copied from interface: AtmosApi

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

public Acl getAcl(ObjectIdentifier identifier)

Description copied from interface: AtmosApi

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

public void setAcl(ObjectIdentifier identifier,
                   Acl acl)

Description copied from interface: AtmosApi

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

public ObjectInfo getObjectInfo(ObjectIdentifier identifier)

Description copied from interface: AtmosApi

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

public ObjectId createVersion(ObjectIdentifier identifier)

Description copied from interface: AtmosApi

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

public ListVersionsResponse listVersions(ListVersionsRequest request)

Description copied from interface: AtmosApi

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

public void restoreVersion(ObjectId objectId,
                           ObjectId versionId)

Description copied from interface: AtmosApi

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

public void deleteVersion(ObjectId versionId)

Description copied from interface: AtmosApi

Deletes the specified object version.

Parameters:

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

createAccessToken

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

Description copied from interface: AtmosApi

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

public GetAccessTokenResponse getAccessToken(java.lang.String accessTokenId)

Description copied from interface: AtmosApi

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

public void deleteAccessToken(java.lang.String accessTokenId)

Description copied from interface: AtmosApi

Deletes the specified access token.

Parameters:

accessTokenId - The ID of the access token.

listAccessTokens

public ListAccessTokensResponse listAccessTokens(ListAccessTokensRequest request)

Description copied from interface: AtmosApi

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.

execute

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

Description copied from interface: AtmosApi

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 AtmosApi.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.

build

protected com.sun.jersey.api.client.WebResource.Builder build(Request request)

addHeaders

protected com.sun.jersey.api.client.WebResource.Builder addHeaders(com.sun.jersey.api.client.WebResource.Builder builder,
                                                                   java.util.Map<java.lang.String,java.util.List<java.lang.Object>> headers)

getContent

protected java.lang.Object getContent(ContentRequest request)

createSubtenant

public java.lang.String createSubtenant(CreateSubtenantRequest request)

Description copied from interface: AtmosApi

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

public void deleteSubtenant(java.lang.String subtenantId)

Description copied from interface: AtmosApi

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