com.akamai.netstorage

Class NetStorageCMSv35Signer

java.lang.Object

com.akamai.netstorage.NetStorageCMSv35Signer

All Implemented Interfaces:

RequestSigner

public class NetStorageCMSv35Signer
extends Object
implements RequestSigner

The NetStorageCMSv35Signer is responsible for brokering the communication between the software layer and the API. This includes the signing and formatting the request appropriately so that the implementation detail is abstracted from calling libraries. The intended calling library is the NetStorage class, but this layer can be called directly and is offered as a convenience interface for enhanced implementations. TODO: support rebinding on IO communication errors (eg: connection reset) TODO: support async IO TODO: support multiplexing of uploads TODO: optimize and adapt throughput based on connection latency TODO: support HTTP trailers for late SHA256 validation

Author:

colinb@akamai.com (Colin Bendell)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	NetStorageCMSv35Signer.NetStorageType There are multiple types of Net Storage.
static class	NetStorageCMSv35Signer.SignType Currently only 3 signing hash types are supported.

Constructor Summary

Constructors

Constructor and Description
NetStorageCMSv35Signer(String method, URL url, APIEventBean params) Primary invocation for an API communication.
NetStorageCMSv35Signer(String method, URL url, APIEventBean params, InputStream uploadStream, long uploadSize) Primary invocation for an API communication.

Method Summary

Modifier and Type	Method and Description
Map<String,String>	computeHeaders(ClientCredential credential) Assmembles the HTTP Headers necessary for API communication
InputStream	execute(ClientCredential credential)
InputStream	execute(HttpURLConnection request, ClientCredential credential) Opens the connection to Netstorage, assembles the signing headers and uploads any files.
protected String	getActionHeaderValue() Computes the value for the the X-Akamai-ACS-Action: header.
protected String	getAuthDataHeaderValue(ClientCredential credential) Constructs the X-Akamai-ACS-Auth-Data header which contains the signing version, the current time, a random number and the username that is used to sign the data.
protected String	getAuthSignHeaderValue(String action, String authData, ClientCredential credential) Computes the X-Akamai-ACS-Auth-Sign header for a given Action and Data header values.
String	getMethod()
APIEventBean	getParams()
NetStorageCMSv35Signer.SignType	getSignVersion()
long	getUploadSize()
InputStream	getUploadStream()
URL	getUrl()
void	setMethod(String method)
void	setParams(APIEventBean params)
void	setSignVersion(NetStorageCMSv35Signer.SignType signVersion)
void	setUploadSize(long uploadSize)
void	setUploadStream(InputStream uploadStream)
void	setUrl(URL url)
HttpURLConnection	sign(HttpURLConnection request, ClientCredential credential) Signs a request with the client credential.
boolean	validate(HttpURLConnection connection) Attempt to validate the response and detect common causes of errors.

Methods inherited from class java.lang.Object

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

Constructor Detail

NetStorageCMSv35Signer

public NetStorageCMSv35Signer(String method,
                              URL url,
                              APIEventBean params)

Primary invocation for an API communication. This constructor is used for convenience when not uploading content

Parameters:

method - an HTTP verb (GET, POST, PUT)

url - the url to interact with (eg: http://example.akamaihd.net/254462 )

params - the set of bean parameters to be sent in the API request

NetStorageCMSv35Signer

public NetStorageCMSv35Signer(String method,
                              URL url,
                              APIEventBean params,
                              InputStream uploadStream,
                              long uploadSize)

Primary invocation for an API communication. This constructor is used when uploading content is likely

Generally, we don't expose that there are other sign versions available and assume it will be HMac-SHA256. However, this can be overridden in the setSignVersion() method;

Parameters:

method - an HTTP verb (GET, POST, PUT)

url - the url to interact with (eg: http://example.akamaihd.net/254462 )

params - the set of bean parameters to be sent in the API request

uploadStream - the inputStream to read the bytes to upload

uploadSize - if available, the total size of the inputStream. Note, that this could be different than the Size parameter in the action line

Method Detail

getMethod

public String getMethod()

setMethod

public void setMethod(String method)

getUrl

public URL getUrl()

setUrl

public void setUrl(URL url)

getParams

public APIEventBean getParams()

setParams

public void setParams(APIEventBean params)

getUploadStream

public InputStream getUploadStream()

setUploadStream

public void setUploadStream(InputStream uploadStream)

getUploadSize

public long getUploadSize()

setUploadSize

public void setUploadSize(long uploadSize)

getSignVersion

public NetStorageCMSv35Signer.SignType getSignVersion()

setSignVersion

public void setSignVersion(NetStorageCMSv35Signer.SignType signVersion)

getActionHeaderValue

protected String getActionHeaderValue()

Computes the value for the the X-Akamai-ACS-Action: header. This is a url query-string encoded separated list of parameters in the form of name=value&name2=value2. For extensibility purposes, we use generic method to convert the bean fields & parameters into name-value pairs and encode appropriately

Returns:

a url encoded query string of name-value pairs from the APIEventBean

getAuthDataHeaderValue

protected String getAuthDataHeaderValue(ClientCredential credential)

Constructs the X-Akamai-ACS-Auth-Data header which contains the signing version, the current time, a random number and the username that is used to sign the data.

Parameters:

credential - client credentials

Returns:

the data field in a comma separated list

getAuthSignHeaderValue

protected String getAuthSignHeaderValue(String action,
                                        String authData,
                                        ClientCredential credential)

Computes the X-Akamai-ACS-Auth-Sign header for a given Action and Data header values. This results in a base64 encoded representation of the hash as required by the spec. The api server will compute this same hash to validate the request

Parameters:

action - action header values getActionHeaderValue()

authData - data header values getAuthDataHeaderValue(ClientCredential credential)

credential - user credentials

Returns:

a base64 encoded return string

computeHeaders

public Map<String,String> computeHeaders(ClientCredential credential)

Assmembles the HTTP Headers necessary for API communication

Parameters:

credential - user credentials

Returns:

Map of name-value pairs representing HTTP Headers and values.

validate

public boolean validate(HttpURLConnection connection)
                 throws NetStorageException,
                        IOException

Attempt to validate the response and detect common causes of errors. The most common being time drift.

TODO: catch rate limitting errors. Should delay and retry.

Parameters:

connection - an open url connection

Returns:

true if 200 OK response, false otherwise.

Throws:

NetStorageException - wrapped exception if it is a recoverable exception

IOException - shouldn't be called at this point, but could be triggered when interrogating the response

sign

public HttpURLConnection sign(HttpURLConnection request,
                              ClientCredential credential)
                       throws RequestSigningException

Description copied from interface: RequestSigner

Signs a request with the client credential.

Specified by:

sign in interface RequestSigner

Parameters:

request - the request to sign.

credential - the credential used in the signing.

Returns:

open connection

Throws:

RequestSigningException - signing exception

execute

public InputStream execute(HttpURLConnection request,
                           ClientCredential credential)
                    throws RequestSigningException

Opens the connection to Netstorage, assembles the signing headers and uploads any files.

Specified by:

execute in interface RequestSigner

Parameters:

request - an open request

credential - user credentials

Returns:

the InputStream from the response if successful

Throws:

RequestSigningException - if an error occurred during the communication

execute

public InputStream execute(ClientCredential credential)
                    throws RequestSigningException

Specified by:

execute in interface RequestSigner

Throws:

RequestSigningException