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.
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.
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)
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.
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.
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
.
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).
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.
