org.jets3t.service
Class CloudFrontService

java.lang.Object
  org.jets3t.service.CloudFrontService

All Implemented Interfaces:

AWSRequestAuthorizer

public class CloudFrontService
extends java.lang.Object
implements AWSRequestAuthorizer

A service that handles communication with the Amazon CloudFront REST API, offering all the operations that can be performed on CloudFront distributions.

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

Field Summary

static java.lang.String	DEFAULT_BUCKET_SUFFIX
static java.lang.String	ENDPOINT
protected int	internalErrorRetryMax
protected Jets3tProperties	jets3tProperties
protected long	timeOffset The approximate difference in the current time between your computer and Amazon's servers, measured in milliseconds.
static java.lang.String	VERSION
static java.lang.String	XML_NAMESPACE

Constructor Summary

CloudFrontService(AWSCredentials awsCredentials)
Constructs the service with default properties.

CloudFrontService(AWSCredentials awsCredentials, java.lang.String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties, org.apache.commons.httpclient.HostConfiguration hostConfig)
Constructs the service and initialises its properties.

Method Summary

void	authorizeHttpRequest(org.apache.commons.httpclient.HttpMethod httpMethod)
Distribution	createDistribution(java.lang.String origin) Create a CloudFront distribution for an S3 bucket that will be publicly available once created.
Distribution	createDistribution(java.lang.String origin, java.lang.String callerReference, java.lang.String[] cnames, java.lang.String comment, boolean enabled, LoggingStatus loggingStatus) Create a CloudFront distribution for an S3 bucket.
void	deleteDistribution(java.lang.String id) Delete a disabled distribution.
void	disableDistributionForDeletion(java.lang.String id) Convenience method to disable a distribution that you intend to delete.
AWSCredentials	getAWSCredentials()
protected java.util.Date	getCurrentTimeWithOffset() Returns the current date and time, adjusted according to the time offset between your computer and an AWS server (as set by the RestUtils.getAWSTimeAdjustment() method).
DistributionConfig	getDistributionConfig(java.lang.String id) Lookup configuration information for a distribution.
Distribution	getDistributionInfo(java.lang.String id) Lookup information for a distribution.
Distribution[]	listDistributions() List all your CloudFront distributions.
Distribution[]	listDistributions(int pagingSize) List all your CloudFront distributions, with a given maximum number of Distribution items in each "page" of results.
Distribution[]	listDistributions(java.lang.String bucketName) List the distributions for a given S3 bucket name, if any.
protected void	performRestRequest(org.apache.commons.httpclient.HttpMethod httpMethod, int expectedResponseCode) Performs an HTTP/S request by invoking the provided HttpMethod object.
static java.lang.String	sanitizeS3BucketName(java.lang.String proposedBucketName) Sanitizes a proposed bucket name to ensure it is fully-specified rather than merely the bucket's short name.
DistributionConfig	updateDistributionConfig(java.lang.String id, java.lang.String[] cnames, java.lang.String comment, boolean enabled, LoggingStatus loggingStatus) Update the configuration of an existing distribution to change its CNAME aliases, comment or enabled status.

Methods inherited from class java.lang.Object

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

Field Detail

ENDPOINT

public static final java.lang.String ENDPOINT

See Also:

Constant Field Values

VERSION

public static final java.lang.String VERSION

See Also:

Constant Field Values

XML_NAMESPACE

public static final java.lang.String XML_NAMESPACE

See Also:

Constant Field Values

DEFAULT_BUCKET_SUFFIX

public static final java.lang.String DEFAULT_BUCKET_SUFFIX

See Also:

Constant Field Values

jets3tProperties

protected Jets3tProperties jets3tProperties

internalErrorRetryMax

protected int internalErrorRetryMax

timeOffset

protected long timeOffset

The approximate difference in the current time between your computer and Amazon's servers, measured in milliseconds. This value is 0 by default. Use the getCurrentTimeWithOffset() to obtain the current time with this offset factor included, and the RestUtils.getAWSTimeAdjustment() method to calculate an offset value for your computer based on a response from an AWS server.

Constructor Detail

CloudFrontService

public CloudFrontService(AWSCredentials awsCredentials,
                         java.lang.String invokingApplicationDescription,
                         org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider,
                         Jets3tProperties jets3tProperties,
                         org.apache.commons.httpclient.HostConfiguration hostConfig)
                  throws CloudFrontServiceException

