Summary: Configuration | Message Processors

org.mule.modules

mule-module-s3

2.0

Namespace	http://www.mulesoft.org/schema/mule/s3
Schema Location	http://www.mulesoft.org/schema/mule/s3/2.0/mule-s3.xsd
Version	2.0
Minimum Mule Version	3.2

Module 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

Configuration
<s3:config> Configure an instance of this module

Message Processors
<s3:copy-object> 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.
<s3:create-bucket> Creates a new bucket; connector must not be configured as anonymous for this operation to succeed.
<s3:create-object> Uploads an object to S3.
<s3:create-object-presigned-uri> Returns a pre-signed URL for accessing an Amazon S3 object.
<s3:create-object-uri> Creates an http URI for the given object id.
<s3:delete-bucket> Deletes the specified bucket.
<s3:delete-bucket-policy> Deletes the bucket's policy.
<s3:delete-bucket-website-configuration> Removes the website configuration for a bucket; this operation requires the DeleteBucketWebsite permission.
<s3:delete-object> Deletes a given object, only the owner of the bucket containing the version can perform this operation.
<s3:get-bucket-policy> Answers the policy for the given bucket.
<s3:get-bucket-website-configuration> Answers the website of the given bucket.
<s3:get-object> Gets the object stored in Amazon S3 under the specified bucket and key.
<s3:get-object-content> Gets the content of an object stored in Amazon S3 under the specified bucket and key.
<s3:get-object-metadata> Gets the metadata for the specified Amazon S3 object without actually fetching the object itself.
<s3:list-buckets> Answers a list of all Amazon S3 buckets that the authenticated sender of the request owns.
<s3:list-object-versions> Lazily lists all object versions for a given bucket that has versioning enabled.
<s3:list-objects> Lazily lists all objects for a given prefix.
<s3:set-bucket-policy> Sets the bucket's policy, overriding any previously set.
<s3:set-bucket-versioning-status> Sets the versioning status for the given bucket.
<s3:set-bucket-website-configuration> Sets the given bucket's website configuration.
<s3:set-object-storage-class> Sets the Amazon S3 storage class for the given object.

Configuration

To use the this module within a flow the namespace to the module must be included. The resulting flow will look similar to the following:

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:s3="http://www.mulesoft.org/schema/mule/s3"
      xsi:schemaLocation="
               http://www.mulesoft.org/schema/mule/core
               http://www.mulesoft.org/schema/mule/core/current/mule.xsd
               http://www.mulesoft.org/schema/mule/s3
               http://www.mulesoft.org/schema/mule/s3/2.0/mule-s3.xsd">

      <!-- here goes your flows and configuration elements -->

</mule>

This module is configured using the config element. This element must be placed outside of your flows and at the root of your Mule application. You can create as many configurations as you deem necesary as long as each carries its own name.

Each message processor, message source or transformer carries a config-ref attribute that allows the invoker to specify which configuration to use.

Attributes
Type	Name	Default Value	Description
xs:string	name		Optional. Give a name to this configuration so it can be later referenced.
xs:string	proxyHost		Optional. The optional proxy port
xs:string	proxyPassword		Optional. The optional proxy password
xs:int	proxyPort		Optional. The optional proxy port
xs:string	proxyUsername		Optional. The optional proxy username

Connection Pool

This connector offers automatic connection management via the use of a connection pool. The pool will act a storage mechanism for all the connections that are in-use by the user of this connector.

Prior to execution of a processor, the connector will attempt to lookup an already established connection and if one doesn't exists it will create one. That lookup mechanism is done in the connection pool via the use of connection variables declared as keys.

The user of the connector can configure the pool by adding a connection-pooling-profile to the connector configuration like this:

    <s3:connection-pooling-profile maxActive="10" maxIdle="10"
                             exhaustedAction="WHEN_EXHAUSTED_GROW" maxWait="120"/>

The following is a list of connection attributes, each connection attribute can be configured at the config element level or they can also be added to each processor. If they are used at the processor level they get the benefit of full expression resolution.

Connection Attributes
Name	Description
accessKey	The access key provided by Amazon, needed for non annoynous operations
secretKey	The secrete key provided by Amazon, needed for non annoynous operations

Also this connector offers automatic retry for certain operations. There are a couple of situations in which a retry may solve the problem at hand, like for example if the system is currently busy or if the session has expired. Those kind of situations are solvable by reacquiring a connection and retrying the operation.

