org.jets3t.service.impl.rest.httpclient
Class GoogleStorageService

java.lang.Object
  extended by org.jets3t.service.StorageService
      extended by org.jets3t.service.impl.rest.httpclient.RestStorageService
          extended by org.jets3t.service.impl.rest.httpclient.GoogleStorageService
All Implemented Interfaces:
AWSRequestAuthorizer

public class GoogleStorageService
extends RestStorageService

REST/HTTP implementation of Google Storage Service based on the HttpClient library.

This class uses properties obtained through Jets3tProperties. For more information on these properties please refer to JetS3t Configuration

Author:
Google Developers

Field Summary
 
Fields inherited from class org.jets3t.service.StorageService
BUCKET_STATUS__ALREADY_CLAIMED, BUCKET_STATUS__DOES_NOT_EXIST, BUCKET_STATUS__MY_BUCKET
 
Constructor Summary
GoogleStorageService(ProviderCredentials credentials)
          Constructs the service and initialises the properties.
GoogleStorageService(ProviderCredentials credentials, java.lang.String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider)
          Constructs the service and initialises the properties.
GoogleStorageService(ProviderCredentials credentials, java.lang.String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties)
          Constructs the service and initialises the properties.
GoogleStorageService(ProviderCredentials credentials, java.lang.String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties, org.apache.commons.httpclient.HostConfiguration hostConfig)
          Constructs the service and initialises the properties.
 
Method Summary
 GSBucket createBucket(java.lang.String bucketName)
          Creates a bucket.
 GSAccessControlList getBucketAcl(java.lang.String bucketName)
          Retrieves the access control settings of a bucket.
 java.lang.String getEndpoint()
           
 GSObject getObject(java.lang.String bucketName, java.lang.String objectKey)
          Returns an object representing the details and data of an item in a service, without applying any preconditions.
 GSObject getObject(java.lang.String bucketName, java.lang.String objectKey, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags, java.lang.Long byteRangeStart, java.lang.Long byteRangeEnd)
          Returns an object representing the details and data of an item that meets any given preconditions.
 GSObject getObjectDetails(java.lang.String bucketName, java.lang.String objectKey)
          Returns an object representing the details of an item in without the object's data, and without applying any preconditions.
 java.util.List<java.lang.String> getResourceParameterNames()
           
 java.lang.String getRestHeaderPrefix()
           
 java.lang.String getRestMetadataPrefix()
           
 GSBucket[] listAllBuckets()
          Lists the buckets belonging to the service user.
 GSObject[] listObjects(java.lang.String bucketName)
          Lists the objects in a bucket.
 GSObject[] listObjects(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter)
          Lists the objects in a bucket matching a prefix and delimiter.
 void putBucketAcl(GSBucket bucket)
          Applies access control settings to a bucket.
 void putBucketAcl(java.lang.String bucketName, GSAccessControlList acl)
          Applies access control settings to a bucket.
 GSObject putObject(java.lang.String bucketName, GSObject object)
           
 
Methods inherited from class org.jets3t.service.impl.rest.httpclient.RestStorageService
authorizeHttpRequest, checkBucketStatus, deleteObjectWithSignedUrl, getCredentialsProvider, getHttpClient, getHttpConnectionManager, getObjectAclWithSignedUrl, getObjectDetailsWithSignedUrl, getObjectWithSignedUrl, isBucketAccessible, putObjectAclWithSignedUrl, putObjectWithSignedUrl, setCredentialsProvider, setHttpClient, setHttpConnectionManager
 
Methods inherited from class org.jets3t.service.StorageService
copyObject, copyObject, createBucket, deleteBucket, deleteBucket, deleteObject, getAccountOwner, getBucket, getCurrentTimeWithOffset, getInternalErrorRetryMax, getInvokingApplicationDescription, getJetS3tProperties, getObjectAcl, getObjectDetails, getOrCreateBucket, getProviderCredentials, isAuthenticatedConnection, isHttpsOnly, isObjectInBucket, isShutdown, listObjects, listObjectsChunked, listObjectsChunked, moveObject, putBucketAcl, putBucketAcl, putObject, putObjectAcl, putObjectAcl, renameMetadataKeys, renameObject, shutdown, updateObjectMetadata
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GoogleStorageService

public GoogleStorageService(ProviderCredentials credentials)
                     throws ServiceException
Constructs the service and initialises the properties.

Parameters:
credentials - the user credentials to use when communicating with Google Storage, may be null in which case the communication is done as an anonymous user.
Throws:
ServiceException

GoogleStorageService

public GoogleStorageService(ProviderCredentials credentials,
                            java.lang.String invokingApplicationDescription,
                            org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider)
                     throws ServiceException
