thredds.crawlabledataset.s3

Class S3URI

java.lang.Object

thredds.crawlabledataset.s3.S3URI

public class S3URI
extends java.lang.Object

An identifier for objects stored in Amazon S3. Ultimately, the identifier is composed solely of a bucket name and a key, and an object of this class can be constructed with those two items. However, this class also supports URIs rendered in a path-like form: s3://<bucket>/<key>.

Instances of this class are immutable.

Since:

2015/08/24

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	S3_DELIMITER
static java.lang.String	S3_PREFIX
static java.io.File	S3ObjectTempDir

Constructor Summary

Constructors

Constructor and Description
S3URI(java.lang.String uri) Creates a S3URI by extracting the S3 bucket and key names from uri.
S3URI(java.lang.String bucket, java.lang.String key) Creates a S3URI from the specified bucket and key.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object o)
java.lang.String	getBaseName() Returns the base name of the file or directory denoted by this URI.
java.lang.String	getBucket() Returns the bucket.
S3URI	getChild(java.lang.String relativePath) Creates a new URI by resolving the specified path relative to this.
java.lang.String	getKey() Returns the key.
java.lang.String	getKeyWithTrailingDelimiter() Returns the key, adding a trailing delimiter.
S3URI	getParent() Returns the parent URI of this URI.
java.io.File	getTempFile() Gets a temporary file to which the content of the S3Object that this URI points to can be downloaded.
int	hashCode()
java.lang.String	toString() Returns a string representation of the URI in the form s3://<bucket>/<key>.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

S3_PREFIX

public static final java.lang.String S3_PREFIX

See Also:

Constant Field Values

S3_DELIMITER

public static final java.lang.String S3_DELIMITER

See Also:

Constant Field Values

S3ObjectTempDir

public static final java.io.File S3ObjectTempDir

Constructor Detail

S3URI

public S3URI(java.lang.String uri)

Creates a S3URI by extracting the S3 bucket and key names from uri. If the key has a trailing delimiter, it will be removed.

Parameters:

uri - an S3 URI in the form s3://<bucket>/<key>.

Throws:

java.lang.IllegalArgumentException - if uri is not in the expected form or if the bucket or key are invalid.

See Also:

S3URI(String, String)

S3URI

public S3URI(java.lang.String bucket,
             java.lang.String key)
      throws java.lang.IllegalArgumentException

Creates a S3URI from the specified bucket and key. If the key has a trailing delimiter, it will be removed.

Parameters:

bucket - a bucket name. Must be non-null and at least 3 characters.

key - a key. May be null but cannot be the empty string. Also, it may not contain consecutive delimiters.

Throws:

java.lang.IllegalArgumentException - if either argument fails the requirements.

Method Detail

getBucket

public java.lang.String getBucket()

Returns the bucket.

Returns:

the bucket.

getKey

public java.lang.String getKey()

Returns the key. May be null if the URI did not include a key, e.g. "s3://bucket". If not null, any trailing #S3_DELIMITER delimiter the key had when passed to the constructor will have been stripped.

Returns:

the key.

getKeyWithTrailingDelimiter

public java.lang.String getKeyWithTrailingDelimiter()

Returns the key, adding a trailing delimiter. Returns null if the key is null.

Returns:

the key, with a trailing delimiter.

getBaseName

public java.lang.String getBaseName()

Returns the base name of the file or directory denoted by this URI. This is just the last name in the key's name sequence. If the key is null, null is returned.

Returns:

the base name.

getParent

public S3URI getParent()

Returns the parent URI of this URI. The determination is completely text-based, using the delimiter. If the key is null, null is returned. If it is non-null, but doesn't have a logical parent, the returned URI will have a null key (but the same bucket). For example, the parent of s3://my-bucket/my-key (bucket="my-bucket", key="my-key") will be s3://my-bucket (bucket=="my-bucket", key=null).

Returns:

the parent URI of this URI.

getChild

public S3URI getChild(java.lang.String relativePath)
               throws java.lang.IllegalArgumentException

Creates a new URI by resolving the specified path relative to this. If key == null, the key of the returned URI will simply be relativePath.

Parameters:

relativePath - a path relative to this. Must be non-null.

Returns:

the child URI.

Throws:

java.lang.IllegalArgumentException - if the path starts with a delimiter. The path must be relative.

getTempFile

public java.io.File getTempFile()

Gets a temporary file to which the content of the S3Object that this URI points to can be downloaded. The path of the file is ${java.io.tmpdir}/S3Objects/${hashCode()}/${getBaseName()}. This method does not cause the file to be created; we're just returning a suitable path.

Returns:

a temporary file to which the content of the S3Object that this URI points to can be downloaded.

toString

public java.lang.String toString()

Returns a string representation of the URI in the form s3://<bucket>/<key>.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the URI.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object