net.noderunner.amazon.s3
Class Connection

java.lang.Object
  extended by net.noderunner.amazon.s3.Connection

public class Connection
extends Object

A stateless connection to the Amazon S3 system which uses the REST API.

It is initially configured with authentication and connection parameters and exposes methods to access and manipulate S3 data.


Field Summary
static String DEFAULT_HOST
          Default hostname.
static int EXPECT_SIZE
          Data larger than 1024 bytes will use expect headers.
static int INSECURE_PORT
          HTTP port.
static String LOCATION_DEFAULT
          Location default.
static String LOCATION_EU
          Location in Europe.
static int SECURE_PORT
          HTTPS port.
 
Constructor Summary
Connection(String awsAccessKeyId, String awsSecretAccessKey)
          Constructs a new Connection.
Connection(String awsAccessKeyId, String awsSecretAccessKey, boolean isSecure)
          Constructs a new Connection.
Connection(String awsAccessKeyId, String awsSecretAccessKey, boolean isSecure, String server)
          Constructs a new Connection.
Connection(String awsAccessKeyId, String awsSecretAccessKey, boolean isSecure, String server, CallingFormat format)
          Constructs a new Connection.
Connection(String awsAccessKeyId, String awsSecretAccessKey, boolean isSecure, String server, int port)
          Constructs a new Connection.
Connection(String awsAccessKeyId, String awsSecretAccessKey, boolean isSecure, String server, int port, CallingFormat format)
          Create a new interface to interact with S3 with the given credential and connection parameters
 
Method Summary
 Response create(Bucket bucket)
          Creates a new bucket.
 Response create(Bucket bucket, String location)
          Creates a new bucket with a location.
 Response create(Bucket bucket, String location, Headers headers)
          Creates a new bucket.
 Response delete(Bucket bucket)
          Deletes a bucket.
 Response delete(Bucket bucket, Headers headers)
          Deletes a bucket.
 Response delete(Bucket bucket, String key)
          Deletes an object from S3.
 Response delete(Bucket bucket, String key, Headers headers)
          Deletes an object from S3.
 boolean exists(Bucket bucket)
          Check if the specified bucket exists (via a HEAD request)
 GetResponse get(Bucket bucket, String key)
          Reads an object from S3.
 GetResponse get(Bucket bucket, String key, Headers headers)
          Reads an object from S3.
 GetResponse getACL(Bucket bucket, Headers headers)
          Get the ACL for a given bucket
 GetResponse getACL(Bucket bucket, String key, Headers headers)
          Get the ACL for a given object (or bucket, if key is null).
 GetResponse getBucketLogging(Bucket bucket, Headers headers)
          Get the logging xml document for a given bucket
 LocationResponse getLocation(Bucket bucket)
          Returns the bucket location.
 GetStreamResponse getStream(Bucket bucket, String key)
          Reads an object from S3, returning a stream to access the data.
 GetStreamResponse getStream(Bucket bucket, String key, Headers headers)
          Reads an object from S3, returning a stream to access the data.
 Response head(Bucket bucket, String key)
          Returns information about an S3 object without loading it.
 Response head(Bucket bucket, String key, Headers headers)
          Returns information about an S3 object without loading it.
 ListResponse list(Bucket bucket)
          Lists the contents of a bucket.
 ListResponse list(Bucket bucket, Integer maxKeys)
          Lists the contents of a bucket.
 ListResponse list(Bucket bucket, String prefix)
          Lists the contents of a bucket by prefix.
 ListResponse list(Bucket bucket, String prefix, String marker, Integer maxKeys)
          Lists the contents of a bucket.
 ListResponse list(Bucket bucket, String prefix, String marker, Integer maxKeys, Headers headers)
          Lists the contents of a bucket.
 ListResponse list(Bucket bucket, String prefix, String marker, Integer maxKeys, String delimiter, Headers headers)
          Lists the contents of a bucket.
 ListAllBucketsResponse listAllBuckets()
          Lists all the buckets created by this account.
 ListAllBucketsResponse listAllBuckets(Headers headers)
          Lists all the buckets created by this account.
 Response put(Bucket bucket, String key, S3Object object)
          Writes an object to S3.
 Response put(Bucket bucket, String key, S3Object object, Headers headers)
          Writes an object to S3.
 Response putACL(Bucket bucket, String aclXMLDoc, Headers headers)
          Write a new ACL for a given bucket
 Response putACL(Bucket bucket, String key, String aclXMLDoc, Headers headers)
          Write a new ACL for a given object
 Response putBucketLogging(Bucket bucket, String loggingXMLDoc, Headers headers)
          Write a new logging xml document for a given bucket
 void shutdown()
          Shuts down any managed or pooled connections.
 String toString()
          Returns a debug string.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

