com.rackspacecloud.client.cloudfiles
Class FilesClient

java.lang.Object
  extended by com.rackspacecloud.client.cloudfiles.FilesClient
Direct Known Subclasses:
FilesClientExt

public class FilesClient
extends java.lang.Object

A client for Cloud Files. Here follows a basic example of logging in, creating a container and an object, retrieving the object, and then deleting both the object and container. For more examples, see the code in com.rackspacecloud.client.cloudfiles.sample, which contains a series of examples.

 
  //  Create the client object for username "jdoe", password "johnsdogsname". 
        FilesClient myClient = FilesClient("jdoe", "johnsdogsname");
 
  // Log in (login() will return false if the login was unsuccessful.
  assert(myClient.login());
 
  // Make sure there are no containers in the account
  assert(myClient.listContainers.length() == 0);
  
  // Create the container
  assert(myClient.createContainer("myContainer"));
  
  // Now we should have one
  assert(myClient.listContainers.length() == 1);
  
  // Upload the file "alpaca.jpg"
  assert(myClient.storeObject("myContainer", new File("alapca.jpg"), "image/jpeg"));
  
  // Download "alpaca.jpg"
  FilesObject obj = myClient.getObject("myContainer", "alpaca.jpg");
  byte data[] = obj.getObject();
  
  // Clean up after ourselves.
  // Note:  Order here is important, you can't delete non-empty containers.
  assert(myClient.deleteObject("myContainer", "alpaca.jpg"));
  assert(myClient.deleteContainer("myContainer");
 


Field Summary
protected  java.lang.String apikey
           
protected  java.lang.String authenticationURL
           
protected  java.lang.String authToken
           
protected  org.apache.http.client.HttpClient client
           
protected  int connectionTimeOut
           
protected  java.lang.String email
           
protected  boolean isLoggedin
           
protected static org.apache.log4j.Logger logger
           
protected  java.lang.String storageURL
           
protected  boolean useETag
           
static java.lang.String VERSION
           
 
Constructor Summary
FilesClient()
          This method uses the default connection time out of CONNECTON_TIMEOUT and username, password, and account from FilesUtil
FilesClient(org.apache.http.client.HttpClient client, java.lang.String email, java.lang.String apikey, java.lang.String authUrl, int connectionTimeOut)
           
FilesClient(java.lang.String email, java.lang.String apikey)
          Mosso-style authentication (No accounts).
FilesClient(java.lang.String email, java.lang.String apikey, java.lang.String authUrl)
          This method uses the default connection time out of CONNECTON_TIMEOUT.
FilesClient(java.lang.String email, java.lang.String apikey, java.lang.String authUrl, int connectionTimeOut)
           
 
Method Summary
 boolean containerExists(java.lang.String container)
          Convenience method to test for the existence of a container in Cloud Files.
 java.lang.String copyObject(java.lang.String sourceContainer, java.lang.String sourceObjName, java.lang.String destContainer, java.lang.String destObjName)
          This method copies the object found in the source container with the source object name to the destination container with the destination object name.
 void createContainer(java.lang.String name)
          Creates a container
 void createFullPath(java.lang.String container, java.lang.String path)
          Create all of the path elements for the entire tree for a given path.
 boolean createManifestObject(java.lang.String container, java.lang.String contentType, java.lang.String name, java.lang.String manifest, IFilesTransferCallback callback)
          Create a manifest on the server, including metadata
 boolean createManifestObject(java.lang.String container, java.lang.String contentType, java.lang.String name, java.lang.String manifest, java.util.Map<java.lang.String,java.lang.String> metadata)
          Create a manifest on the server, including metadata
 boolean createManifestObject(java.lang.String container, java.lang.String contentType, java.lang.String name, java.lang.String manifest, java.util.Map<java.lang.String,java.lang.String> metadata, IFilesTransferCallback callback)
          Create a manifest on the server, including metadata
 void createPath(java.lang.String container, java.lang.String path)
          Creates a path (but not any of the sub portions of the path)
 boolean deleteContainer(java.lang.String name)
          Deletes a container
 void deleteObject(java.lang.String container, java.lang.String objName)
          Delete the given object from it's container.
 FilesAccountInfo getAccountInfo()
          Gets information for the given account.
 java.lang.String getAuthenticationURL()
          The URL we will use for Authentication
 java.lang.String getAuthToken()
           
 int getConnectionTimeOut()
           
 FilesContainerInfo getContainerInfo(java.lang.String container)
          Get basic information on a container (number of items and the total size).
 byte[] getObject(java.lang.String container, java.lang.String objName)
          Get the content of the given object
 java.io.InputStream getObjectAsRangedStream(java.lang.String container, java.lang.String objName, long offset, long length)
           
 java.io.InputStream getObjectAsStream(java.lang.String container, java.lang.String objName)
          Get's the given object's content as a stream
 FilesObjectMetaData getObjectMetaData(java.lang.String container, java.lang.String objName)
          Get an object's metadata
 java.lang.String getPassword()
          The password the client will use for the login.
 java.lang.String getStorageToken()
          Deprecated. 
 java.lang.String getStorageURL()
           
 boolean getUseETag()
           
 java.lang.String getUserAgent()
           
 java.lang.String getUserName()
          The username we are logged in with.
 boolean isLoggedin()
          Has this instance of the client authenticated itself?
static boolean isValidContainerName(java.lang.String name)
           
static boolean isValidObjectName(java.lang.String name)
           
 java.util.List<FilesContainer> listContainers()
          List the containers available in an account.
 java.util.List<FilesContainer> listContainers(int limit)
          List the containers available in an account.
 java.util.List<FilesContainer> listContainers(int limit, java.lang.String marker)
          List the containers available in an account.
 java.util.List<FilesContainerInfo> listContainersInfo()
          List all of the containers available in an account, ordered by container name.
 java.util.List<FilesContainerInfo> listContainersInfo(int limit)
          List the containers available in an account, ordered by container name.
 java.util.List<FilesContainerInfo> listContainersInfo(int limit, java.lang.String marker)
          List the containers available in an account, ordered by container name.
 java.util.List<FilesObject> listObjects(java.lang.String container)
          List the objects in a container in lexicographic order.
 java.util.List<FilesObject> listObjects(java.lang.String container, java.lang.Character delimiter)
          List the objects in a container in lexicographic order.
 java.util.List<FilesObject> listObjects(java.lang.String container, int limit)
          List the objects in a container in lexicographic order.
 java.util.List<FilesObject> listObjects(java.lang.String container, int limit, java.lang.String marker)
          List the objects in a container in lexicographic order.
 java.util.List<FilesObject> listObjects(java.lang.String container, java.lang.String path)
          List the objects in a container in lexicographic order.
 java.util.List<FilesObject> listObjects(java.lang.String container, java.lang.String path, java.lang.Character delimiter)
          List the objects in a container in lexicographic order.
 java.util.List<FilesObject> listObjects(java.lang.String container, java.lang.String path, int limit)
          List the objects in a container in lexicographic order.
 java.util.List<FilesObject> listObjects(java.lang.String container, java.lang.String path, int limit, java.lang.String marker)
          List the objects in a container in lexicographic order.
 java.util.List<FilesObject> listObjectsStartingWith(java.lang.String container, java.lang.String startsWith, java.lang.String path, int limit, java.lang.String marker)
          List all of the objects in a container with the given starting string.
 java.util.List<FilesObject> listObjectsStartingWith(java.lang.String container, java.lang.String startsWith, java.lang.String path, int limit, java.lang.String marker, java.lang.Character delimiter)
          List all of the objects in a container with the given starting string.
 boolean login()
          Log in to CloudFiles.
 boolean login(java.lang.String authToken, java.lang.String storageURL)
          Log in to CloudFiles.
static java.lang.String md5Sum(byte[] data)
          Calculates the MD5 checksum of an array of data
static java.lang.String md5Sum(java.io.File f)
          Calculates the MD5 checksum of a file, returned as a hex encoded string
static java.lang.String sanitizeAndPreserveSlashes(java.lang.String str)
           
static java.lang.String sanitizeForURI(java.lang.String str)
          Encode any unicode characters that will cause us problems.
 void setAuthenticationURL(java.lang.String authenticationURL)
          Changes the URL of the authentication service.
 void setConnectionTimeOut(int connectionTimeOut)
          The timeout we will use for communicating with the server (in milliseconds)
 void setPassword(java.lang.String password)
          Set's the password for this client.
 void setUseETag(boolean useETag)
           
 void setUserAgent(java.lang.String userAgent)
           
 void setUserName(java.lang.String email)
          Set's the username for this client.
 boolean storeObject(java.lang.String container, byte[] obj, java.lang.String contentType, java.lang.String name, java.util.Map<java.lang.String,java.lang.String> metadata)
          Store a file on the server, including metadata
 boolean storeObject(java.lang.String container, byte[] obj, java.lang.String contentType, java.lang.String name, java.util.Map<java.lang.String,java.lang.String> metadata, IFilesTransferCallback callback)
          Store a file on the server, including metadata
 java.lang.String storeObject(java.lang.String container, java.io.File obj, java.lang.String contentType)
          Copies the file to Cloud Files, keeping the original file name in Cloud Files.
 java.lang.String storeObjectAs(java.lang.String container, java.io.File obj, java.lang.String contentType, java.lang.String name)
          Store a file on the server
 java.lang.String storeObjectAs(java.lang.String container, java.io.File obj, java.lang.String contentType, java.lang.String name, IFilesTransferCallback callback)
          Store a file on the server
 java.lang.String storeObjectAs(java.lang.String container, java.io.File obj, java.lang.String contentType, java.lang.String name, java.util.Map<java.lang.String,java.lang.String> metadata)
          Store a file on the server, including metadata
 java.lang.String storeObjectAs(java.lang.String container, java.io.File obj, java.lang.String contentType, java.lang.String name, java.util.Map<java.lang.String,java.lang.String> metadata, IFilesTransferCallback callback)
          Store a file on the server, including metadata
 java.lang.String storeObjectAs(java.lang.String container, java.lang.String name, org.apache.http.HttpEntity entity, java.util.Map<java.lang.String,java.lang.String> metadata, java.lang.String md5sum)
           
 java.lang.String storeStreamedObject(java.lang.String container, java.io.InputStream data, java.lang.String contentType, java.lang.String name, java.util.Map<java.lang.String,java.lang.String> metadata)
          Store a file on the server, including metadata, with the contents coming from an input stream.
static java.lang.String unencodeURI(java.lang.String str)
           
 boolean updateObjectManifest(java.lang.String container, java.lang.String object, java.lang.String manifest)
           
 boolean updateObjectMetadata(java.lang.String container, java.lang.String object, java.util.Map<java.lang.String,java.lang.String> metadata)
           
 boolean updateObjectMetadataAndManifest(java.lang.String container, java.lang.String object, java.util.Map<java.lang.String,java.lang.String> metadata, java.lang.String manifest)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final java.lang.String VERSION
See Also:
Constant Field Values

email

protected java.lang.String email

apikey

protected java.lang.String apikey

authenticationURL

protected java.lang.String authenticationURL

connectionTimeOut

protected int connectionTimeOut

storageURL

protected java.lang.String storageURL

authToken

protected java.lang.String authToken

isLoggedin

protected boolean isLoggedin

useETag

protected boolean useETag

client

protected org.apache.http.client.HttpClient client

logger

protected static org.apache.log4j.Logger logger
Constructor Detail

FilesClient

public FilesClient(org.apache.http.client.HttpClient client,
                   java.lang.String email,
                   java.lang.String apikey,
                   java.lang.String authUrl,
                   int connectionTimeOut)
Parameters:
client - The HttpClient to talk to Swift
email - The username to log in to
apikey - The password
authUrl - The Cloud Files account to use
connectionTimeOut - The connection timeout, in ms.

FilesClient

public FilesClient(java.lang.String email,
                   java.lang.String apikey,
                   java.lang.String authUrl,
                   int connectionTimeOut)
Parameters:
email - The username to log in to
apikey - The password
authUrl - The Cloud Files account to use
connectionTimeOut - The connection timeout, in ms.

FilesClient

public FilesClient(java.lang.String email,
                   java.lang.String apikey,
                   java.lang.String authUrl)
This method uses the default connection time out of CONNECTON_TIMEOUT. If account is null, "Mosso Style" authentication is assumed, otherwise standard Cloud Files authentication is used.

Parameters:
email -
apikey -
authUrl -

FilesClient

public FilesClient(java.lang.String email,
                   java.lang.String apikey)
Mosso-style authentication (No accounts).

Parameters:
email - Your CloudFiles username
apikey - Your CloudFiles API Access Key

FilesClient

public FilesClient()
This method uses the default connection time out of CONNECTON_TIMEOUT and username, password, and account from FilesUtil

Method Detail

login

public boolean login()
              throws java.io.IOException,
                     org.apache.http.HttpException
Log in to CloudFiles. This method performs the authentication and sets up the client's internal state.

Returns:
true if the login was successful, false otherwise.
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol

login

public boolean login(java.lang.String authToken,
                     java.lang.String storageURL)
              throws java.io.IOException,
                     org.apache.http.HttpException
Log in to CloudFiles. This method performs the authentication and sets up the client's internal state.

Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol

listContainersInfo

public java.util.List<FilesContainerInfo> listContainersInfo()
                                                      throws java.io.IOException,
                                                             org.apache.http.HttpException,
                                                             FilesAuthorizationException,
                                                             FilesException
List all of the containers available in an account, ordered by container name.

Returns:
null if the user is not logged in or the Account is not found. A List of FSContainers with all of the containers in the account. if there are no containers in the account, the list will be zero length.
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listContainersInfo

public java.util.List<FilesContainerInfo> listContainersInfo(int limit)
                                                      throws java.io.IOException,
                                                             org.apache.http.HttpException,
                                                             FilesAuthorizationException,
                                                             FilesException
List the containers available in an account, ordered by container name.

Parameters:
limit - The maximum number of containers to return. -1 returns an unlimited number.
Returns:
null if the user is not logged in or the Account is not found. A List of FSContainers with all of the containers in the account. if there are no containers in the account, the list will be zero length.
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listContainersInfo

public java.util.List<FilesContainerInfo> listContainersInfo(int limit,
                                                             java.lang.String marker)
                                                      throws java.io.IOException,
                                                             org.apache.http.HttpException,
                                                             FilesAuthorizationException,
                                                             FilesException
List the containers available in an account, ordered by container name.

Parameters:
limit - The maximum number of containers to return. -1 returns an unlimited number.
marker - Return containers that occur after this lexicographically.
Returns:
null if the user is not logged in or the Account is not found. A List of FSContainers with all of the containers in the account. if there are no containers in the account, the list will be zero length.
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listContainers

public java.util.List<FilesContainer> listContainers()
                                              throws java.io.IOException,
                                                     org.apache.http.HttpException,
                                                     FilesAuthorizationException,
                                                     FilesException
List the containers available in an account.

Returns:
null if the user is not logged in or the Account is not found. A List of FilesContainer with all of the containers in the account. if there are no containers in the account, the list will be zero length.
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listContainers

public java.util.List<FilesContainer> listContainers(int limit)
                                              throws java.io.IOException,
                                                     org.apache.http.HttpException,
                                                     FilesAuthorizationException,
                                                     FilesException
List the containers available in an account.

Parameters:
limit - The maximum number of containers to return. -1 denotes no limit.
Returns:
null if the user is not logged in or the Account is not found. A List of FilesContainer with all of the containers in the account. if there are no containers in the account, the list will be zero length.
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listContainers

public java.util.List<FilesContainer> listContainers(int limit,
                                                     java.lang.String marker)
                                              throws java.io.IOException,
                                                     org.apache.http.HttpException,
                                                     FilesException
List the containers available in an account.

Parameters:
limit - The maximum number of containers to return. -1 denotes no limit.
marker - Only return containers after this container. Null denotes starting at the beginning (lexicographically).
Returns:
A List of FilesContainer with all of the containers in the account. if there are no containers in the account, the list will be zero length.
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listObjectsStartingWith

public java.util.List<FilesObject> listObjectsStartingWith(java.lang.String container,
                                                           java.lang.String startsWith,
                                                           java.lang.String path,
                                                           int limit,
                                                           java.lang.String marker)
                                                    throws java.io.IOException,
                                                           FilesException
List all of the objects in a container with the given starting string.

Parameters:
container - The container name
startsWith - The string to start with
path - Only look for objects in this path
limit - Return at most limit objects
marker - Returns objects lexicographically greater than marker. Used in conjunction with limit to paginate the list.
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listObjectsStartingWith

public java.util.List<FilesObject> listObjectsStartingWith(java.lang.String container,
                                                           java.lang.String startsWith,
                                                           java.lang.String path,
                                                           int limit,
                                                           java.lang.String marker,
                                                           java.lang.Character delimiter)
                                                    throws java.io.IOException,
                                                           FilesException
List all of the objects in a container with the given starting string.

Parameters:
container - The container name
startsWith - The string to start with
path - Only look for objects in this path
limit - Return at most limit objects
marker - Returns objects lexicographically greater than marker. Used in conjunction with limit to paginate the list.
delimiter - Use this argument as the delimiter that separates "directories"
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listObjects

public java.util.List<FilesObject> listObjects(java.lang.String container)
                                        throws java.io.IOException,
                                               FilesAuthorizationException,
                                               FilesException
List the objects in a container in lexicographic order.

Parameters:
container - The container name
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listObjects

public java.util.List<FilesObject> listObjects(java.lang.String container,
                                               java.lang.Character delimiter)
                                        throws java.io.IOException,
                                               FilesAuthorizationException,
                                               FilesException
List the objects in a container in lexicographic order.

Parameters:
container - The container name
delimiter - Use this argument as the delimiter that separates "directories"
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listObjects

public java.util.List<FilesObject> listObjects(java.lang.String container,
                                               int limit)
                                        throws java.io.IOException,
                                               org.apache.http.HttpException,
                                               FilesAuthorizationException,
                                               FilesException
List the objects in a container in lexicographic order.

Parameters:
container - The container name
limit - Return at most limit objects
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listObjects

public java.util.List<FilesObject> listObjects(java.lang.String container,
                                               java.lang.String path)
                                        throws java.io.IOException,
                                               org.apache.http.HttpException,
                                               FilesAuthorizationException,
                                               FilesException
List the objects in a container in lexicographic order.

Parameters:
container - The container name
path - Only look for objects in this path
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException

listObjects

public java.util.List<FilesObject> listObjects(java.lang.String container,
                                               java.lang.String path,
                                               java.lang.Character delimiter)
                                        throws java.io.IOException,
                                               org.apache.http.HttpException,
                                               FilesAuthorizationException,
                                               FilesException
List the objects in a container in lexicographic order.

Parameters:
container - The container name
path - Only look for objects in this path
delimiter - Use this argument as the delimiter that separates "directories"
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException

listObjects

public java.util.List<FilesObject> listObjects(java.lang.String container,
                                               java.lang.String path,
                                               int limit)
                                        throws java.io.IOException,
                                               org.apache.http.HttpException,
                                               FilesAuthorizationException,
                                               FilesException
List the objects in a container in lexicographic order.

Parameters:
container - The container name
path - Only look for objects in this path
limit - Return at most limit objects
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

listObjects

public java.util.List<FilesObject> listObjects(java.lang.String container,
                                               java.lang.String path,
                                               int limit,
                                               java.lang.String marker)
                                        throws java.io.IOException,
                                               org.apache.http.HttpException,
                                               FilesAuthorizationException,
                                               FilesException
List the objects in a container in lexicographic order.

Parameters:
container - The container name
path - Only look for objects in this path
limit - Return at most limit objects
marker - Returns objects lexicographically greater than marker. Used in conjunction with limit to paginate the list.
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException

listObjects

public java.util.List<FilesObject> listObjects(java.lang.String container,
                                               int limit,
                                               java.lang.String marker)
                                        throws java.io.IOException,
                                               org.apache.http.HttpException,
                                               FilesAuthorizationException,
                                               FilesException
List the objects in a container in lexicographic order.

Parameters:
container - The container name
limit - Return at most limit objects
marker - Returns objects lexicographically greater than marker. Used in conjunction with limit to paginate the list.
Returns:
A list of FilesObjects starting with the given string
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

containerExists

public boolean containerExists(java.lang.String container)
                        throws java.io.IOException,
                               org.apache.http.HttpException
Convenience method to test for the existence of a container in Cloud Files.

Parameters:
container -
Returns:
true if the container exists. false otherwise.
Throws:
java.io.IOException
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol

getAccountInfo

public FilesAccountInfo getAccountInfo()
                                throws java.io.IOException,
                                       org.apache.http.HttpException,
                                       FilesAuthorizationException,
                                       FilesException
Gets information for the given account.

Returns:
The FilesAccountInfo with information about the number of containers and number of bytes used by the given account.
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException - There was another error in the request to the server.
FilesAuthorizationException - The client's login was invalid.

getContainerInfo

public FilesContainerInfo getContainerInfo(java.lang.String container)
                                    throws java.io.IOException,
                                           org.apache.http.HttpException,
                                           FilesException
Get basic information on a container (number of items and the total size).

Parameters:
container - The container to get information for
Returns:
ContainerInfo object of the container is present or null if its not present
Throws:
java.io.IOException - There was a socket level exception while talking to CloudFiles
org.apache.http.HttpException - There was an protocol level exception while talking to Cloudfiles
FilesNotFoundException - The container was not found
FilesAuthorizationException - The client was not logged in or the log in expired.
FilesException

createContainer

public void createContainer(java.lang.String name)
                     throws java.io.IOException,
                            org.apache.http.HttpException,
                            FilesAuthorizationException,
                            FilesException
Creates a container

Parameters:
name - The name of the container to be created
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesAuthorizationException - The client was not property logged in
FilesInvalidNameException - The container name was invalid
FilesException

deleteContainer

public boolean deleteContainer(java.lang.String name)
                        throws java.io.IOException,
                               org.apache.http.HttpException,
                               FilesAuthorizationException,
                               FilesInvalidNameException,
                               FilesNotFoundException,
                               FilesContainerNotEmptyException
Deletes a container

Parameters:
name - The name of the container
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesAuthorizationException - The user is not Logged in
FilesInvalidNameException - The container name is invalid
FilesNotFoundException - The container doesn't exist
FilesContainerNotEmptyException - The container was not empty

createPath

public void createPath(java.lang.String container,
                       java.lang.String path)
                throws org.apache.http.HttpException,
                       java.io.IOException,
                       FilesException
Creates a path (but not any of the sub portions of the path)

Parameters:
container - The name of the container.
path - The name of the Path
Throws:
org.apache.http.HttpException - There was an error at the protocol layer while talking to CloudFiles
java.io.IOException - There was an error at the socket layer while talking to CloudFiles
FilesException - There was another error while taking to the CloudFiles server

createFullPath

public void createFullPath(java.lang.String container,
                           java.lang.String path)
                    throws org.apache.http.HttpException,
                           java.io.IOException,
                           FilesException
Create all of the path elements for the entire tree for a given path. Thus, createFullPath("myContainer", "foo/bar/baz") creates the paths "foo", "foo/bar" and "foo/bar/baz".

Parameters:
container - The name of the container
path - The full name of the path
Throws:
org.apache.http.HttpException - There was an error at the protocol layer while talking to CloudFiles
java.io.IOException - There was an error at the socket layer while talking to CloudFiles
FilesException - There was another error while taking to the CloudFiles server

createManifestObject

public boolean createManifestObject(java.lang.String container,
                                    java.lang.String contentType,
                                    java.lang.String name,
                                    java.lang.String manifest,
                                    IFilesTransferCallback callback)
                             throws java.io.IOException,
                                    org.apache.http.HttpException,
                                    FilesException
Create a manifest on the server, including metadata

Parameters:
container - The name of the container
contentType - The MIME type of the file
name - The name of the file on the server
manifest - Set manifest content here
callback - The object to which any callbacks will be sent (null if you don't want callbacks)
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

createManifestObject

public boolean createManifestObject(java.lang.String container,
                                    java.lang.String contentType,
                                    java.lang.String name,
                                    java.lang.String manifest,
                                    java.util.Map<java.lang.String,java.lang.String> metadata)
                             throws java.io.IOException,
                                    org.apache.http.HttpException,
                                    FilesException
Create a manifest on the server, including metadata

Parameters:
container - The name of the container
contentType - The MIME type of the file
name - The name of the file on the server
manifest - Set manifest content here
metadata - A map with the metadata as key names and values as the metadata values
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

createManifestObject

public boolean createManifestObject(java.lang.String container,
                                    java.lang.String contentType,
                                    java.lang.String name,
                                    java.lang.String manifest,
                                    java.util.Map<java.lang.String,java.lang.String> metadata,
                                    IFilesTransferCallback callback)
                             throws java.io.IOException,
                                    org.apache.http.HttpException,
                                    FilesException
Create a manifest on the server, including metadata

Parameters:
container - The name of the container
contentType - The MIME type of the file
name - The name of the file on the server
manifest - Set manifest content here
metadata - A map with the metadata as key names and values as the metadata values
callback - The object to which any callbacks will be sent (null if you don't want callbacks)
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

storeObjectAs

public java.lang.String storeObjectAs(java.lang.String container,
                                      java.io.File obj,
                                      java.lang.String contentType,
                                      java.lang.String name)
                               throws java.io.IOException,
                                      org.apache.http.HttpException,
                                      FilesException
Store a file on the server

Parameters:
container - The name of the container
obj - The File containing the file to copy over
contentType - The MIME type of the file
name - The name of the file on the server
Returns:
The ETAG if the save was successful, null otherwise
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

storeObjectAs

public java.lang.String storeObjectAs(java.lang.String container,
                                      java.io.File obj,
                                      java.lang.String contentType,
                                      java.lang.String name,
                                      IFilesTransferCallback callback)
                               throws java.io.IOException,
                                      org.apache.http.HttpException,
                                      FilesException
Store a file on the server

Parameters:
container - The name of the container
obj - The File containing the file to copy over
contentType - The MIME type of the file
name - The name of the file on the server
Returns:
The ETAG if the save was successful, null otherwise
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

storeObjectAs

public java.lang.String storeObjectAs(java.lang.String container,
                                      java.io.File obj,
                                      java.lang.String contentType,
                                      java.lang.String name,
                                      java.util.Map<java.lang.String,java.lang.String> metadata)
                               throws java.io.IOException,
                                      org.apache.http.HttpException,
                                      FilesException
Store a file on the server, including metadata

Parameters:
container - The name of the container
obj - The File containing the file to copy over
contentType - The MIME type of the file
name - The name of the file on the server
metadata - A map with the metadata as key names and values as the metadata values
Returns:
The ETAG if the save was successful, null otherwise
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesAuthorizationException
FilesException

storeObjectAs

public java.lang.String storeObjectAs(java.lang.String container,
                                      java.io.File obj,
                                      java.lang.String contentType,
                                      java.lang.String name,
                                      java.util.Map<java.lang.String,java.lang.String> metadata,
                                      IFilesTransferCallback callback)
                               throws java.io.IOException,
                                      org.apache.http.HttpException,
                                      FilesException
Store a file on the server, including metadata

Parameters:
container - The name of the container
obj - The File containing the file to copy over
contentType - The MIME type of the file
name - The name of the file on the server
metadata - A map with the metadata as key names and values as the metadata values
callback - The callback object that will be called as the data is sent
Returns:
The ETAG if the save was successful, null otherwise
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

storeObject

public java.lang.String storeObject(java.lang.String container,
                                    java.io.File obj,
                                    java.lang.String contentType)
                             throws java.io.IOException,
                                    org.apache.http.HttpException,
                                    FilesException
Copies the file to Cloud Files, keeping the original file name in Cloud Files.

Parameters:
container - The name of the container to place the file in
obj - The File to transfer
contentType - The file's MIME type
Returns:
The ETAG if the save was successful, null otherwise
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

storeObject

public boolean storeObject(java.lang.String container,
                           byte[] obj,
                           java.lang.String contentType,
                           java.lang.String name,
                           java.util.Map<java.lang.String,java.lang.String> metadata)
                    throws java.io.IOException,
                           org.apache.http.HttpException,
                           FilesException
Store a file on the server, including metadata

Parameters:
container - The name of the container
obj - The File containing the file to copy over
contentType - The MIME type of the file
name - The name of the file on the server
metadata - A map with the metadata as key names and values as the metadata values
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

storeObject

public boolean storeObject(java.lang.String container,
                           byte[] obj,
                           java.lang.String contentType,
                           java.lang.String name,
                           java.util.Map<java.lang.String,java.lang.String> metadata,
                           IFilesTransferCallback callback)
                    throws java.io.IOException,
                           org.apache.http.HttpException,
                           FilesException
Store a file on the server, including metadata

Parameters:
container - The name of the container
obj - The File containing the file to copy over
contentType - The MIME type of the file
name - The name of the file on the server
metadata - A map with the metadata as key names and values as the metadata values
callback - The object to which any callbacks will be sent (null if you don't want callbacks)
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

storeStreamedObject

public java.lang.String storeStreamedObject(java.lang.String container,
                                            java.io.InputStream data,
                                            java.lang.String contentType,
                                            java.lang.String name,
                                            java.util.Map<java.lang.String,java.lang.String> metadata)
                                     throws java.io.IOException,
                                            org.apache.http.HttpException,
                                            FilesException
Store a file on the server, including metadata, with the contents coming from an input stream. This allows you to not know the entire length of your content when you start to write it. Nor do you have to hold it entirely in memory at the same time.

Parameters:
container - The name of the container
data - Any object that implements InputStream
contentType - The MIME type of the file
name - The name of the file on the server
metadata - A map with the metadata as key names and values as the metadata values
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException

storeObjectAs

public java.lang.String storeObjectAs(java.lang.String container,
                                      java.lang.String name,
                                      org.apache.http.HttpEntity entity,
                                      java.util.Map<java.lang.String,java.lang.String> metadata,
                                      java.lang.String md5sum)
                               throws java.io.IOException,
                                      org.apache.http.HttpException,
                                      FilesException
Parameters:
container - The name of the container
name - The name of the object
entity - The name of the request entity (make sure to set the Content-Type
metadata - The metadata for the object
md5sum - The 32 character hex encoded MD5 sum of the data
Returns:
The ETAG if the save was successful, null otherwise
Throws:
java.io.IOException - There was a socket level exception talking to CloudFiles
org.apache.http.HttpException - There was a protocol level error talking to CloudFiles
FilesException - There was an error talking to CloudFiles.

copyObject

public java.lang.String copyObject(java.lang.String sourceContainer,
                                   java.lang.String sourceObjName,
                                   java.lang.String destContainer,
                                   java.lang.String destObjName)
                            throws org.apache.http.HttpException,
                                   java.io.IOException
This method copies the object found in the source container with the source object name to the destination container with the destination object name.

Parameters:
sourceContainer - of object to copy
sourceObjName - of object to copy
destContainer - where object copy will be copied
destObjName - of object copy
Returns:
ETAG if successful, else null
Throws:
java.io.IOException - indicates a socket level error talking to CloudFiles
org.apache.http.HttpException - indicates a protocol level error talking to CloudFiles
FilesException - indicates an error talking to CloudFiles

deleteObject

public void deleteObject(java.lang.String container,
                         java.lang.String objName)
                  throws java.io.IOException,
                         FilesNotFoundException,
                         org.apache.http.HttpException,
                         FilesException
Delete the given object from it's container.

Parameters:
container - The container name
objName - The object name
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesException
FilesNotFoundException

getObjectMetaData

public FilesObjectMetaData getObjectMetaData(java.lang.String container,
                                             java.lang.String objName)
                                      throws java.io.IOException,
                                             FilesNotFoundException,
                                             org.apache.http.HttpException,
                                             FilesAuthorizationException,
                                             FilesInvalidNameException
Get an object's metadata

Parameters:
container - The name of the container
objName - The name of the object
Returns:
The object's metadata
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesAuthorizationException - The Client's Login was invalid.
FilesInvalidNameException - The container or object name was not valid
FilesNotFoundException - The file was not found

getObject

public byte[] getObject(java.lang.String container,
                        java.lang.String objName)
                 throws java.io.IOException,
                        org.apache.http.HttpException,
                        FilesAuthorizationException,
                        FilesInvalidNameException,
                        FilesNotFoundException
Get the content of the given object

Parameters:
container - The name of the container
objName - The name of the object
Returns:
The content of the object
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesAuthorizationException
FilesInvalidNameException
FilesNotFoundException

getObjectAsStream

public java.io.InputStream getObjectAsStream(java.lang.String container,
                                             java.lang.String objName)
                                      throws java.io.IOException,
                                             org.apache.http.HttpException,
                                             FilesAuthorizationException,
                                             FilesInvalidNameException,
                                             FilesNotFoundException
Get's the given object's content as a stream

Parameters:
container - The name of the container
objName - The name of the object
Returns:
An input stream that will give the objects content when read from.
Throws:
java.io.IOException - There was an IO error doing network communication
org.apache.http.HttpException - There was an error with the http protocol
FilesAuthorizationException
FilesNotFoundException - The container does not exist
FilesInvalidNameException

getObjectAsRangedStream

public java.io.InputStream getObjectAsRangedStream(java.lang.String container,
                                                   java.lang.String objName,
                                                   long offset,
                                                   long length)
                                            throws java.io.IOException,
                                                   org.apache.http.HttpException,
                                                   FilesAuthorizationException,
                                                   FilesInvalidNameException,
                                                   FilesNotFoundException
Throws:
java.io.IOException
org.apache.http.HttpException
FilesAuthorizationException
FilesInvalidNameException
FilesNotFoundException

md5Sum

public static java.lang.String md5Sum(java.io.File f)
                               throws java.io.IOException
Calculates the MD5 checksum of a file, returned as a hex encoded string

Parameters:
f - The file
Returns:
The MD5 checksum, as a base 16 encoded string
Throws:
java.io.IOException

md5Sum

public static java.lang.String md5Sum(byte[] data)
                               throws java.io.IOException
Calculates the MD5 checksum of an array of data

Parameters:
data - The data to checksum
Returns:
The checksum, represented as a base 16 encoded string.
Throws:
java.io.IOException

sanitizeForURI

public static java.lang.String sanitizeForURI(java.lang.String str)
Encode any unicode characters that will cause us problems.

Parameters:
str -
Returns:
The string encoded for a URI

sanitizeAndPreserveSlashes

public static java.lang.String sanitizeAndPreserveSlashes(java.lang.String str)

unencodeURI

public static java.lang.String unencodeURI(java.lang.String str)

getConnectionTimeOut

public int getConnectionTimeOut()
Returns:
The connection timeout used for communicating with the server (in milliseconds)

setConnectionTimeOut

public void setConnectionTimeOut(int connectionTimeOut)
The timeout we will use for communicating with the server (in milliseconds)

Parameters:
connectionTimeOut - The new timeout for this connection

getStorageURL

public java.lang.String getStorageURL()
Returns:
The storage URL on the other end of the ReST api

getStorageToken

@Deprecated
public java.lang.String getStorageToken()
Deprecated. 

Returns:
Get's our storage token.

getAuthToken

public java.lang.String getAuthToken()
Returns:
Get's our storage token.

isLoggedin

public boolean isLoggedin()
Has this instance of the client authenticated itself? Note, this does not mean that a call right now will work, if the auth token has timed out, you will need to re-auth.

Returns:
True if we logged in, false otherwise.

getUserName

public java.lang.String getUserName()
The username we are logged in with.

Returns:
The username

setUserName

public void setUserName(java.lang.String email)
Set's the username for this client. Note, setting this after login has no real impact unless the login() method is called again.

Parameters:
email - the username

getPassword

public java.lang.String getPassword()
The password the client will use for the login.

Returns:
The password

setPassword

public void setPassword(java.lang.String password)
Set's the password for this client. Note, setting this after login has no real impact unless the login() method is called again.

Parameters:
password - The new password

getAuthenticationURL

public java.lang.String getAuthenticationURL()
The URL we will use for Authentication

Returns:
The URL (represented as a string)

setAuthenticationURL

public void setAuthenticationURL(java.lang.String authenticationURL)
Changes the URL of the authentication service. Note, if one is logged in, this doesn't have an effect unless one calls login again.

Parameters:
authenticationURL - The new authentication URL

getUseETag

public boolean getUseETag()
Returns:
the useETag

setUseETag

public void setUseETag(boolean useETag)
Parameters:
useETag - the useETag to set

setUserAgent

public void setUserAgent(java.lang.String userAgent)

getUserAgent

public java.lang.String getUserAgent()

isValidContainerName

public static boolean isValidContainerName(java.lang.String name)

isValidObjectName

public static boolean isValidObjectName(java.lang.String name)

updateObjectManifest

public boolean updateObjectManifest(java.lang.String container,
                                    java.lang.String object,
                                    java.lang.String manifest)
                             throws FilesAuthorizationException,
                                    org.apache.http.HttpException,
                                    java.io.IOException,
                                    FilesInvalidNameException
Throws:
FilesAuthorizationException
org.apache.http.HttpException
java.io.IOException
FilesInvalidNameException

updateObjectMetadata

public boolean updateObjectMetadata(java.lang.String container,
                                    java.lang.String object,
                                    java.util.Map<java.lang.String,java.lang.String> metadata)
                             throws FilesAuthorizationException,
                                    org.apache.http.HttpException,
                                    java.io.IOException,
                                    FilesInvalidNameException
Throws:
FilesAuthorizationException
org.apache.http.HttpException
java.io.IOException
FilesInvalidNameException

updateObjectMetadataAndManifest

public boolean updateObjectMetadataAndManifest(java.lang.String container,
                                               java.lang.String object,
                                               java.util.Map<java.lang.String,java.lang.String> metadata,
                                               java.lang.String manifest)
                                        throws FilesAuthorizationException,
                                               org.apache.http.HttpException,
                                               java.io.IOException,
                                               FilesInvalidNameException
Throws:
FilesAuthorizationException
org.apache.http.HttpException
java.io.IOException
FilesInvalidNameException