Class 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 Detail

      • 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.
      • getAmazonS3Client

        public AmazonS3 getAmazonS3Client()
      • 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​(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.
      • 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​(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.
      • 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​(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.