com.yosokumo.core
Class YosokumoRequest

java.lang.Object
  com.yosokumo.core.YosokumoRequest

 class YosokumoRequest
extends java.lang.Object

Implements all HTTP requests to the Yosokumo web service. These are the basic methods:

• getFromServer()
• postToServer()
• deleteFromServer()
• putToServer()

These above methods all return false in case of a problem. The caller can then use these methods to determine the cause of the failure:

• getStatusCode()
• getEntity()
• getException()

Field Summary

private java.lang.String	auxHeaderName
private java.lang.String	auxHeaderValue
private java.lang.String	contentType
private Credentials	credentials
private byte[]	entity
private ServiceException	exception
private java.lang.String	hostName
private int	port
private int	statusCode
private boolean	trace

Constructor Summary

YosokumoRequest(Credentials credentials, java.lang.String hostName, int port, java.lang.String contentType)
Initializes a newly created YosokumoRequest object with attributes specified by the input parameters.

Method Summary

private void	appendHeaderValue(org.apache.http.HttpRequest r, java.lang.String headerName, java.lang.StringBuilder s) Append an HTTP header value.
boolean	deleteFromServer(java.lang.String resourceUri) Issue an HTTP DELETE request.
byte[]	getEntity() Return the entity from an HTTP response.
ServiceException	getException() Return the exception from an HTTP process.
boolean	getFromServer(java.lang.String resourceUri) Issue an HTTP GET request.
private boolean	getResponse(org.apache.http.client.methods.HttpRequestBase httpRequest, java.lang.String traceName) Execute an HTTP request and process the response.
int	getStatusCode() Return the status code from an HTTP response.
boolean	getTrace() Return the trace flag.
void	initForOperation() Initialize for an HTTP operation.
private java.lang.String	makeDigest(org.apache.http.client.methods.HttpRequestBase request) Make a digest of an HTTP request.
private boolean	makeRequest(org.apache.http.client.methods.HttpRequestBase httpRequest, byte[] entityToSend, java.lang.String traceName) Make an HTTP request.
private java.lang.String	makeRequestString(org.apache.http.client.methods.HttpRequestBase r) Make a string from an HTTP request.
private java.lang.String	normalizeResourceUri(java.lang.String resourceUri, java.lang.String hostName, int port) Normalize a resource URI.
boolean	postToServer(java.lang.String resourceUri, byte[] entityToPost) Issue an HTTP POST request.
boolean	putToServer(java.lang.String resourceUri, byte[] entityToPut) Issue an HTTP PUT request.
void	setAuxHeader(java.lang.String name, java.lang.String value) Set the auxiliary header.
void	setCredentials(Credentials credentials) Set the credentials.
void	setTrace(boolean traceOn) Set the trace flag.

Methods inherited from class java.lang.Object

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

Field Detail

trace

private boolean trace

credentials

private Credentials credentials

hostName

private java.lang.String hostName

port

private int port

contentType

private java.lang.String contentType

auxHeaderName

private java.lang.String auxHeaderName

auxHeaderValue

private java.lang.String auxHeaderValue

statusCode

private int statusCode

entity

private byte[] entity

exception

private ServiceException exception

Constructor Detail

YosokumoRequest

public YosokumoRequest(Credentials credentials,
                       java.lang.String hostName,
                       int port,
                       java.lang.String contentType)

Initializes a newly created YosokumoRequest object with attributes specified by the input parameters.

Parameters:

credentials - specifies user id and key for authentication.

hostName - is the name of the Yosokumo server.

port - is the port to use to access the Yosokumo service.

contentType - is the content type to use in HTTP communications with the Yosokumo server (e.g., application/yosokumo+protobuf).

Method Detail

initForOperation

public void initForOperation()

Initialize for an HTTP operation. Init various data fields to prepare for execution of a service request.

setCredentials

public void setCredentials(Credentials credentials)

Set the credentials.

Parameters:

credentials - to use in HTTP communications to authorize the user on the Yokosumo server.

setAuxHeader

public void setAuxHeader(java.lang.String name,
                         java.lang.String value)

Set the auxiliary header. Some HTTP requests use an auxiliary header such as "x-yosokumo-full-entries: on" for Get Catalog.

Parameters:

name - is the name of the auxiliary header, e.g., "x-yosokumo-full-entries".

value - is the value of the auxiliary header, e.g., "on".

setTrace

public void setTrace(boolean traceOn)

