org.jets3t.service.utils

Class ServiceUtils

java.lang.Object

org.jets3t.service.utils.ServiceUtils

public class ServiceUtils
extends java.lang.Object

General utility methods used throughout the jets3t project.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	HASH_SHA256
protected static java.text.SimpleDateFormat	iso8601DateParser
protected static java.text.SimpleDateFormat	iso8601DateParser_Walrus
protected static java.text.SimpleDateFormat	rfc822DateParser

Constructor Summary

Constructors

Constructor and Description
ServiceUtils()

Method Summary

Modifier and Type	Method and Description
static S3Object	buildObjectFromUrl(java.lang.String host, java.lang.String urlPath, java.lang.String s3Endpoint) Builds an object based on the bucket name and object key information available in the components of a URL.
static java.util.Map<java.lang.String,java.lang.Object>	cleanRestMetadataMap(java.util.Map<java.lang.String,java.lang.Object> metadata, java.lang.String serviceMetadataPrefix, java.lang.String userMetadataPrefix) From a map of metadata returned from a REST GET or HEAD request, returns a map of metadata with the HTTP-connection-specific metadata items removed.
static byte[]	computeMD5Hash(byte[] data) Computes the MD5 hash of the given data and returns it as a hex string.
static byte[]	computeMD5Hash(java.io.InputStream is) Computes the MD5 hash of the data in the given input stream and returns it as a hex string.
static long	countBytesInObjects(S3Object[] objects) Counts the total number of bytes in a set of S3Objects by summing the content length of each.
static java.lang.String	findBucketNameInHostname(java.lang.String host, java.lang.String s3Endpoint) Identifies the name of a bucket from a given host name, if available.
static java.lang.String	findBucketNameInHostOrPath(java.net.URI uri, java.lang.String s3Endpoint) Find the name of a bucket referred to by a HTTP request's Host or Path URI components.
static java.lang.String	formatIso8601Date(java.util.Date date)
static java.lang.String	formatRfc822Date(java.util.Date date)
static byte[]	fromBase64(java.lang.String b64Data) Converts a Base64-encoded string to the original byte data.
static byte[]	fromHex(java.lang.String hexData) Converts a Hex-encoded data string to the original byte data.
static java.lang.String	generateS3HostnameForBucket(java.lang.String bucketName, boolean isDnsBucketNamingDisabled, java.lang.String s3Endpoint)
static java.lang.String	getUserAgentDescription(java.lang.String applicationDescription) Returns a user agent string describing the jets3t library, and optionally the application using it, to server-side services.
static byte[]	hash(byte[] data, java.lang.String cryptoHash)
static byte[]	hash(java.io.InputStream dataIS, java.lang.String cryptoHash, boolean resetInsteadOfClose)
static byte[]	hash(java.lang.String data, java.lang.String cryptoHash)
static byte[]	hashSHA256(byte[] data)
static byte[]	hashSHA256(java.io.InputStream dataIS)
static byte[]	hashSHA256(java.io.InputStream dataIS, boolean resetInsteadOfClose)
static byte[]	hmac(byte[] key, byte[] data, java.lang.String cryptoAlgorithm)
static byte[]	hmacSHA256(byte[] key, byte[] data)
static byte[]	hmacSHA256(java.lang.String key, java.lang.String data) Return lowercase hex-encoded HMAC message digest of given data using the given key, using a crypto hash like "SHA256".
static boolean	isBucketNameValidDNSName(java.lang.String bucketName) Returns true if the given bucket name can be used as a component of a valid DNS name.
static boolean	isEtagAlsoAnMD5Hash(java.lang.String etag) Guess whether the given ETag value is also an MD5 hash of an underlying object in a storage service, as opposed to being some other kind of opaque hash.
static java.lang.String	join(int[] ints, java.lang.String delimiter) Joins a list of ints into a delimiter-separated string.
static java.lang.String	join(java.util.List<?> items, java.lang.String delimiter) Joins a list of items into a delimiter-separated string.
static java.lang.String	join(java.lang.Object[] items, java.lang.String delimiter) Joins a list of items into a delimiter-separated string.
static org.xml.sax.XMLReader	loadXMLReader() Find a SAX XMLReader by hook or by crook, with work-arounds for non-standard platforms.
static java.util.Date	parseIso8601Date(java.lang.String dateString)
static java.util.Date	parseRfc822Date(java.lang.String dateString)
static java.lang.String	readInputStreamLineToString(java.io.InputStream is, java.lang.String encoding) Reads from an input stream until a newline character or the end of the stream is reached.
static byte[]	readInputStreamToBytes(java.io.InputStream is) Reads binary data from an input stream and returns it as a byte array.
static java.lang.String	readInputStreamToString(java.io.InputStream is, java.lang.String encoding) Reads text data from an input stream and returns it as a String.
static java.lang.String	signWithHmacSha1(java.lang.String awsSecretKey, java.lang.String canonicalString) Calculate the HMAC/SHA1 on a string.
static java.lang.String[]	splitIgnoreEmpty(java.lang.String str, java.lang.String regexp)
static byte[]	stringToBytes(java.lang.String str)
static java.lang.String	toBase64(byte[] data) Converts byte data to a Base64-encoded string.
static java.lang.String	toHex(byte[] data) Converts byte data to a Hex-encoded string.
static java.lang.String	wrapString(java.lang.String p_Input, java.lang.String p_Prefix, int p_Len) Take the input we're given and wrap at the user-defined intervals
static java.lang.String	wrapString(java.lang.String p_Input, java.lang.String p_Prefix, int p_Len, java.lang.String p_Delims) Take the input we're given and wrap at the user-defined intervals

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