Constructs the service and initialises its properties.

Parameters:

awsCredentials - the AWS user credentials to use when communicating with CloudFront

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.1 or My App Name/1.0. May be null.

credentialsProvider - an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary. May be null.

jets3tProperties - JetS3t properties that will be applied within this service. May be null.

hostConfig - Custom HTTP host configuration; e.g to register a custom Protocol Socket Factory. May be null.

Throws:

CloudFrontServiceException

CloudFrontService

public CloudFrontService(AWSCredentials awsCredentials)
                  throws CloudFrontServiceException

Constructs the service with default properties.

Parameters:

awsCredentials - the AWS user credentials to use when communicating with CloudFront

Throws:

CloudFrontServiceException

Method Detail

getAWSCredentials

public AWSCredentials getAWSCredentials()

Returns:

the AWS Credentials identifying the AWS user.

getCurrentTimeWithOffset

protected java.util.Date getCurrentTimeWithOffset()

Returns the current date and time, adjusted according to the time offset between your computer and an AWS server (as set by the RestUtils.getAWSTimeAdjustment() method).

Returns:

the current time, or the current time adjusted to match the AWS time if the service has experienced a RequestExpired error.

authorizeHttpRequest

public void authorizeHttpRequest(org.apache.commons.httpclient.HttpMethod httpMethod)
                          throws java.lang.Exception

Specified by:

authorizeHttpRequest in interface AWSRequestAuthorizer

Parameters:

httpMethod - the request object

Throws:

java.lang.Exception

performRestRequest

protected void performRestRequest(org.apache.commons.httpclient.HttpMethod httpMethod,
                                  int expectedResponseCode)
                           throws CloudFrontServiceException

Performs an HTTP/S request by invoking the provided HttpMethod object. If the HTTP response code doesn't match the expected value, an exception is thrown.

Parameters:

httpMethod - the object containing a request target and all other information necessary to perform the request

expectedResponseCode - the HTTP response code that indicates a successful request. If the response code received does not match this value an error must have occurred, so an exception is thrown.

Throws:

CloudFrontServiceException - all exceptions are wrapped in a CloudFrontServiceException. Depending on the kind of error that occurred, this exception may contain additional error information available from an XML error response document.

listDistributions

public Distribution[] listDistributions(int pagingSize)
                                 throws CloudFrontServiceException

List all your CloudFront distributions, with a given maximum number of Distribution items in each "page" of results.

Parameters:

pagingSize - the maximum number of distributions the CloudFront service will return in each response message.

Returns:

a list of your distributions.

Throws:

CloudFrontServiceException

listDistributions

public Distribution[] listDistributions()
                                 throws CloudFrontServiceException

List all your CloudFront distributions.

Returns:

a list of your distributions.

Throws:

CloudFrontServiceException

listDistributions

public Distribution[] listDistributions(java.lang.String bucketName)
                                 throws CloudFrontServiceException

List the distributions for a given S3 bucket name, if any.

Parameters:

bucketName - the name of the S3 bucket whose distributions will be returned.

Returns:

a list of distributions applied to the given S3 bucket, or an empty list if there are no such distributions.

Throws:

CloudFrontServiceException

createDistribution

public Distribution createDistribution(java.lang.String origin)
                                throws CloudFrontServiceException

Create a CloudFront distribution for an S3 bucket that will be publicly available once created.

Parameters:

origin - the Amazon S3 bucket to associate with the distribution, specified as a full S3 sub-domain path (e.g. 'jets3t.s3.amazonaws.com' for the 'jets3t' bucket)

Returns:

an object that describes the newly-created distribution, in particular the distribution's identifier and domain name values.

Throws:

CloudFrontServiceException

createDistribution

public Distribution createDistribution(java.lang.String origin,
                                       java.lang.String callerReference,
                                       java.lang.String[] cnames,
                                       java.lang.String comment,
                                       boolean enabled,
                                       LoggingStatus loggingStatus)
                                throws CloudFrontServiceException

Create a CloudFront distribution for an S3 bucket.

Parameters:

origin - the Amazon S3 bucket to associate with the distribution, specified as a full S3 sub-domain path (e.g. 'jets3t.s3.amazonaws.com' for the 'jets3t' bucket)

