Class AmazonS3
This client uses the REST API to communicate with the Amazon S3 servers and read or write content through a bucket that the user has access to. It is a very lightweight implementation of the S3 API and therefore does not have all of the bells and whistles of popular client implementations.
Authentication is always performed using the user's AWSAccessKeyId and their private AWSSecretAccessKey.
Optional client-side encryption may be enabled if requested. The format is compatible with jets3t, a popular Java based Amazon S3 client library. Enabling encryption can hide sensitive data from the operators of the S3 service.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static final class
KeyInfo enables sorting of keys by lastModified time(package private) static interface
Property names used in amazon connection configuration file.private final class
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final String
ACL to apply to created objects.private final String
S3 Bucket Domain.private final WalkEncryption
Encryption algorithm, may be a null instance that provides pass-through.private static final String
(package private) final int
Maximum number of times to try an operation.private final SecretKeySpec
Decoded form of the private AWSSecretAccessKey, to sign requests.private final ProxySelector
Our HTTP proxy support, in case we are behind a firewall.private final String
AWSAccessKeyId, public string that identifies the user's account.private final File
Directory for locally buffered content.private static final String
private static final String
-
Constructor Summary
ConstructorsConstructorDescriptionAmazonS3
(Properties props) Create a new S3 client for the supplied user information. -
Method Summary
Modifier and TypeMethodDescription(package private) void
beginPut
(String bucket, String key, ProgressMonitor monitor, String monitorTask) Atomically create or replace a single large object.Decrypt an input stream fromget(String, String)
.void
Delete a single object.(package private) IOException
error
(String action, String key, HttpURLConnection c) Get the content of a bucket object.private static String
httpNow()
private static boolean
isSignedHeader
(String name) List the names of keys available within a bucket.(package private) IOException
maxAttempts
(String action, String key) private static MessageDigest
newMD5()
private HttpURLConnection
(package private) HttpURLConnection
(package private) static Properties
properties
(File authFile) void
Atomically create or replace a single small object.(package private) void
putImpl
(String bucket, String key, byte[] csum, TemporaryBuffer buf, ProgressMonitor monitor, String monitorTask) private static String
private static String
toCleanString
(List<String> list)
-
Field Details
-
SIGNED_HEADERS
-
HMAC
- See Also:
-
X_AMZ_ACL
- See Also:
-
X_AMZ_META
- See Also:
-
publicKey
AWSAccessKeyId, public string that identifies the user's account. -
privateKey
Decoded form of the private AWSSecretAccessKey, to sign requests. -
proxySelector
Our HTTP proxy support, in case we are behind a firewall. -
acl
ACL to apply to created objects. -
maxAttempts
final int maxAttemptsMaximum number of times to try an operation. -
encryption
Encryption algorithm, may be a null instance that provides pass-through. -
tmpDir
Directory for locally buffered content. -
domain
S3 Bucket Domain.
-
-
Constructor Details
-
AmazonS3
Create a new S3 client for the supplied user information.The connection properties are a subset of those supported by the popular jets3t library. For example:
# AWS Access and Secret Keys (required) accesskey: <YourAWSAccessKey> secretkey: <YourAWSSecretKey> # Access Control List setting to apply to uploads, must be one of: # PRIVATE, PUBLIC_READ (defaults to PRIVATE). acl: PRIVATE # S3 Domain # AWS S3 Region Domain (defaults to s3.amazonaws.com) domain: s3.amazonaws.com # Number of times to retry after internal error from S3. httpclient.retry-max: 3 # End-to-end encryption (hides content from S3 owners) password: <encryption pass-phrase> crypto.algorithm: PBEWithMD5AndDES
- Parameters:
props
- connection properties.
-
-
Method Details
-
isSignedHeader
-
toCleanString
-
remove
-
httpNow
-
newMD5
-
get
Get the content of a bucket object.- Parameters:
bucket
- name of the bucket storing the object.key
- key of the object within its bucket.- Returns:
- connection to stream the content of the object. The request properties of the connection may not be modified by the caller as the request parameters have already been signed.
- Throws:
IOException
- sending the request was not possible.
-
decrypt
Decrypt an input stream fromget(String, String)
.- Parameters:
u
- connection previously created byget(String, String)
}.- Returns:
- stream to read plain text from.
- Throws:
IOException
- decryption could not be configured.
-
list
List the names of keys available within a bucket.This method is primarily meant for obtaining a "recursive directory listing" rooted under the specified bucket and prefix location. It returns the keys sorted in reverse order of LastModified time (freshest keys first).
- Parameters:
bucket
- name of the bucket whose objects should be listed.prefix
- common prefix to filter the results by. Must not be null. Supplying the empty string will list all keys in the bucket. Supplying a non-empty string will act as though a trailing '/' appears in prefix, even if it does not.- Returns:
- list of keys starting with
prefix
, after removingprefix
(orprefix + "/"
)from all of them. - Throws:
IOException
- sending the request was not possible, or the response XML document could not be parsed properly.
-
delete
Delete a single object.Deletion always succeeds, even if the object does not exist.
- Parameters:
bucket
- name of the bucket storing the object.key
- key of the object within its bucket.- Throws:
IOException
- deletion failed due to communications error.
-
put
Atomically create or replace a single small object.This form is only suitable for smaller contents, where the caller can reasonable fit the entire thing into memory.
End-to-end data integrity is assured by internally computing the MD5 checksum of the supplied data and transmitting the checksum along with the data itself.
- Parameters:
bucket
- name of the bucket storing the object.key
- key of the object within its bucket.data
- new data content for the object. Must not be null. Zero length array will create a zero length object.- Throws:
IOException
- creation/updating failed due to communications error.
-
beginPut
public OutputStream beginPut(String bucket, String key, ProgressMonitor monitor, String monitorTask) throws IOException Atomically create or replace a single large object.Initially the returned output stream buffers data into memory, but if the total number of written bytes starts to exceed an internal limit the data is spooled to a temporary file on the local drive.
Network transmission is attempted only when
close()
gets called at the end of output. Closing the returned stream can therefore take significant time, especially if the written content is very large.End-to-end data integrity is assured by internally computing the MD5 checksum of the supplied data and transmitting the checksum along with the data itself.
- Parameters:
bucket
- name of the bucket storing the object.key
- key of the object within its bucket.monitor
- (optional) progress monitor to post upload completion to during the stream's close method.monitorTask
- (optional) task name to display during the close method.- Returns:
- a stream which accepts the new data, and transmits once closed.
- Throws:
IOException
- if encryption was enabled it could not be configured.
-
putImpl
void putImpl(String bucket, String key, byte[] csum, TemporaryBuffer buf, ProgressMonitor monitor, String monitorTask) throws IOException - Throws:
IOException
-
error
- Throws:
IOException
-
maxAttempts
-
open
- Throws:
IOException
-
open
HttpURLConnection open(String method, String bucket, String key, Map<String, String> args) throws IOException- Throws:
IOException
-
authorize
- Throws:
IOException
-
properties
- Throws:
FileNotFoundException
IOException
-