Set the trace flag. When trace is on, text is written to System.out showing the progress of HTTP requests and reponses.

Parameters:

traceOn - is the value to assign to the trace flag.

getTrace

public boolean getTrace()

Return the trace flag.

Returns:

the current setting of the trace flag.

getStatusCode

public int getStatusCode()

Return the status code from an HTTP response.

Returns:

the status code from an HTTP response.

getEntity

public byte[] getEntity()

Return the entity from an HTTP response.

Returns:

the entity from an HTTP response.

getException

public ServiceException getException()

Return the exception from an HTTP process.

Returns:

null means there is no exception. Otherwise the return value is an exception from an HTTP response.

getFromServer

public boolean getFromServer(java.lang.String resourceUri)

Issue an HTTP GET request.

Parameters:

resourceUri - is the URI of the resource to get.

Returns:

false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() to obtain the data returned from the server.

postToServer

public boolean postToServer(java.lang.String resourceUri,
                            byte[] entityToPost)

Issue an HTTP POST request.

Parameters:

resourceUri - is the URI of the resource to post to.

Returns:

false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() to obtain the data returned from the server.

deleteFromServer

public boolean deleteFromServer(java.lang.String resourceUri)

Issue an HTTP DELETE request.

Parameters:

resourceUri - is the URI of the resource to delete.

Returns:

false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() for more information.

putToServer

public boolean putToServer(java.lang.String resourceUri,
                           byte[] entityToPut)

Issue an HTTP PUT request.

Parameters:

resourceUri - is the URI where to put the resource.

entityToPut - is entity to put to the server.

Returns:

false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() for more information.

makeRequest

private boolean makeRequest(org.apache.http.client.methods.HttpRequestBase httpRequest,
                            byte[] entityToSend,
                            java.lang.String traceName)

Make an HTTP request. This is the workhorse method which does all the work of making an HTTP request and processing the response.

Parameters:

httpRequest - is HttpGet, HttpPut, HttpPost, or HttpDelete.

entityToSend - is an entity to put to the server.

traceName - is the name of the request to be used in trace output.

Returns:

false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() for more information.

getResponse

private boolean getResponse(org.apache.http.client.methods.HttpRequestBase httpRequest,
                            java.lang.String traceName)

Execute an HTTP request and process the response.

Parameters:

httpRequest - is an HTTP request, ready to be executed

traceName - is the name of the request to be used in trace output.

Returns:

false means there was a problem (call getStatusCode(), getEntity(), and getException() for more information). true means the request was successful. Call getStatusCode() and getEntity() for more information.

normalizeResourceUri

private java.lang.String normalizeResourceUri(java.lang.String resourceUri,
                                              java.lang.String hostName,
                                              int port)

Normalize a resource URI. There are several cases:

• The input URI begins with "http://" but the next part of the URI is not the host name: Return the URI as is.
• The input URI begins with "http://"+hostname: Return the URI with ":"+port inserted after the host name.
• The input URI begins with the host name: Return the URI with "http://" prepended.
• None of the above: Return the URI with "http://"+hostName+":"+port prepended.

One reason this method exists is that the HttpClient classes HttpGet, HttpPost, etc., require that the resource URIs passed to their constructors have the "http://"+hostName prefix, despite the fact that the HTTP request lines created by these classes strip the prefix and use only the resource URI. This normalization method allows the programmer to use only the URI, or the fully-prefixed URI, whichever is more convenient.

Parameters:

resourceUri - the input URI to normalize.

hostName - the host name to use.

port - the port to use.

Returns:

a normalized version of the input URI.

makeDigest

private java.lang.String makeDigest(org.apache.http.client.methods.HttpRequestBase request)

Make a digest of an HTTP request.

Parameters:

request - is the HTTP request to digest.

Returns:

null means there was a problem; exception is set. Otherwise the return value is a digest of the input request.

makeRequestString

private java.lang.String makeRequestString(org.apache.http.client.methods.HttpRequestBase r)

Make a string from an HTTP request. This string is used for Yosokumo authentication.

Parameters:

r - is the input HTTP request.

Returns:

is a string containing a number of fields from r.

appendHeaderValue

private void appendHeaderValue(org.apache.http.HttpRequest r,
                               java.lang.String headerName,
                               java.lang.StringBuilder s)

Append an HTTP header value. This is a helper method for makeRequestString.

Parameters:

r - is the input HTTP request.

headerName - is the name of the header whose value is wanted.

s - is the string to append the header value to.