s3Service.copyVersionedObject(finalVersionId,
vBucketName, "versioned-object",
"destination-bucket", new S3Object("copied-from-version"),
false, null, null, null, null);
AccessControlList versionedObjectAcl =
s3Service.getVersionedObjectAcl(finalVersionId,
vBucketName, "versioned-object");
s3Service.putVersionedObjectAcl(finalVersionId,
vBucketName, "versioned-object", versionedObjectAcl);
// To delete an object version once-and-for-all you must use the
// versioning-specific delete operation, and you can only do so
// if you are the owner of the bucket containing the version.
s3Service.deleteVersionedObject(finalVersionId,
vBucketName, "versioned-object");
// You can easily delete all the versions of an object using
// one of JetS3t's multi-threaded services.
versions = s3Service.getObjectVersions(vBucketName, "versioned-object");
// Convert version and delete marker objects into versionId strings.
String[] versionIds = BaseVersionOrDeleteMarker.toVersionIds(versions);
(new S3ServiceSimpleMulti(s3Service)).deleteVersionsOfObject(
versionIds, vBucketName, "versioned-object");
//////////////////////////////////////////////////////////////
// For additional data protection you can require multi-factor
// authentication (MFA) to delete object versions.
//////////////////////////////////////////////////////////////
// Require multi-factor authentication to delete versions.
s3Service.enableBucketVersioningAndMFA(vBucketName);
// Check MFA status for the bucket
versioningStatus = s3Service.getBucketVersioningStatus(vBucketName);
System.out.println("Multi-factor auth required to delete versions ? "
+ versioningStatus.isMultiFactorAuthDeleteRequired());
// If MFA is enabled for a bucket you must provide the serial number
// for your multi-factor authentication device and a recent code to
// delete object versions.
String multiFactorSerialNumber = "#111222333";
String multiFactorAuthCode = "12345678";
s3Service.deleteVersionedObjectWithMFA(finalVersionId,
multiFactorSerialNumber, multiFactorAuthCode, vBucketName, "versioned-object");
// With MFA enabled, you must provide your multi-factor auth credentials
// to disable MFA.
s3Service.disableMFAForVersionedBucket(vBucketName,
multiFactorSerialNumber, multiFactorAuthCode);
// With MFA enabled, you must provide your multi-factor auth credentials
// to suspend S3 versioning altogether. However, the credentials will not
// be needed if you have already disabled MFA.
s3Service.suspendBucketVersioningWithMFA(vBucketName,
multiFactorSerialNumber, multiFactorAuthCode);
/* *****************
* Advanced Examples
* *****************
*/
/*
* Managing Metadata
*/
// S3Objects can contain metadata stored as name/value pairs. This metadata is stored in
// S3 and can be accessed when an object is retrieved from S3 using getObject
// or getObjectDetails methods. To store metadata with an object, add your metadata to
// the object prior to uploading it to S3.
// Note that metadata cannot be updated in S3 without replacing the existing object,
// and that metadata names must be strings without spaces.
S3Object objectWithMetadata = new S3Object("metadataObject");
objectWithMetadata.addMetadata("favourite-colour", "blue");
objectWithMetadata.addMetadata("document-version", "0.3");
/*
* Save and load encrypted AWS Credentials
*/
// AWS credentials are your means to login to and manage your S3 account, and should be
// kept secure. The JetS3t toolkit stores these credentials in AWSCredentials objects.
// The AWSCredentials class provides utility methods to allow credentials to be saved to
// an encrypted file and loaded from a previously saved file with the right password.
// Save credentials to an encrypted file protected with a password.
File credFile = new File("awscredentials.enc");
awsCredentials.save("password", credFile);
// Load encrypted credentials from a file.
ProviderCredentials loadedCredentials = AWSCredentials.load("password", credFile);
System.out.println("AWS Key loaded from file: " + loadedCredentials.getAccessKey());
// You won't get far if you use the wrong password...
try {
loadedCredentials = AWSCredentials.load("wrongPassword", credFile);
} catch (S3ServiceException e) {
System.err.println("Cannot load credentials from file with the wrong password!");
}
/*
* Manage Access Control Lists
*/
// S3 uses Access Control Lists to control who has access to buckets and objects in S3.
// By default, any bucket or object you create will belong to you and will not be accessible
// to anyone else. You can use JetS3t's support for access control lists to make buckets or
// objects publicly accessible, or to allow other S3 members to access or manage your objects.
// The ACL capabilities of S3 are quite involved, so to understand this subject fully please
// consult Amazon's documentation. The code examples below show how to put your understanding
// of the S3 ACL mechanism into practice.
// ACL settings may be provided with a bucket or object when it is created, or the ACL of
// existing items may be updated. Let's start by creating a bucket with default (i.e. private)
// access settings, then making it public.
// Create a bucket in S3.
S3Bucket publicBucket = new S3Bucket(awsCredentials.getAccessKey() + ".publicBucket");
s3Service.createBucket(publicBucket);
// Retrieve the bucket's ACL and modify it to grant public access,
// ie READ access to the ALL_USERS group.
AccessControlList bucketAcl = s3Service.getBucketAcl(publicBucket);
bucketAcl.grantPermission(GroupGrantee.ALL_USERS, Permission.PERMISSION_READ);
// Update the bucket's ACL. Now anyone can view the list of objects in this bucket.
publicBucket.setAcl(bucketAcl);
s3Service.putBucketAcl(publicBucket);
System.out.println("View bucket's object listing here: http://s3.amazonaws.com/"
+ publicBucket.getName());
// Now let's create an object that is public from scratch. Note that we will use the bucket's
// public ACL object created above, this works fine. Although it is possible to create an
// AccessControlList object from scratch, this is more involved as you need to set the
// ACL's Owner information which is only readily available from an existing ACL.
// Create a public object in S3. Anyone can download this object.
S3Object publicObject = new S3Object(
"publicObject.txt", "This object is public");
publicObject.setAcl(bucketAcl);
s3Service.putObject(publicBucket, publicObject);
System.out.println("View public object contents here: http://s3.amazonaws.com/"
+ publicBucket.getName() + "/" + publicObject.getKey());
// The ALL_USERS Group is particularly useful, but there are also other grantee types
// that can be used with AccessControlList. Please see Amazon's S3 technical documentation
// for a fuller discussion of these settings.
AccessControlList acl = new AccessControlList();
// Grant access by email address. Note that this only works email address of AWS S3 members.
acl.grantPermission(new EmailAddressGrantee("someone@somewhere.com"),
Permission.PERMISSION_FULL_CONTROL);
// Grant control of ACL settings to a known AWS S3 member.
acl.grantPermission(new CanonicalGrantee("AWS member's ID"),
Permission.PERMISSION_READ_ACP);
acl.grantPermission(new CanonicalGrantee("AWS member's ID"),
Permission.PERMISSION_WRITE_ACP);
/*
* Bucket Policies -- offer a greater degree of access control for a bucket.
*/