HASH_SHA256

public static java.lang.String HASH_SHA256

iso8601DateParser

protected static final java.text.SimpleDateFormat iso8601DateParser

iso8601DateParser_Walrus

protected static final java.text.SimpleDateFormat iso8601DateParser_Walrus

rfc822DateParser

protected static final java.text.SimpleDateFormat rfc822DateParser

Constructor Detail

ServiceUtils

public ServiceUtils()

Method Detail

parseIso8601Date

public static java.util.Date parseIso8601Date(java.lang.String dateString)
                                       throws java.text.ParseException

Throws:

java.text.ParseException

formatIso8601Date

public static java.lang.String formatIso8601Date(java.util.Date date)

parseRfc822Date

public static java.util.Date parseRfc822Date(java.lang.String dateString)
                                      throws java.text.ParseException

Throws:

java.text.ParseException

formatRfc822Date

public static java.lang.String formatRfc822Date(java.util.Date date)

signWithHmacSha1

public static java.lang.String signWithHmacSha1(java.lang.String awsSecretKey,
                                                java.lang.String canonicalString)

Calculate the HMAC/SHA1 on a string.

Parameters:

awsSecretKey - AWS secret key.

canonicalString - canonical string representing the request to sign.

Returns:

Signature

stringToBytes

public static byte[] stringToBytes(java.lang.String str)

Parameters:

str -

Returns:

String as bytes using default JetS3t encoding (UTF-8)

hash

public static byte[] hash(byte[] data,
                          java.lang.String cryptoHash)

Parameters:

data -

cryptoHash -

Returns:

lowercase hex-encoded hash value.

hash

public static byte[] hash(java.io.InputStream dataIS,
                          java.lang.String cryptoHash,
                          boolean resetInsteadOfClose)
                   throws java.io.IOException

Parameters:

dataIS -

cryptoHash -

resetInsteadOfClose - if true, input stream is reset instead of closed after hash is generated.

Returns:

lowercase hex-encoded hash value.

Throws:

java.io.IOException

hash

public static byte[] hash(java.lang.String data,
                          java.lang.String cryptoHash)

Parameters:

data -

cryptoHash -

Returns:

lowercase hex-encoded hash value.

hashSHA256

public static byte[] hashSHA256(byte[] data)

hashSHA256

public static byte[] hashSHA256(java.io.InputStream dataIS,
                                boolean resetInsteadOfClose)
                         throws java.io.IOException

Throws:

java.io.IOException

hashSHA256

public static byte[] hashSHA256(java.io.InputStream dataIS)
                         throws java.io.IOException

Throws:

java.io.IOException

hmac

public static byte[] hmac(byte[] key,
                          byte[] data,
                          java.lang.String cryptoAlgorithm)

Parameters:

key - key for HMAC

data - data to be HMAC'd

cryptoAlgorithm - cryptographic algorithm to use for HMAC, e.g. "SHA-256"

Returns:

HMAC hash value with given crypto hashing algorithm.

hmacSHA256

public static byte[] hmacSHA256(java.lang.String key,
                                java.lang.String data)

Return lowercase hex-encoded HMAC message digest of given data using the given key, using a crypto hash like "SHA256".

Parameters:

key -

data -

Returns:

HMAC SHA256 hash value.

hmacSHA256

public static byte[] hmacSHA256(byte[] key,
                                byte[] data)

Parameters:

key -

data -

Returns:

HMAC SHA256 hash value.

readInputStreamToString

public static java.lang.String readInputStreamToString(java.io.InputStream is,
                                                       java.lang.String encoding)
                                                throws java.io.IOException

Reads text data from an input stream and returns it as a String.

Parameters:

is - input stream from which text data is read.

encoding - the character encoding of the textual data in the input stream. If this parameter is null, the default system encoding will be used.

Returns:

text data read from the input stream.

Throws:

java.io.IOException

readInputStreamLineToString

public static java.lang.String readInputStreamLineToString(java.io.InputStream is,
                                                           java.lang.String encoding)
                                                    throws java.io.IOException

Reads from an input stream until a newline character or the end of the stream is reached.

Parameters:

is -

Returns:

text data read from the input stream, not including the newline character.

Throws:

java.io.IOException

readInputStreamToBytes

public static byte[] readInputStreamToBytes(java.io.InputStream is)
                                     throws java.io.IOException

Reads binary data from an input stream and returns it as a byte array.

Parameters:

is - input stream from which data is read.

Returns:

byte array containing data read from the input stream.

Throws:

java.io.IOException

countBytesInObjects

public static long countBytesInObjects(S3Object[] objects)

Counts the total number of bytes in a set of S3Objects by summing the content length of each.

Parameters:

objects -

Returns:

total number of bytes in all S3Objects.

cleanRestMetadataMap

public static java.util.Map<java.lang.String,java.lang.Object> cleanRestMetadataMap(java.util.Map<java.lang.String,java.lang.Object> metadata,
                                                                                    java.lang.String serviceMetadataPrefix,
                                                                                    java.lang.String userMetadataPrefix)

From a map of metadata returned from a REST GET or HEAD request, returns a map of metadata with the HTTP-connection-specific metadata items removed.

Parameters:

metadata - metadata map to be cleaned

serviceMetadataPrefix - prefix denoting service-specific "header" HTTP header values (case insensitive)

userMetadataPrefix - prefix denoting service-specific "user metadata" HTTP header values (case insensitive)

Returns:

metadata map with HTTP-connection-specific items removed.

toHex

public static java.lang.String toHex(byte[] data)

Converts byte data to a Hex-encoded string.

Parameters:

data - data to hex encode.

Returns:

hex-encoded string.

fromHex

public static byte[] fromHex(java.lang.String hexData)

Converts a Hex-encoded data string to the original byte data.

Parameters:

hexData - hex-encoded data to decode.

Returns:

decoded data from the hex string.

toBase64

public static java.lang.String toBase64(byte[] data)

Converts byte data to a Base64-encoded string.

Parameters:

data - data to Base64 encode.

Returns:

encoded Base64 string.

join

public static java.lang.String join(java.util.List<?> items,
                                    java.lang.String delimiter)

Joins a list of items into a delimiter-separated string. Each item is converted to a string value with the toString() method before being added to the final delimited list.

Parameters:

items - the items to include in a delimited string

delimiter - the delimiter character or string to insert between each item in the list

Returns:

a delimited string

join

public static java.lang.String join(java.lang.Object[] items,
                                    java.lang.String delimiter)

Joins a list of items into a delimiter-separated string. Each item is converted to a string value with the toString() method before being added to the final delimited list.

Parameters:

items - the items to include in a delimited string

delimiter - the delimiter character or string to insert between each item in the list

Returns:

a delimited string

join

public static java.lang.String join(int[] ints,
                                    java.lang.String delimiter)

Joins a list of ints into a delimiter-separated string.

Parameters:

ints - the ints to include in a delimited string

delimiter - the delimiter character or string to insert between each item in the list

Returns:

a delimited string

splitIgnoreEmpty

public static java.lang.String[] splitIgnoreEmpty(java.lang.String str,
                                                  java.lang.String regexp)

Parameters:

str -

regexp -

Returns:

string split with regexp using String.split(String) with empty strings removed.

fromBase64

public static byte[] fromBase64(java.lang.String b64Data)

Converts a Base64-encoded string to the original byte data.

Parameters:

b64Data - a Base64-encoded string to decode.

Returns:

bytes decoded from a Base64 string.

computeMD5Hash

public static byte[] computeMD5Hash(java.io.InputStream is)
                             throws java.security.NoSuchAlgorithmException,
                                    java.io.IOException

Computes the MD5 hash of the data in the given input stream and returns it as a hex string. The provided input stream is consumed and closed by this method.

Parameters:

is -

Returns:

MD5 hash

Throws:

java.security.NoSuchAlgorithmException

java.io.IOException

computeMD5Hash

public static byte[] computeMD5Hash(byte[] data)
                             throws java.security.NoSuchAlgorithmException,
                                    java.io.IOException

Computes the MD5 hash of the given data and returns it as a hex string.

Parameters:

data -

Returns:

MD5 hash.

Throws:

java.security.NoSuchAlgorithmException

java.io.IOException

isEtagAlsoAnMD5Hash

public static boolean isEtagAlsoAnMD5Hash(java.lang.String etag)

Guess whether the given ETag value is also an MD5 hash of an underlying object in a storage service, as opposed to being some other kind of opaque hash.

