public class

S3Connector

extends Object
java.lang.Object
   ↳ org.mule.module.s3.S3Connector
Known Direct Subclasses
Known Indirect Subclasses

Class Overview

Amazon S3 (Simple Storage Service) is an online storage web service offered by Amazon Web Services. Amazon S3 provides storage through web services interfaces (REST, SOAP, and BitTorrent).

Summary

Fields
private SimpleAmazonS3 client
private String proxyHost The optional proxy port
private String proxyPassword The optional proxy password
private Integer proxyPort The optional proxy port
private String proxyUsername The optional proxy username
Public Constructors
S3Connector()
Public Methods
synchronized void connect(String accessKey, String secretKey)
Login to Amazon S3
String connectionId()
String copyObject(String sourceBucketName, String sourceKey, String sourceVersionId, String destinationBucketName, String destinationKey, AccessControlList destinationAcl, StorageClass destinationStorageClass, Map<String, String> destinationUserMetadata, Date modifiedSince, Date unmodifiedSince)
Copies a source object to a new destination; to copy an object, the caller's account must have read access to the source object and write access to the destination bucket.
Bucket createBucket(String bucketName, Region region, AccessControlList acl)
Creates a new bucket; connector must not be configured as anonymous for this operation to succeed.
String createObject(String bucketName, String key, Object content, Long contentLength, String contentMd5, String contentType, String contentDisposition, AccessControlList acl, StorageClass storageClass, Map<String, String> userMetadata)
Uploads an object to S3.
URI createObjectPresignedUri(String bucketName, String key, String versionId, Date expiration, String method)
Returns a pre-signed URL for accessing an Amazon S3 object.
URI createObjectUri(String bucketName, String key, boolean useDefaultServer, boolean secure)
Creates an http URI for the given object id.
void deleteBucket(String bucketName, boolean force)
Deletes the specified bucket.
void deleteBucketPolicy(String bucketName)
Deletes the bucket's policy.
void deleteBucketWebsiteConfiguration(String bucketName)
Removes the website configuration for a bucket; this operation requires the DeleteBucketWebsite permission.
void deleteObject(String bucketName, String key, String versionId)
Deletes a given object, only the owner of the bucket containing the version can perform this operation.
synchronized void disconnect()
String getBucketPolicy(String bucketName)
Answers the policy for the given bucket.
BucketWebsiteConfiguration getBucketWebsiteConfiguration(String bucketName)
Answers the website of the given bucket.
S3Object getObject(String bucketName, String key, String versionId, Date modifiedSince, Date unmodifiedSince)
Gets the object stored in Amazon S3 under the specified bucket and key.
InputStream getObjectContent(String bucketName, String key, String versionId, Date modifiedSince, Date unmodifiedSince)
Gets the content of an object stored in Amazon S3 under the specified bucket and key.
ObjectMetadata getObjectMetadata(String bucketName, String key, String versionId)
Gets the metadata for the specified Amazon S3 object without actually fetching the object itself.
String getProxyHost()
String getProxyPassword()
int getProxyPort()
String getProxyUsername()
boolean isConnected()
List<Bucket> listBuckets()
Answers a list of all Amazon S3 buckets that the authenticated sender of the request owns.
Iterable<S3VersionSummary> listObjectVersions(String bucketName)
Lazily lists all object versions for a given bucket that has versioning enabled.
Iterable<S3ObjectSummary> listObjects(String bucketName, String prefix)
Lazily lists all objects for a given prefix.
void setBucketPolicy(String bucketName, String policyText)
Sets the bucket's policy, overriding any previously set.
void setBucketVersioningStatus(String bucketName, VersioningStatus versioningStatus)
Sets the versioning status for the given bucket.
void setBucketWebsiteConfiguration(String bucketName, String suffix, String errorDocument)
Sets the given bucket's website configuration.
void setClient(SimpleAmazonS3 client)
void setObjectStorageClass(String bucketName, String key, StorageClass storageClass)
Sets the Amazon S3 storage class for the given object.
void setProxyHost(String proxyHost)
void setProxyPassword(String proxyPassword)
void setProxyPort(Integer proxyPort)
void setProxyUsername(String proxyUsername)
[Expand]
Inherited Methods
From class java.lang.Object

Fields

private SimpleAmazonS3 client

private String proxyHost

The optional proxy port

private String proxyPassword

The optional proxy password

private Integer proxyPort

The optional proxy port

private String proxyUsername

