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;
     }
 }
 
  • Method Details

    • getKey

      public String getKey()
    • getBucketName

      public String getBucketName()
    • getS3Region

      public Region getS3Region()
    • 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.