LOCATION_DEFAULT

public static final String LOCATION_DEFAULT
Location default.


LOCATION_EU

public static final String LOCATION_EU
Location in Europe.

See Also:
Constant Field Values

DEFAULT_HOST

public static final String DEFAULT_HOST
Default hostname.

See Also:
Constant Field Values

INSECURE_PORT

public static final int INSECURE_PORT
HTTP port.

See Also:
Constant Field Values

SECURE_PORT

public static final int SECURE_PORT
HTTPS port.

See Also:
Constant Field Values

EXPECT_SIZE

public static final int EXPECT_SIZE
Data larger than 1024 bytes will use expect headers. See: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html 14.20

See Also:
Constant Field Values
Constructor Detail

Connection

public Connection(String awsAccessKeyId,
                  String awsSecretAccessKey)
Constructs a new Connection.


Connection

public Connection(String awsAccessKeyId,
                  String awsSecretAccessKey,
                  boolean isSecure)
Constructs a new Connection.


Connection

public Connection(String awsAccessKeyId,
                  String awsSecretAccessKey,
                  boolean isSecure,
                  String server)
Constructs a new Connection.


Connection

public Connection(String awsAccessKeyId,
                  String awsSecretAccessKey,
                  boolean isSecure,
                  String server,
                  int port)
Constructs a new Connection.


Connection

public Connection(String awsAccessKeyId,
                  String awsSecretAccessKey,
                  boolean isSecure,
                  String server,
                  CallingFormat format)
Constructs a new Connection.


Connection

public Connection(String awsAccessKeyId,
                  String awsSecretAccessKey,
                  boolean isSecure,
                  String server,
                  int port,
                  CallingFormat format)
Create a new interface to interact with S3 with the given credential and connection parameters

Parameters:
awsAccessKeyId - Your user key into AWS
awsSecretAccessKey - The secret string used to generate signatures for authentication.
isSecure - use SSL encryption
server - Which host to connect to. Usually, this will be s3.amazonaws.com
port - Which port to use.
callingFormat - Type of request Regular/Vanity or Pure Vanity domain
Method Detail

create

public Response create(Bucket bucket,
                       String location,
                       Headers headers)
                throws IOException
Creates a new bucket.

Parameters:
bucket - The name of the bucket to create.
location - Desired location ("EU") (or null for default).
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
metadata - A Map of String to List of Strings representing the s3 metadata for this bucket (can be null).
Throws:
IllegalArgumentException - on invalid location
IOException

create

public Response create(Bucket bucket,
                       String location)
                throws IOException
Creates a new bucket with a location.

Throws:
IOException

create

public Response create(Bucket bucket)
                throws IOException
Creates a new bucket.

Throws:
IOException

exists

public boolean exists(Bucket bucket)
               throws IOException
Check if the specified bucket exists (via a HEAD request)

Parameters:
bucket - The name of the bucket to check
Returns:
true if HEAD access returned success
Throws:
IOException
See Also:
head(Bucket, String)

list

public ListResponse list(Bucket bucket,
                         String prefix,
                         String marker,
                         Integer maxKeys,
                         Headers headers)
                  throws IOException
Lists the contents of a bucket.

Parameters:
bucket - The name of the bucket
prefix - All returned keys will start with this string (can be null).
marker - All returned keys will be lexographically greater than this string (can be null).
maxKeys - The maximum number of keys to return (can be null).
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

list

public ListResponse list(Bucket bucket,
                         String prefix,
                         String marker,
                         Integer maxKeys)
                  throws IOException
Lists the contents of a bucket.

Throws:
IOException

list

public ListResponse list(Bucket bucket,
                         Integer maxKeys)
                  throws IOException
Lists the contents of a bucket.

Throws:
IOException

list

public ListResponse list(Bucket bucket)
                  throws IOException
Lists the contents of a bucket.

Throws:
IOException

list

public ListResponse list(Bucket bucket,
                         String prefix)
                  throws IOException
Lists the contents of a bucket by prefix.

Throws:
IOException

list

public ListResponse list(Bucket bucket,
                         String prefix,
                         String marker,
                         Integer maxKeys,
                         String delimiter,
                         Headers headers)
                  throws IOException
Lists the contents of a bucket.

Parameters:
bucket - The name of the bucket to list.
prefix - All returned keys will start with this string (can be null).
marker - All returned keys will be lexographically greater than this string (can be null).
maxKeys - The maximum number of keys to return (can be null).
delimiter - Keys that contain a string between the prefix and the first occurrence of the delimiter will be rolled up into a single element.
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

delete

public Response delete(Bucket bucket,
                       Headers headers)
                throws IOException