The optional proxy username

Public Constructors

public S3Connector ()

Public Methods

public synchronized void connect (String accessKey, String secretKey)

Login to Amazon S3

Parameters
accessKey The access key provided by Amazon, needed for non annoynous operations
secretKey The secrete key provided by Amazon, needed for non annoynous operations
Throws
ConnectionException

public String connectionId ()

public String copyObject (String sourceBucketName, String sourceKey, String sourceVersionId, String destinationBucketName, String destinationKey, AccessControlList destinationAcl, StorageClass destinationStorageClass, Map<String, String> destinationUserMetadata, Date modifiedSince, Date unmodifiedSince)

Copies a source object to a new destination; to copy an object, the caller's account must have read access to the source object and write access to the destination bucket. By default, all object metadata for the source object are copied to the new destination object, unless new object metadata in the specified is provided. The AccesControlList is not copied to the new object, and, unless another ACL specified, PRIVATE is assumed. If no destination bucket is specified, the same that the source bucket is used - local copy.

Parameters
sourceBucketName The source object's bucket
sourceKey The source object's key
sourceVersionId The specific version of the source object to copy, if versioning is enabled. Left unspecified if the latest version is desired, or versioning is not enabled.
destinationBucketName The destination object's bucket. If none provided, a local copy is performed, that is, it is copied within the same bucket.
destinationKey The destination object's key
destinationAcl The acl of the destination object.
destinationStorageClass One of StorageClass enumerated values, defaults to STANDARD
destinationUserMetadata The new metadata of the destination object, that if specified, overrides that copied from the source object
modifiedSince The modified constraint that restricts this request to executing only if the object has been modified after the specified date. This constraint is specified but does not match, no copy is performed
unmodifiedSince The unmodified constraint that restricts this request to executing only if the object has not been modified after this date. This constraint is specified but does not match, no copy is performed
Returns
  • the version id of the new object, or null, if versioning is not enabled

public Bucket createBucket (String bucketName, Region region, AccessControlList acl)

Creates a new bucket; connector must not be configured as anonymous for this operation to succeed. Bucket names must be unique across all of Amazon S3, that is, among all their users. Bucket ownership is similar to the ownership of Internet domain names. Within Amazon S3, only a single user owns each bucket. Once a uniquely named bucket is created in Amazon S3, organize and name the objects within the bucket in any way. Ownership of the bucket is retained as long as the owner has an Amazon S3 account. To conform with DNS requirements, buckets names must: not contain underscores, be between 3 and 63 characters long, not end with a dash, not contain adjacent periods, not contain dashes next to periods and not contain uppercase characters. Do not make bucket create or delete calls in the high availability code path of an application. Create or delete buckets in a separate initialization or setup.

Parameters
bucketName The bucket to create. It must not exist yet.
region The region where to create the new bucket
acl The access control list of the new bucket
Returns
  • the non null, new Bucket

public String createObject (String bucketName, String key, Object content, Long contentLength, String contentMd5, String contentType, String contentDisposition, AccessControlList acl, StorageClass storageClass, Map<String, String> userMetadata)

Uploads an object to S3. Supported contents are InputStreams, Strings, byte arrays and Files.

Parameters
bucketName The object's bucket
key The object's key
content The content to be uploaded to S3, capable of creating a PutObjectRequest.
contentLength The content length. If content is a InputStream, this parameter should be specified, as not doing so will introduce a performance loss as the contents will have to be persisted on disk before being uploaded. Otherwise, it is ignored. An exception to this rule are InputStreams returned by Mule Http Connector: if stream has Content-Length information, it will be used. In any case a content length of 0 is interpreted as an unspecified content length
contentMd5 The content md5, encoded in base 64. If content is a file, it is ignored.
contentType The content type of the new object.
contentDisposition The content disposition of the new object.
acl The access control list of the new object
storageClass The storage class of the new object
userMetadata A map of arbitrary object properties keys and values
Returns
  • the id of the created object, or null, if versioning is not enabled

public URI createObjectPresignedUri (String bucketName, String key, String versionId, Date expiration, String method)

Returns a pre-signed URL for accessing an Amazon S3 object. The pre-signed URL can be shared to other users, allowing access to the resource without providing an account's AWS security credentials.