By default, the connector will automatically attempt to retry the operation only once. You can at your choosing specify a greater ammount of retries by using the retryMax attribute on each operation.

    ... retryMax="3"/>

Message Processors

<s3:copy-object>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
sourceBucketName		The source object's bucket
sourceKey		The source object's key
sourceVersionId		Optional. 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		Optional. 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		Optional. The acl of the destination object.
destinationStorageClass		Optional. One of `StorageClass` enumerated values, defaults to `STANDARD`
destinationUserMetadata		Optional. The new metadata of the destination object, that if specified, overrides that copied from the source object
modifiedSince		Optional. 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		Optional. 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
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

the version id of the new object, or null, if versioning is not enabled

<s3:create-bucket>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The bucket to create. It must not exist yet.
region		Optional. The region where to create the new bucket
acl		Optional. The access control list of the new bucket
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

the non null, new Bucket

<s3:create-object>

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

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The object's bucket
key		The object's key
content		The content to be uploaded to S3, capable of creating a PutObjectRequest.
contentLength		Optional. 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		Optional. The content md5, encoded in base 64. If content is a file, it is ignored.
contentType		Optional. The content type of the new object.
acl		Optional. The access control list of the new object
storageClass		Optional. The storage class of the new object
userMetadata		Optional. A map of arbitrary object properties keys and values
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

the id of the created object, or null, if versioning is not enabled

<s3:create-object-presigned-uri>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The object's bucket
key		The object's key
versionId		Optional. 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		Optional. The time at which the returned pre-signed URL will expire.
method		Optional. The HTTP method verb to use for this URL
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

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.

<s3:create-object-uri>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The object's bucket
key		The object's key
useDefaultServer		Optional. If the default US Amazon server subdomain should be used in the URI regardless of the region.
secure		Optional. Whether to use http or https
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

a non secure http URI to the object. Unlike the presigned URI, object must have PUBLIC_READ or PUBLIC_READ_WRITE permission

<s3:delete-bucket>

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

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The bucket to delete
force		Optional. Optional true if the bucket must be deleted even if it is not empty, false if operation should fail in such scenario.
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

<s3:delete-bucket-policy>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The bucket whose policy to delete
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

<s3:delete-bucket-website-configuration>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The bucket whose policy to delete
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

<s3:delete-object>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The object's bucket
key		The object's key
versionId		Optional. 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.
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

<s3:get-bucket-policy>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The bucket whose policy to retrieve
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

the bucket policy, or null, if not set

<s3:get-bucket-website-configuration>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The target bucket's name
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

a non null com.amazonaws.services.s3.model.BucketWebsiteConfiguration

<s3:get-object>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The object's bucket
key		The object's key
versionId		Optional. 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		Optional. The modified constraint that restricts this request to executing only if the object has been modified after the specified date.
unmodifiedSince		Optional. The unmodified constraint that restricts this request to executing only if the object has not been modified after this date.
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

the S3Object, or null, if conditional get constraints did not match

<s3:get-object-content>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The object's bucket
key		The object's key
versionId		Optional. 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		Optional. The modified constraint that restricts this request to executing only if the object has been modified after the specified date.
unmodifiedSince		Optional. The unmodified constraint that restricts this request to executing only if the object has not been modified after this date.
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

an input stream to the objects contents

<s3:get-object-metadata>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The object's bucket
key		The object's key
versionId		Optional. The object metadata for the given bucketName and key
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

the non null object metadata

<s3:list-buckets>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

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

<s3:list-object-versions>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The target bucket's name
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

An iterable

<s3:list-objects>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The target bucket's name
prefix		Optional. The prefix of the objects to be listed. If unspecified, all objects are listed
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

Return Payload

An iterable

<s3:set-bucket-policy>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The bucket name
policyText		The policy text
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

<s3:set-bucket-versioning-status>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The target bucket name
versioningStatus		The version status to set
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

<s3:set-bucket-website-configuration>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The target bucket's name
suffix		The document to serve when a directory is specified, relative to the requested resource
errorDocument		Optional. The full path to error document the bucket will use as error page for 4XX errors
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations

Child Elements

<s3:set-object-storage-class>

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.

XML Sample

INCLUDE_ERROR

Attributes

config-ref		Optional. Specify which configuration to use.
bucketName		The object's bucket name
key		The object's key
storageClass		The storage class to set
retryMax	1	Optional. Specify how many times this operation can be retried automatically
accessKey		Optional. The access key provided by Amazon, needed for non annoynous operations
secretKey		Optional. The secrete key provided by Amazon, needed for non annoynous operations