Constructs the service and initialises the properties.

Parameters:
credentials - the user credentials to use when communicating with Google Storage, may be null in which case the communication is done as an anonymous user.
invokingApplicationDescription - a short description of the application using the service, suitable for inclusion in a user agent string for REST/HTTP requests. Ideally this would include the application's version number, for example: Cockpit/0.7.3 or My App Name/1.0
credentialsProvider - an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary.
Throws:
ServiceException

GoogleStorageService

public GoogleStorageService(ProviderCredentials credentials,
                            java.lang.String invokingApplicationDescription,
                            org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider,
                            Jets3tProperties jets3tProperties)
                     throws ServiceException
Constructs the service and initialises the properties.

Parameters:
credentials - the user credentials to use when communicating with Google Storage, may be null in which case the communication is done as an anonymous user.
invokingApplicationDescription - a short description of the application using the service, suitable for inclusion in a user agent string for REST/HTTP requests. Ideally this would include the application's version number, for example: Cockpit/0.7.3 or My App Name/1.0
credentialsProvider - an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary.
jets3tProperties - JetS3t properties that will be applied within this service.
Throws:
ServiceException

GoogleStorageService

public GoogleStorageService(ProviderCredentials credentials,
                            java.lang.String invokingApplicationDescription,
                            org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider,
                            Jets3tProperties jets3tProperties,
                            org.apache.commons.httpclient.HostConfiguration hostConfig)
                     throws ServiceException
Constructs the service and initialises the properties.

Parameters:
credentials - the user credentials to use when communicating with Google Storage, may be null in which case the communication is done as an anonymous user.
invokingApplicationDescription - a short description of the application using the service, suitable for inclusion in a user agent string for REST/HTTP requests. Ideally this would include the application's version number, for example: Cockpit/0.7.3 or My App Name/1.0
credentialsProvider - an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary.
jets3tProperties - JetS3t properties that will be applied within this service.
hostConfig - Custom HTTP host configuration; e.g to register a custom Protocol Socket Factory
Throws:
ServiceException
Method Detail

getEndpoint

public java.lang.String getEndpoint()
Specified by:
getEndpoint in class StorageService
Returns:
the endpoint to be used to connect to Google Storage.

getRestHeaderPrefix

public java.lang.String getRestHeaderPrefix()
Specified by:
getRestHeaderPrefix in class StorageService
Returns:
header prefix for general Google Storage headers: x-goog-.

getRestMetadataPrefix

public java.lang.String getRestMetadataPrefix()
Specified by:
getRestMetadataPrefix in class StorageService
Returns:
header prefix for Google Storage metadata headers: x-goog-meta-.

getResourceParameterNames

public java.util.List<java.lang.String> getResourceParameterNames()
Specified by:
getResourceParameterNames in class StorageService
Returns:
GET parameter names that represent specific resources in the target service, as opposed to representing REST operation "plumbing". For example the "acl" parameter might be used to represent a resource's access control list settings.

listAllBuckets

public GSBucket[] listAllBuckets()
                          throws ServiceException
Description copied from class: StorageService
Lists the buckets belonging to the service user.

This method cannot be performed by anonymous services, and will fail with an exception if the service is not authenticated.

Overrides:
listAllBuckets in class StorageService
Returns:
the list of buckets owned by the service user.
Throws:
ServiceException

listObjects

public GSObject[] listObjects(java.lang.String bucketName)
                       throws ServiceException
Description copied from class: StorageService
Lists the objects in a bucket.

The objects returned by this method contain only minimal information such as the object's size, ETag, and LastModified timestamp. To retrieve the objects' metadata you must perform follow-up getObject or getObjectDetails operations.

This method can be performed by anonymous services. Anonymous services can only list the objects in a publicly-readable bucket.

Overrides:
listObjects in class StorageService
Parameters:
bucketName - the name of the bucket whose contents will be listed.
Returns:
the set of objects contained in a bucket.
Throws:
ServiceException

listObjects

public GSObject[] listObjects(java.lang.String bucketName,
                              java.lang.String prefix,
                              java.lang.String delimiter)
                       throws ServiceException
Description copied from class: StorageService
Lists the objects in a bucket matching a prefix and delimiter.

The objects returned by this method contain only minimal information such as the object's size, ETag, and LastModified timestamp. To retrieve the objects' metadata you must perform follow-up getObject or getObjectDetails operations.

This method can be performed by anonymous services. Anonymous services can only list the objects in a publicly-readable bucket.

NOTE: If you supply a delimiter value that could cause virtual path "subdirectories" to be included in the results from the service, use the StorageService.listObjectsChunked(String, String, String, long, String, boolean) method instead of this one to obtain both object and path values.