Parameters
bucketName The object's bucket
key The object's key
versionId The specific version of the object to create the URI, if versioning is enabled. Left unspecified if the latest version is desired, or versioning is not enabled.
expiration The time at which the returned pre-signed URL will expire.
method The HTTP method verb to use for this URL
Returns
  • A non null pre-signed URI that can be used to access an Amazon S3 resource without requiring the user of the URL to know the account's AWS security credentials.

public URI createObjectUri (String bucketName, String key, boolean useDefaultServer, boolean secure)

Creates an http URI for the given object id. The useDefaultServer option enables using default US Amazon server subdomain in the URI regardless of the region. The main benefit of such feature is that this operation does not need to hit the Amazon servers, but the drawback is that using the given URI as an URL to the resource have unnecessary latency penalties for standard regions other than US_STANDARD.

Parameters
bucketName The object's bucket
key The object's key
useDefaultServer If the default US Amazon server subdomain should be used in the URI regardless of the region.
secure Whether to use http or https
Returns
  • a non secure http URI to the object. Unlike the presigned URI, object must have PUBLIC_READ or PUBLIC_READ_WRITE permission

public void deleteBucket (String bucketName, boolean force)

Deletes the specified bucket. All objects (and all object versions, if versioning was ever enabled) in the bucket must be deleted before the bucket itself can be deleted; this restriction can be relaxed by specifying the attribute force="true".

Parameters
bucketName The bucket to delete
force Optional true if the bucket must be deleted even if it is not empty, false if operation should fail in such scenario.

public void deleteBucketPolicy (String bucketName)

Deletes the bucket's policy. Only the owner of the bucket can delete the bucket policy. Bucket policies provide access control management at the bucket level for both the bucket resource and contained object resources.

Parameters
bucketName The bucket whose policy to delete

public void deleteBucketWebsiteConfiguration (String bucketName)

Removes the website configuration for a bucket; this operation requires the DeleteBucketWebsite permission. By default, only the bucket owner can delete the website configuration attached to a bucket. However, bucket owners can grant other users permission to delete the website configuration by writing a bucket policy granting them the S3:DeleteBucketWebsite permission. Calling this operation on a bucket with no website configuration does not fail, but calling this operation a bucket that does not exist does.

Parameters
bucketName The bucket whose policy to delete

public void deleteObject (String bucketName, String key, String versionId)

Deletes a given object, only the owner of the bucket containing the version can perform this operation. If version is specified, versioning must be enabled, and once deleted, there is no method to restore such version. Otherwise, once deleted, the object can only be restored if versioning was enabled when the object was deleted. If attempting to delete an object that does not exist, Amazon S3 will return a success message instead of an error message.

Parameters
bucketName The object's bucket
key The object's key
versionId The specific version of the object to delete, if versioning is enabled. Left unspecified if the latest version is desired, or versioning is not enabled.

public synchronized void disconnect ()

public String getBucketPolicy (String bucketName)

Answers the policy for the given bucket. Only the owner of the bucket can retrieve it. If no policy has been set for the bucket, then a null policy text field will be returned.

Parameters
bucketName The bucket whose policy to retrieve
Returns
  • the bucket policy, or null, if not set

public BucketWebsiteConfiguration getBucketWebsiteConfiguration (String bucketName)

Answers the website of the given bucket. This operation requires the GetBucketWebsite permission. By default, only the bucket owner can read the bucket website configuration. However, bucket owners can allow other users to read the website configuration by writing a bucket policy granting them the GetBucketWebsite permission.

Parameters
bucketName The target bucket's name
Returns
  • a non null com.amazonaws.services.s3.model.BucketWebsiteConfiguration

public S3Object getObject (String bucketName, String key, String versionId, Date modifiedSince, Date unmodifiedSince)

Gets the object stored in Amazon S3 under the specified bucket and key. Returns null if the specified constraints weren't met. To get an object from Amazon S3, the caller must have Read access to the object. Callers should be very careful when using this method; the returned Amazon S3 object contains a direct stream of data from the HTTP connection. The underlying HTTP connection cannot be closed until the user finishes reading the data and closes the stream. Regarding conditional get constraints, Amazon S3 will ignore any dates occurring in the future.

Parameters
bucketName The object's bucket
key The object's key
versionId The specific version of the object to get its contents, if versioning is enabled. Left unspecified if the latest version is desired, or versioning is not enabled.
modifiedSince The modified constraint that restricts this request to executing only if the object has been modified after the specified date.
unmodifiedSince The unmodified constraint that restricts this request to executing only if the object has not been modified after this date.
Returns
  • the S3Object, or null, if conditional get constraints did not match

