com.amazonaws.services.dynamodbv2.datamodeling

Class S3Link

java.lang.Object

com.amazonaws.services.dynamodbv2.datamodeling.S3Link

public class S3Link
extends Object

An S3 Link that works with DynamoDBMapper. An S3 link is persisted as a JSON string in DynamoDB. This link object can be used directly to upload/download files to S3. Alternatively, the underlying AmazonS3Client and TransferManager can be retrieved to provide full access API to S3.

For example:

 AWSCredentialsProvider s3CredentialProvider = ...;
 DynamoDBMapper mapper = new DynamoDBMapper(..., s3CredentialProvider);
 String username = "jamestkirk";

 User user = new User();
 user.setUsername(username);

 // S3 region can be specified, but is optional
 S3Link s3link = mapper.createS3Link("my-company-user-avatars", username + ".jpg");
 user.setAvatar(s3link);

 // All meta information of the S3 resource is persisted in DynamoDB, including
 // region, bucket, and key
 mapper.save(user);

 // Upload file to S3 with the link saved in DynamoDB
 s3link.uploadFrom(new File("/path/to/all/those/user/avatars/" + username + ".jpg"));
 // Download file from S3 via an S3Link
 s3link.downloadTo(new File("/path/to/downloads/" + username + ".jpg"));

 // Full S3 API is available via the canonical AmazonS3Client and TransferManager API.
 // For example:
 AmazonS3Client s3 = s3link.getAmazonS3Client();
 TransferManager s3m = s3link.getTransferManager();
 // etc.
 

The User pojo class used above:

 @DynamoDBTable(tableName = "user-table")
 public class User {
     private String username;
     private S3Link avatar;

     @DynamoDBHashKey
     public String getUsername() {
         return username;
     }

     public void setUsername(String username) {
         this.username = username;
     }

     public S3Link getAvatar() {
         return avatar;
     }

     public void setAvatar(S3Link avatar) {
         this.avatar = avatar;
     }
 }
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	S3Link.Factory S3Link factory.

Method Summary

Modifier and Type	Method and Description
ObjectMetadata	downloadTo(File destination) Convenient method to synchronously download to the specified file from the S3 object represented by this S3Link.
ObjectMetadata	downloadTo(File destination, RequestMetricCollector requestMetricCollector) Same as downloadTo(File) but allows specifying a request metric collector.
ObjectMetadata	downloadTo(OutputStream output) Downloads the data from the object represented by this S3Link to the specified output stream.
ObjectMetadata	downloadTo(OutputStream output, RequestMetricCollector requestMetricCollector) Same as downloadTo(OutputStream) but allows specifying a request metric collector.
static S3Link	fromJson(S3ClientCache s3cc, String json) Deserializes from a JSON string.
AmazonS3	getAmazonS3Client()
String	getBucketName()
String	getKey()
String	getRegion() Returns the S3 region as string.
Region	getS3Region() Returns the S3 region in Region format.
TransferManager	getTransferManager()
URL	getUrl() Returns a URL for the location of the object represented by this S3Link.
void	setAcl(AccessControlList acl) Sets the access control list for the object represented by this S3Link.
void	setAcl(AccessControlList acl, RequestMetricCollector requestMetricCollector) Same as setAcl(AccessControlList) but allows specifying a request metric collector.
void	setAcl(CannedAccessControlList acl) Sets the access control list for the object represented by this S3Link.
void	setAcl(CannedAccessControlList acl, RequestMetricCollector col)
String	toJson() Serializes into a JSON string.
PutObjectResult	uploadFrom(byte[] buffer) Convenience method to synchronously upload from the given buffer to the Amazon S3 object represented by this S3Link.
PutObjectResult	uploadFrom(byte[] buffer, RequestMetricCollector requestMetricCollector) Same as uploadFrom(byte[]) but allows specifying a request metric collector.
PutObjectResult	uploadFrom(File source) Convenience method to synchronously upload from the given file to the Amazon S3 object represented by this S3Link.
PutObjectResult	uploadFrom(File source, RequestMetricCollector requestMetricCollector) Same as uploadFrom(File) but allows specifying a request metric collector.