Overrides:
listObjects in class StorageService
Parameters:
bucketName - the name of the bucket whose contents will be listed.
prefix - only objects with a key that starts with this prefix will be listed
delimiter - only list objects with key names up to this delimiter, may be null. See note above. Note: If a non-null delimiter is specified, the prefix must include enough text to reach the first occurrence of the delimiter in the bucket's keys, or no results will be returned.
Returns:
the set of objects contained in a bucket whose keys start with the given prefix.
Throws:
ServiceException

createBucket

public GSBucket createBucket(java.lang.String bucketName)
                      throws ServiceException
Description copied from class: StorageService
Creates a bucket. Caution: Performing this operation unnecessarily when a bucket already exists may cause OperationAborted errors with the message "A conflicting conditional operation is currently in progress against this resource.". To avoid this error, use the StorageService.getOrCreateBucket(String) in situations where the bucket may already exist. This method cannot be performed by anonymous services.

Overrides:
createBucket in class StorageService
Parameters:
bucketName - the name of the bucket to create.
Returns:
the created bucket object. Note: the object returned has minimal information about the bucket that was created, including only the bucket's name.
Throws:
ServiceException

getBucketAcl

public GSAccessControlList getBucketAcl(java.lang.String bucketName)
                                 throws ServiceException
Description copied from class: StorageService
Retrieves the access control settings of a bucket. This method can be performed by anonymous services, but can only succeed if the bucket's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of a bucket if the ACL already in place for that bucket allows you to do so.

Overrides:
getBucketAcl in class StorageService
Parameters:
bucketName - the name of the bucket whose access control settings will be returned.
Returns:
the ACL settings of the bucket.
Throws:
ServiceException

putBucketAcl

public void putBucketAcl(java.lang.String bucketName,
                         GSAccessControlList acl)
                  throws ServiceException
Applies access control settings to a bucket. The ACL settings must be included inside the bucket. This method can be performed by anonymous services, but can only succeed if the bucket's existing ACL already allows write access by the anonymous user.

Parameters:
bucketName - a name of the bucket with ACL settings to apply.
Throws:
ServiceException

putBucketAcl

public void putBucketAcl(GSBucket bucket)
                  throws ServiceException
Applies access control settings to a bucket. The ACL settings must be included inside the bucket. This method can be performed by anonymous services, but can only succeed if the bucket's existing ACL already allows write access by the anonymous user.

Parameters:
bucket - a bucket with ACL settings to apply.
Throws:
ServiceException

getObject

public GSObject getObject(java.lang.String bucketName,
                          java.lang.String objectKey)
                   throws ServiceException
Description copied from class: StorageService
Returns an object representing the details and data of an item in a service, without applying any preconditions.

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object.

Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.

Overrides:
getObject in class StorageService
Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the key identifying the object.
Returns:
the object with the given key, including the object's data input stream.
Throws:
ServiceException

putObject

public GSObject putObject(java.lang.String bucketName,
                          GSObject object)
                   throws ServiceException
Throws:
ServiceException

getObject

public GSObject getObject(java.lang.String bucketName,
                          java.lang.String objectKey,
                          java.util.Calendar ifModifiedSince,
                          java.util.Calendar ifUnmodifiedSince,
                          java.lang.String[] ifMatchTags,
                          java.lang.String[] ifNoneMatchTags,
                          java.lang.Long byteRangeStart,
                          java.lang.Long byteRangeEnd)
                   throws ServiceException
Description copied from class: StorageService
Returns an object representing the details and data of an item that meets any given preconditions.

Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.

An exception is thrown if any of the preconditions fail. Preconditions are only applied if they are non-null.

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object.

Implementation notes

Implementations should use StorageService.assertValidBucket(org.jets3t.service.model.StorageBucket, java.lang.String) assertion.

Overrides:
getObject in class StorageService
Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the key identifying the object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
byteRangeStart - include only a portion of the object's data - starting at this point, ignored if null.
byteRangeEnd - include only a portion of the object's data - ending at this point, ignored if null.
Returns:
the object with the given key, including only general details and metadata (not the data input stream)
Throws:
ServiceException

getObjectDetails

public GSObject getObjectDetails(java.lang.String bucketName,
                                 java.lang.String objectKey)
                          throws ServiceException
Description copied from class: StorageService
Returns an object representing the details of an item in without the object's data, and without applying any preconditions.

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object's details.

Overrides:
getObjectDetails in class StorageService
Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the key identifying the object.
Returns:
the object with the given key, including only general details and metadata (not the data input stream)
Throws:
ServiceException