public InputStream getObjectContent (String bucketName, String key, String versionId, Date modifiedSince, Date unmodifiedSince)

Gets the content of an object stored in Amazon S3 under the specified bucket and key. Returns null if the specified constraints weren't met. To get an object's content from Amazon S3, the caller must have Read access to the object. Regarding conditional get constraints, Amazon S3 will ignore any dates occurring in the future.

Parameters
bucketName The object's bucket
key The object's key
versionId The specific version of the object to get its contents, if versioning is enabled, left unspecified if the latest version is desired, or versioning is not enabled.
modifiedSince The modified constraint that restricts this request to executing only if the object has been modified after the specified date.
unmodifiedSince The unmodified constraint that restricts this request to executing only if the object has not been modified after this date.
Returns
  • an input stream to the objects contents

public ObjectMetadata getObjectMetadata (String bucketName, String key, String versionId)

Gets the metadata for the specified Amazon S3 object without actually fetching the object itself. This is useful in obtaining only the object metadata, and avoids wasting bandwidth on fetching the object data.

Parameters
bucketName The object's bucket
key The object's key
versionId The object metadata for the given bucketName and key
Returns
  • the non null object metadata

public String getProxyHost ()

public String getProxyPassword ()

public int getProxyPort ()

public String getProxyUsername ()

public boolean isConnected ()

public List<Bucket> listBuckets ()

Answers a list of all Amazon S3 buckets that the authenticated sender of the request owns. Users must authenticate with a valid AWS Access Key ID that is registered with Amazon S3. Anonymous requests cannot list buckets, and users cannot list buckets that they did not create.

Returns
  • a non null list of com.amazonaws.services.s3.model.Bucket

public Iterable<S3VersionSummary> listObjectVersions (String bucketName)

Lazily lists all object versions for a given bucket that has versioning enabled. As S3 does not limit in any way the number of objects, such listing can retrieve an arbitrary amount of object versions, and may need to perform extra calls to the api while it is iterated.

Parameters
bucketName The target bucket's name
Returns
  • An iterable

public Iterable<S3ObjectSummary> listObjects (String bucketName, String prefix)

Lazily lists all objects for a given prefix. As S3 does not limit in any way the number of objects, such listing can retrieve an arbitrary amount of objects, and may need to perform extra calls to the api while it is iterated.

Parameters
bucketName The target bucket's name
prefix The prefix of the objects to be listed. If unspecified, all objects are listed
Returns
  • An iterable

public void setBucketPolicy (String bucketName, String policyText)

Sets the bucket's policy, overriding any previously set. Only the owner of the bucket can set a bucket policy. Bucket policies provide access control management at the bucket level for both the bucket resource and contained object resources. Only one policy can be specified per-bucket.

Parameters
bucketName The bucket name
policyText The policy text

public void setBucketVersioningStatus (String bucketName, VersioningStatus versioningStatus)

Sets the versioning status for the given bucket. A bucket's versioning configuration can be in one of three possible states: Off, Enabled and Suspended. By default, new buckets are in the Off state. Once versioning is enabled for a bucket the status can never be reverted to Off.

Parameters
bucketName The target bucket name
versioningStatus The version status to set

public void setBucketWebsiteConfiguration (String bucketName, String suffix, String errorDocument)

Sets the given bucket's website configuration. This operation requires the PutBucketWebsite permission. By default, only the bucket owner can configure the website attached to a bucket. However, bucket owners can allow other users to set the website configuration by writing a bucket policy granting them the S3:PutBucketWebsite permission.

Parameters
bucketName The target bucket's name
suffix The document to serve when a directory is specified, relative to the requested resource
errorDocument The full path to error document the bucket will use as error page for 4XX errors

public void setClient (SimpleAmazonS3 client)

Parameters
client

public void setObjectStorageClass (String bucketName, String key, StorageClass storageClass)

Sets the Amazon S3 storage class for the given object. Changing the storage class of an object in a bucket that has enabled versioning creates a new version of the object with the new storage class. The existing version of the object preservers the previous storage class.

Parameters
bucketName The object's bucket name
key The object's key
storageClass The storage class to set

public void setProxyHost (String proxyHost)

Parameters
proxyHost

public void setProxyPassword (String proxyPassword)

Parameters
proxyPassword

public void setProxyPort (Integer proxyPort)

Parameters
proxyPort

public void setProxyUsername (String proxyUsername)

Parameters
proxyUsername