Methods inherited from class java.lang.Object

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

Method Detail

getKey

public String getKey()

getBucketName

public String getBucketName()

getS3Region

public Region getS3Region()

Returns the S3 region in Region format.

Do not use this method if S3Link is created with a region not in Region enum. Use getRegion() instead.

Returns:

S3 region.

getRegion

public String getRegion()

Returns the S3 region as string.

Returns:

region provided when creating the S3Link object. If no region is provided during S3Link creation, returns us-east-1.

toJson

public String toJson()

Serializes into a JSON string.

Returns:

The string representation of the link to the S3 resource.

fromJson

public static S3Link fromJson(S3ClientCache s3cc,
                              String json)

Deserializes from a JSON string.

getAmazonS3Client

public AmazonS3 getAmazonS3Client()

getTransferManager

public TransferManager getTransferManager()

uploadFrom

public PutObjectResult uploadFrom(File source)

Convenience method to synchronously upload from the given file to the Amazon S3 object represented by this S3Link.

Parameters:

source - source file to upload from

Returns:

A PutObjectResult object containing the information returned by Amazon S3 for the newly created object.

uploadFrom

public PutObjectResult uploadFrom(File source,
                                  RequestMetricCollector requestMetricCollector)

Same as uploadFrom(File) but allows specifying a request metric collector.

uploadFrom

public PutObjectResult uploadFrom(byte[] buffer)

Convenience method to synchronously upload from the given buffer to the Amazon S3 object represented by this S3Link.

Parameters:

buffer - The buffer containing the data to upload.

Returns:

A PutObjectResult object containing the information returned by Amazon S3 for the newly created object.

uploadFrom

public PutObjectResult uploadFrom(byte[] buffer,
                                  RequestMetricCollector requestMetricCollector)

Same as uploadFrom(byte[]) but allows specifying a request metric collector.

setAcl

public void setAcl(CannedAccessControlList acl)

Sets the access control list for the object represented by this S3Link. Note: Executing this method requires that the object already exists in Amazon S3.

Parameters:

acl - The access control list describing the new permissions for the object represented by this S3Link.

setAcl

public void setAcl(CannedAccessControlList acl,
                   RequestMetricCollector col)

setAcl

public void setAcl(AccessControlList acl)

Sets the access control list for the object represented by this S3Link. Note: Executing this method requires that the object already exists in Amazon S3.

Parameters:

acl - The access control list describing the new permissions for the object represented by this S3Link.

setAcl

public void setAcl(AccessControlList acl,
                   RequestMetricCollector requestMetricCollector)

Same as setAcl(AccessControlList) but allows specifying a request metric collector.

getUrl

public URL getUrl()

Returns a URL for the location of the object represented by this S3Link.

If the object represented by this S3Link has public read permissions (ex: CannedAccessControlList.PublicRead), then this URL can be directly accessed to retrieve the object data.

Returns:

A URL for the location of the object represented by this S3Link.

downloadTo

public ObjectMetadata downloadTo(File destination)

Convenient method to synchronously download to the specified file from the S3 object represented by this S3Link.

Parameters:

destination - destination file to download to

Returns:

All S3 object metadata for the specified object. Returns null if constraints were specified but not met.

downloadTo

public ObjectMetadata downloadTo(File destination,
                                 RequestMetricCollector requestMetricCollector)

Same as downloadTo(File) but allows specifying a request metric collector.

downloadTo

public ObjectMetadata downloadTo(OutputStream output)

Downloads the data from the object represented by this S3Link to the specified output stream.

Parameters:

output - The output stream to write the object's data to.

Returns:

The object's metadata.

downloadTo

public ObjectMetadata downloadTo(OutputStream output,
                                 RequestMetricCollector requestMetricCollector)

Same as downloadTo(OutputStream) but allows specifying a request metric collector.