This test was made necessary by Amazon S3's multipart upload feature, where the ETag value returned after a re-assembled multipart upload is completed is no longer the same as an MD5 hash of the assembled data.

An ETag is considered also an MD5 when:

• The length is exactly 16 characters (excluding surrounding quote characters)
• All characters in the string are hexadecimal values, i.e. [0-9a-f] when lowercased

These rules are drawn from the post by Carl@AWS on Nov 11, 2010 10:40 AM here: https://forums.aws.amazon.com/thread.jspa?messageID=222158&tstart=0

Returns:

true if the ETag value can be assumed to also be an MD5 hash.

findBucketNameInHostname

public static java.lang.String findBucketNameInHostname(java.lang.String host,
                                                        java.lang.String s3Endpoint)

Identifies the name of a bucket from a given host name, if available. Returns null if the bucket name cannot be identified, as might happen when a bucket name is represented by the path component of a URL instead of the host name component.

Parameters:

host - the host name component of a URL that may include the bucket name, if an alternative host name is in use.

Returns:

The S3 bucket name represented by the DNS host name, or null if none.

findBucketNameInHostOrPath

public static java.lang.String findBucketNameInHostOrPath(java.net.URI uri,
                                                          java.lang.String s3Endpoint)

Find the name of a bucket referred to by a HTTP request's Host or Path URI components. Returns null if the bucket name cannot be found, which is a legitimate outcome for requests that are not directed at a bucket (e.g. service root-level requests). "http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region"

Parameters:

uri - URI containing the request's Host domain name target (via URI.getHost()) and Path component (via URI.getPath())

s3Endpoint - Host name of default S3 endpoint, generally "s3.amazonaws.com" but may differ when using alternative services such as Eucalyptus Walrus etc.

Returns:

the bucket name target of the request's Host/Path, or null if none.

buildObjectFromUrl

public static S3Object buildObjectFromUrl(java.lang.String host,
                                          java.lang.String urlPath,
                                          java.lang.String s3Endpoint)
                                   throws java.io.UnsupportedEncodingException

Builds an object based on the bucket name and object key information available in the components of a URL.

Parameters:

host - the host name component of a URL that may include the bucket name, if an alternative host name is in use.

urlPath - the path of a URL that references an S3 object, and which may or may not include the bucket name.

Returns:

the object referred to by the URL components.

Throws:

java.io.UnsupportedEncodingException

isBucketNameValidDNSName

public static boolean isBucketNameValidDNSName(java.lang.String bucketName)

Returns true if the given bucket name can be used as a component of a valid DNS name. If so, the bucket can be accessed using requests with the bucket name as part of an S3 sub-domain. If not, the old-style bucket reference URLs must be used, in which case the bucket name must be the first component of the resource path.

Parameters:

bucketName - the name of the bucket to test for DNS compatibility.

generateS3HostnameForBucket

public static java.lang.String generateS3HostnameForBucket(java.lang.String bucketName,
                                                           boolean isDnsBucketNamingDisabled,
                                                           java.lang.String s3Endpoint)

getUserAgentDescription

public static java.lang.String getUserAgentDescription(java.lang.String applicationDescription)

Returns a user agent string describing the jets3t library, and optionally the application using it, to server-side services.

Parameters:

applicationDescription - a description of the application using the jets3t toolkit, included at the end of the user agent string. This value may be null.

Returns:

a string built with the following components (some elements may not be available): JetS3t/Constants.JETS3T_VERSION (os.name/os.version; os.arch; user.region; user.region; user.language) applicationDescription

loadXMLReader

public static org.xml.sax.XMLReader loadXMLReader()
                                           throws ServiceException

Find a SAX XMLReader by hook or by crook, with work-arounds for non-standard platforms.

Returns:

an initialized XML SAX reader

Throws:

ServiceException

wrapString

public static java.lang.String wrapString(java.lang.String p_Input,
                                          java.lang.String p_Prefix,
                                          int p_Len)

Take the input we're given and wrap at the user-defined intervals

Parameters:

p_Input - The string to be modified by the line wrap.

p_Prefix - a prefix to prebend to the output string

p_Len - The maximum number of characters per line

Returns:

The new string that contains the extra new-line escapes.

wrapString

public static java.lang.String wrapString(java.lang.String p_Input,
                                          java.lang.String p_Prefix,
                                          int p_Len,
                                          java.lang.String p_Delims)

Take the input we're given and wrap at the user-defined intervals

Parameters:

p_Input - The string to be modified by the line wrap.

p_Prefix - a prefix to prebend to the output string

p_Len - The maximum number of characters per line

p_Delims - are the characters on which wrapping is allowed

Returns:

The new string that contains the extra new-line escapes.