org.mule.extension.s3.internal.operation

Class ObjectOperations

java.lang.Object

org.mule.connectors.commons.template.operation.ConnectorOperations<CONFIG,CONNECTION,SERVICE>

org.mule.extension.aws.commons.internal.operation.AWSOperations<S3Configuration,S3Connection,S>

org.mule.extension.s3.internal.operation.S3Operations<ObjectService>

org.mule.extension.s3.internal.operation.ObjectOperations

@Throws(value=S3ErrorTypeProvider.class)
public class ObjectOperations
extends S3Operations<ObjectService>

Field Summary

Fields inherited from class org.mule.extension.s3.internal.operation.S3Operations

DEFAULT_CANNED_ACL, NOT_ENCODED, REGION_DEFAULT

Constructor Summary

Constructors

Constructor and Description
ObjectOperations()

Method Summary

Modifier and Type	Method and Description
ObjectResult	copyObject(S3Configuration config, S3Connection connection, String sourceBucketName, String sourceKey, String sourceVersionId, String destinationBucketName, String destinationKey, CannedAccessControlList destinationAcl, StorageClass destinationStorageClass, Map<String,String> destinationUserMetadata, LocalDateTime modifiedSince, LocalDateTime unmodifiedSince, String encryption, String contentType) 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.
ObjectResult	createObject(S3Configuration config, S3Connection connection, String bucketName, String key, InputStream objectContent, ObjectMetadataParameterGroup objectMetadata, CannedAccessControlList acl, String kmsMasterKey) Uploads an object to S3.
String	createObjectPresignedUri(S3Configuration config, S3Connection connection, String bucketName, String key, LocalDateTime expiration, String contentMd5, String contentType, HttpMethod method, SSEAlgorithm sseS3Encryption) Returns a pre-signed URL for accessing an Amazon S3 object.
void	deleteObject(S3Configuration config, S3Connection connection, String bucketName, String key, String versionId) Deletes a given object, only the owner of the bucket containing the version can perform this operation.
void	deleteObjects(S3Configuration config, S3Connection connection, String bucketName, List<KeyVersion> keys) Deletes multiple objects in a single bucket from S3.
org.mule.runtime.extension.api.runtime.operation.Result<InputStream,S3ObjectAttributes>	getObject(S3Configuration config, S3Connection connection, String bucketName, String key, Range range, String versionId, LocalDateTime modifiedSince, LocalDateTime unmodifiedSince) Gets the object stored in Amazon S3 under the specified bucket and key.
org.mule.runtime.extension.api.runtime.operation.Result<List<Grant>,AccessControlListAttributes>	getObjectAcl(S3Configuration config, S3Connection connection, String bucketName, String key, String versionId) Returns the access control list (ACL) of an object.
ObjectMetadataParameterGroup	getObjectMetadata(S3Configuration config, S3Connection connection, String bucketName, String key, String versionId) Gets only the object metadata stored in Amazon S3 under the specified bucket and key.
org.mule.runtime.extension.api.runtime.streaming.PagingProvider<S3Connection,S3ObjectSummary>	listObjects(String bucketName, String prefix, String marker, String delimiter, Integer maxKeys, EncodingType encodingType) Lazily lists all objects for a given prefix.
org.mule.runtime.extension.api.runtime.streaming.PagingProvider<S3Connection,S3VersionSummary>	listVersions(String bucketName, String prefix, String keyMarker, String versionIdMarker, String delimiter, Integer maxResults, EncodingType encodingType) Lazily lists all object versions for a given bucket that has versioning enabled.
void	setObjectAcl(S3Configuration config, S3Connection connection, String bucketName, String key, String versionId, Owner owner, List<Grant> grants) Set the access control list (ACL) permissions for an object that already exists in a bucket
void	setObjectStorageClass(S3Configuration config, S3Connection connection, String bucketName, String key, StorageClass storageClass) Sets the Amazon S3 storage class for the given object.

Methods inherited from class org.mule.extension.aws.commons.internal.operation.AWSOperations