callerReference - A user-set unique reference value that ensures the request can't be replayed (max UTF-8 encoding size 128 bytes). This parameter may be null, in which case your computer's local epoch time in milliseconds will be used.

cnames - A list of up to 10 CNAME aliases to associate with the distribution. This parameter may be a null or empty array.

comment - An optional comment to describe the distribution in your own terms (max 128 characters). May be null.

enabled - Should the distribution should be enabled and publicly accessible upon creation?

loggingStatus - Logging status settings (bucket, prefix) for the distribution. If this value is null, logging will be disabled for the distribution.

Returns:

an object that describes the newly-created distribution, in particular the distribution's identifier and domain name values.

Throws:

CloudFrontServiceException

getDistributionInfo

public Distribution getDistributionInfo(java.lang.String id)
                                 throws CloudFrontServiceException

Lookup information for a distribution.

Parameters:

id - the distribution's unique identifier.

Returns:

an object that describes the distribution, including its identifier and domain name values as well as its configuration details.

Throws:

CloudFrontServiceException

getDistributionConfig

public DistributionConfig getDistributionConfig(java.lang.String id)
                                         throws CloudFrontServiceException

Lookup configuration information for a distribution. The configuration information is a subset of the information available from the getDistributionInfo(String) method.

Parameters:

id - the distribution's unique identifier.

Returns:

an object that describes the distribution's configuration, including its origin bucket and CNAME aliases.

Throws:

CloudFrontServiceException

updateDistributionConfig

public DistributionConfig updateDistributionConfig(java.lang.String id,
                                                   java.lang.String[] cnames,
                                                   java.lang.String comment,
                                                   boolean enabled,
                                                   LoggingStatus loggingStatus)
                                            throws CloudFrontServiceException

Update the configuration of an existing distribution to change its CNAME aliases, comment or enabled status. The new configuration settings replace the existing configuration, and may take some time to be fully applied.

This method performs all the steps necessary to update the configuration. It first performs lookup on the distribution using getDistributionConfig(String) to find its origin and caller reference values, then uses this information to apply your configuration changes.

Parameters:

id - the distribution's unique identifier.

cnames - A list of up to 10 CNAME aliases to associate with the distribution. This parameter may be null, in which case the original CNAME aliases are retained.

comment - An optional comment to describe the distribution in your own terms (max 128 characters). May be null, in which case the original comment is retained.

enabled - Should the distribution should be enabled and publicly accessible after the configuration update?

loggingStatus - Logging status settings (bucket, prefix) for the distribution. If this value is null, logging will be disabled for the distribution.

Returns:

an object that describes the distribution's updated configuration, including its origin bucket and CNAME aliases.

Throws:

CloudFrontServiceException

disableDistributionForDeletion

public void disableDistributionForDeletion(java.lang.String id)
                                    throws CloudFrontServiceException

Convenience method to disable a distribution that you intend to delete. This method merely calls the updateDistributionConfig(String, String[], String, boolean, LoggingStatus) method with default values for most of the distribution's configuration settings.

Warning: Do not use this method with distributions you intend to keep, because it will reset most of the distribution's configuration settings such as CNAMEs and logging status.

Parameters:

id - the distribution's unique identifier.

Throws:

CloudFrontServiceException

deleteDistribution

public void deleteDistribution(java.lang.String id)
                        throws CloudFrontServiceException

Delete a disabled distribution. You can only delete a distribution that is already disabled, if you delete an enabled distribution this operation will fail with a DistributionNotDisabled error.

This method performs many of the steps necessary to delete a disabled distribution. It first performs lookup on the distribution using getDistributionConfig(String) to find its ETag value, then uses this information to delete the distribution.

Because it can take a long time (minutes) to disable a distribution, this task is not performed automatically by this method. In your own code, you need to verify that a distribution is disabled with a status of Deployed before you invoke this method.

Parameters:

id - the distribution's unique identifier.

Throws:

CloudFrontServiceException

sanitizeS3BucketName

public static java.lang.String sanitizeS3BucketName(java.lang.String proposedBucketName)

Sanitizes a proposed bucket name to ensure it is fully-specified rather than merely the bucket's short name. A fully specified bucket name looks like "jets3t.s3.amazonaws.com".

Parameters:

proposedBucketName - the proposed S3 bucket name that will be sanitized.

Returns:

the bucket name with the DEFAULT_BUCKET_SUFFIX added, if necessary.