Deletes a bucket.

Parameters:
bucket - The name of the bucket to delete.
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

delete

public Response delete(Bucket bucket)
                throws IOException
Deletes a bucket.

Throws:
IOException

put

public Response put(Bucket bucket,
                    String key,
                    S3Object object,
                    Headers headers)
             throws IOException
Writes an object to S3.

Parameters:
bucket - The name of the bucket to which the object will be added.
key - The name of the key to use.
object - An S3Object containing the data to write.
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

put

public Response put(Bucket bucket,
                    String key,
                    S3Object object)
             throws IOException
Writes an object to S3.

Throws:
IOException

get

public GetResponse get(Bucket bucket,
                       String key,
                       Headers headers)
                throws IOException
Reads an object from S3.

Parameters:
bucket - The name of the bucket where the object lives.
key - The name of the key to use.
headers - HTTP headers to pass (can be null).
Throws:
IOException

get

public GetResponse get(Bucket bucket,
                       String key)
                throws IOException
Reads an object from S3.

Throws:
IOException

getStream

public GetStreamResponse getStream(Bucket bucket,
                                   String key,
                                   Headers headers)
                            throws IOException
Reads an object from S3, returning a stream to access the data. This is preferable when dealing with large objects.

Parameters:
bucket - The name of the bucket where the object lives.
key - The name of the key to use.
headers - HTTP headers to pass (can be null).
Throws:
IOException

getStream

public GetStreamResponse getStream(Bucket bucket,
                                   String key)
                            throws IOException
Reads an object from S3, returning a stream to access the data. This is preferable when dealing with large objects.

Throws:
IOException

head

public Response head(Bucket bucket,
                     String key)
              throws IOException
Returns information about an S3 object without loading it. Check Response.isOk() or Response.isNotFound() to see if the object exists.

Throws:
IOException

head

public Response head(Bucket bucket,
                     String key,
                     Headers headers)
              throws IOException
Returns information about an S3 object without loading it.

Throws:
IOException

delete

public Response delete(Bucket bucket,
                       String key,
                       Headers headers)
                throws IOException
Deletes an object from S3.

Parameters:
bucket - The name of the bucket where the object lives.
key - The name of the key to use.
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

delete

public Response delete(Bucket bucket,
                       String key)
                throws IOException
Deletes an object from S3.

Throws:
IOException

getBucketLogging

public GetResponse getBucketLogging(Bucket bucket,
                                    Headers headers)
                             throws IOException
Get the logging xml document for a given bucket

Parameters:
bucket - The name of the bucket
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

putBucketLogging

public Response putBucketLogging(Bucket bucket,
                                 String loggingXMLDoc,
                                 Headers headers)
                          throws IOException
Write a new logging xml document for a given bucket

Parameters:
loggingXMLDoc - The xml representation of the logging configuration as a String
bucket - The name of the bucket
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

getACL

public GetResponse getACL(Bucket bucket,
                          Headers headers)
                   throws IOException
Get the ACL for a given bucket

Parameters:
bucket - The name of the bucket where the object lives.
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

getACL

public GetResponse getACL(Bucket bucket,
                          String key,
                          Headers headers)
                   throws IOException
Get the ACL for a given object (or bucket, if key is null).

Parameters:
bucket - The name of the bucket where the object lives.
key - The name of the key to use.
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

putACL

public Response putACL(Bucket bucket,
                       String aclXMLDoc,
                       Headers headers)
                throws IOException
Write a new ACL for a given bucket

Parameters:
aclXMLDoc - The xml representation of the ACL as a String
bucket - The name of the bucket where the object lives.
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

putACL

public Response putACL(Bucket bucket,
                       String key,
                       String aclXMLDoc,
                       Headers headers)
                throws IOException
Write a new ACL for a given object

Parameters:
aclXMLDoc - The xml representation of the ACL as a String
bucket - The name of the bucket where the object lives.
key - The name of the key to use.
headers - A Map of String to List of Strings representing the http headers to pass (can be null).
Throws:
IOException

getLocation

public LocationResponse getLocation(Bucket bucket)
                             throws IOException
Returns the bucket location.

Throws:
IOException

listAllBuckets

public ListAllBucketsResponse listAllBuckets(Headers headers)
                                      throws IOException
Lists all the buckets created by this account.

Throws:
IOException

listAllBuckets

public ListAllBucketsResponse listAllBuckets()
                                      throws IOException
Lists all the buckets created by this account.

Throws:
IOException

shutdown

public void shutdown()
Shuts down any managed or pooled connections.


toString

public String toString()
Returns a debug string.

Overrides:
toString in class Object


Copyright © 2011. All Rights Reserved.