newExecutionBuilder

Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectOperations

public ObjectOperations()

Method Detail

createObject

public ObjectResult createObject(@Config
                                 S3Configuration config,
                                 @Connection
                                 S3Connection connection,
                                 String bucketName,
                                 String key,
                                 @Summary(value="The content to be uploaded to S3, capable of creating a {@link PutObjectRequest}.") @Content
                                 InputStream objectContent,
                                 @Summary(value="The additional information about the new object being created, such as content type & encoding, etc.") @ParameterGroup(name="Metadata")
                                 ObjectMetadataParameterGroup objectMetadata,
                                 @DisplayName(value="Canned ACL") @Optional(defaultValue="PRIVATE")
                                 CannedAccessControlList acl,
                                 @Optional
                                 String kmsMasterKey)

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

Parameters:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

bucketName - the object's bucket

key - the object's key

objectContent - the content to be uploaded to S3, capable of creating a PutObjectRequest.

objectMetadata - the additional information about the new object being created, such as content type & encoding, etc.

acl - the access control list of the new object

kmsMasterKey - Encrypt objects uploaded to S3 buckets with AWS KMS master key

Returns:

the objectResult of the created object.

deleteObject

public void deleteObject(@Config
                         S3Configuration config,
                         @Connection
                         S3Connection connection,
                         String bucketName,
                         String key,
                         @Optional
                         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:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

bucketName - the object's bucket

key - the object's key

versionId - the specific version of the object to delete, if versioning is enabled.

deleteObjects

public void deleteObjects(@Config
                          S3Configuration config,
                          @Connection
                          S3Connection connection,
                          String bucketName,
                          List<KeyVersion> keys)

Deletes multiple objects in a single bucket from S3. Version of the keys is optional.

In some cases, some objects will be successfully deleted, while some attempts will cause an error. If any object in the request cannot be deleted, this method throws a MultiObjectDeleteException with details of the error.

Parameters:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

bucketName - the objects bucket name

keys - the objects keys, version is optional

listObjects

public org.mule.runtime.extension.api.runtime.streaming.PagingProvider<S3Connection,S3ObjectSummary> listObjects(String bucketName,
                                                                                                                 @Optional
                                                                                                                 String prefix,
                                                                                                                 @Summary(value="Where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker.") @Optional
                                                                                                                 String marker,
                                                                                                                 @Summary(value="Causes keys that contain the same string between a prefix and the first occurrence of the delimiter to be rolled up into a single result element.") @Optional
                                                                                                                 String delimiter,
                                                                                                                 @Summary(value="The maximum number of keys to return per page. If not specified S3 will limit the number of returned results per page.") @Optional
                                                                                                                 Integer maxKeys,
                                                                                                                 @Optional(defaultValue="NOT_ENCODED")
                                                                                                                 EncodingType encodingType)

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

marker - where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker

delimiter - causes keys that contain the same string between a prefix and the first occurrence of the delimiter to be rolled up into a single result element.

maxKeys - The maximum number of keys to return per page. If not specified S3 will limit the number of returned results per page.

encodingType - The encoding method to be applied on the response.

Returns:

An iterable

setObjectStorageClass

public void setObjectStorageClass(@Config
                                  S3Configuration config,
                                  @Connection
                                  S3Connection connection,
                                  String bucketName,
                                  String key,
                                  @Content @Optional(defaultValue="STANDARD")
                                  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:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

bucketName - the object's bucket name

key - the object's key

storageClass - the storage class to set

setObjectAcl

public void setObjectAcl(@Config
                         S3Configuration config,
                         @Connection
                         S3Connection connection,
                         String bucketName,
                         String key,
                         @Optional
                         String versionId,
                         Owner owner,
                         @Content
                         List<Grant> grants)

Set the access control list (ACL) permissions for an object that already exists in a bucket

Parameters:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

bucketName - the object's bucket name

key - the object's key

versionId - the specific version of the object

owner - the owner of the ACL

grants - the Grants of the ACL

copyObject

public ObjectResult copyObject(@Config
                               S3Configuration config,
                               @Connection
                               S3Connection connection,
                               @Placement(order=1)
                               String sourceBucketName,
                               @Placement(order=2)
                               String sourceKey,
                               @Placement(order=3) @Summary(value="The specific version of the source object to copy, if versioning is enabled. ") @Optional
                               String sourceVersionId,
                               @Placement(order=4) @Summary(value="The destination object\'s bucket. If none provided, object is copied within the same bucket.") @Optional
                               String destinationBucketName,
                               @Placement(order=5)
                               String destinationKey,
                               @Placement(order=6) @DisplayName(value="Canned ACL") @Optional(defaultValue="PRIVATE")
                               CannedAccessControlList destinationAcl,
                               @Placement(order=7) @Summary(value="One of {@link StorageClass} enumerated values, defaults to {@link StorageClass#STANDARD}") @Optional(defaultValue="STANDARD")
                               StorageClass destinationStorageClass,
                               @Placement(order=8) @Summary(value="The new metadata of the destination object. If specified, overrides that copied from the source object") @Optional @NullSafe
                               Map<String,String> destinationUserMetadata,
                               @Placement(order=9) @Summary(value="The modified constraint that restricts this request to executing only if the object has been modified after the specified date. ") @Optional
                               LocalDateTime modifiedSince,
                               @Placement(order=10) @Summary(value="The unmodified constraint that restricts this request to executing only if the object has not been modified after this date. ") @Optional
                               LocalDateTime unmodifiedSince,
                               @Placement(order=11) @Optional
                               String encryption,
                               @Placement(order=12) @Optional
                               String contentType)

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 AccessControlList 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. Destination object's Content-Type http header would be set with the specified value and if it is passed null, then the default MIME type 'application/octet-stream' would be set.

Parameters:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

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.

destinationBucketName - the destination object's bucket. If none provided, object 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 StorageClass.STANDARD

destinationUserMetadata - the new metadata of the destination object. 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.

unmodifiedSince - The unmodified constraint that restricts this request to executing only if the object has not been modified after this date.

encryption - Encryption method for server-side encryption. Supported value AES256.

contentType - the destination object's Content-Type HTTP header

Returns:

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

createObjectPresignedUri

@MediaType(value="text/plain")
public String createObjectPresignedUri(@Config
                                                                      S3Configuration config,
                                                                      @Connection
                                                                      S3Connection connection,
                                                                      String bucketName,
                                                                      String key,
                                                                      @Summary(value="The expiration date at which point the new pre-signed URL will no longer be accepted by Amazon S3.") @Optional
                                                                      LocalDateTime expiration,
                                                                      @DisplayName(value="Content MD5") @Optional
                                                                      String contentMd5,
                                                                      @Optional
                                                                      String contentType,
                                                                      @Optional(defaultValue="PUT")
                                                                      HttpMethod method,
                                                                      @Optional
                                                                      SSEAlgorithm sseS3Encryption)

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:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

bucketName - the name of the bucket involved in this request.

key - the key of the object involved in this request.

expiration - the expiration date at which point the new pre-signed URL will no longer be accepted by Amazon S3.

contentMd5 - the expected content-md5 header of the request.

contentType - the expected content-type of the request.

method - the HTTP method (GET, PUT, DELETE, HEAD) to be used in this request.

sseS3Encryption - the encryption method (KMS, AES256) to use for the presigned URL. This field is not allowed for the HTTP GET method. If you set a value for this field and use the HTTP GET method, you will get an error.

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.

getObject

@MediaType(value="application/octet-stream",
           strict=false)
public org.mule.runtime.extension.api.runtime.operation.Result<InputStream,S3ObjectAttributes> getObject(@Config
                                                                                                                                                                               S3Configuration config,
                                                                                                                                                                               @Connection
                                                                                                                                                                               S3Connection connection,
                                                                                                                                                                               String bucketName,
                                                                                                                                                                               String key,
                                                                                                                                                                               @Summary(value="Specify these parameters in order to define range bytes of an object which is being downloaded.") @ParameterGroup(name="Range",showInDsl=true) @Placement(tab="Advanced")
                                                                                                                                                                               Range range,
                                                                                                                                                                               @Summary(value="The specific version of the object to get its contents, if versioning is enabled. ") @Optional
                                                                                                                                                                               String versionId,
                                                                                                                                                                               @Summary(value="The modified constraint that restricts this request to executing only if the object has been modified after the specified date.") @Optional
                                                                                                                                                                               LocalDateTime modifiedSince,
                                                                                                                                                                               @Summary(value="The unmodified constraint that restricts this request to executing only if the object has not been modified after this date.") @Optional
                                                                                                                                                                               LocalDateTime 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 Permission.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:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

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.

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

getObjectMetadata

public ObjectMetadataParameterGroup getObjectMetadata(@Config
                                                      S3Configuration config,
                                                      @Connection
                                                      S3Connection connection,
                                                      String bucketName,
                                                      String key,
                                                      @Summary(value="The specific version of the object to get its contents, if versioning is enabled. ") @Optional
                                                      String versionId)

Gets only the object metadata stored in Amazon S3 under the specified bucket and key. To get an object metadata from Amazon S3, the caller must have Permission.Read access to the object.

Parameters:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

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.

Returns:

the ObjectMetadata

getObjectAcl

public org.mule.runtime.extension.api.runtime.operation.Result<List<Grant>,AccessControlListAttributes> getObjectAcl(@Config
                                                                                                                     S3Configuration config,
                                                                                                                     @Connection
                                                                                                                     S3Connection connection,
                                                                                                                     String bucketName,
                                                                                                                     String key,
                                                                                                                     @Optional
                                                                                                                     String versionId)

Returns the access control list (ACL) of an object. By default, GET returns ACL information about the current version of an object. To return ACL information about a different version, use the versionId attribute.

Parameters:

config - Configuration for Amazon S3 connector.

connection - Amazon S3 connection instance.

bucketName - the object's bucket

key - the object's key

versionId - the object's version id

Returns:

the access control list

listVersions

public org.mule.runtime.extension.api.runtime.streaming.PagingProvider<S3Connection,S3VersionSummary> listVersions(String bucketName,
                                                                                                                   @Summary(value="Optional parameter restricting the response to keys which begin with the specified prefix. ") @Optional
                                                                                                                   String prefix,
                                                                                                                   @Summary(value="Where in the sorted list of all versions in the specified bucket to begin returning results. Results are always ordered first alphabetically and then from most recent version to least recent version. ") @Optional
                                                                                                                   String keyMarker,
                                                                                                                   @Summary(value="Where in the sorted list of all versions in the specified bucket to begin returning results. Results are always ordered first alphabetically and then from most recent version to least recent version.") @Optional
                                                                                                                   String versionIdMarker,
                                                                                                                   @Summary(value="Causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the list. ") @Optional
                                                                                                                   String delimiter,
                                                                                                                   @Summary(value="The maximum number of results to return per page. If not specified, S3 will limit the number of returned results per page.") @Optional
                                                                                                                   Integer maxResults,
                                                                                                                   @Summary(value="The encoding method to be applied on the response. ") @Optional(defaultValue="NOT_ENCODED")
                                                                                                                   EncodingType encodingType)

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

prefix - optional parameter restricting the response to keys which begin with the specified prefix.

keyMarker - where in the sorted list of all versions in the specified bucket to begin returning results. Results are always ordered first alphabetically and then from most recent version to least recent version.

versionIdMarker - where in the sorted list of all versions in the specified bucket to begin returning results. Results are always ordered first alphabetically and then from most recent version to least recent version.

delimiter - causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the list.

maxResults - The maximum number of results to return per page. If not specified, S3 will limit the number of returned results per page.

encodingType - the encoding method to be applied on the response.

Returns:

An iterable