net.degreedays.api.processing

Class XmlHttpRequestProcessor.Builder

java.lang.Object

net.degreedays.api.processing.XmlHttpRequestProcessor.Builder

Enclosing class:

XmlHttpRequestProcessor

public static final class XmlHttpRequestProcessor.Builder
extends java.lang.Object

Builds XmlHttpRequestProcessor objects: create and configure a Builder object, then call build() to create an XmlHttpRequestProcessor object.

The request-processing functionality of XmlHttpRequestProcessor is defined by the processing components it uses internally. To create an XmlHttpRequestProcessor with default out-of-the-box functionality, simply create an instance of this builder class and call build(). Or you can customize the the request-processing functionality by setting custom processing components before calling build()...

Providing custom processing components

There are two main ways that you might want to provide custom processing components:

First, you might want to provide a component that you have created or downloaded. For example, here's how to create an XmlHttpRequestProcessor with a custom HttpRequestDispatcher called customHttpRequestDispatcher (which we're assuming you have already created):

 XmlHttpRequestProcessor.Builder builder =
         new XmlHttpRequestProcessor.Builder(accountKey, securityKey);
 builder.setHttpRequestDispatcher(customHttpRequestDispatcher);
 RequestProcessor processor = builder.build();
 

You might also want to wrap, or decorate, the default implementation of a component, adding a little extra functionality. Here's an example that logs the XML of the requests that are sent to the API:

 XmlHttpRequestProcessor.Builder builder =
         new XmlHttpRequestProcessor.Builder(accountKey, securityKey);
 final RequestToXml defaultRequestToXml = builder.getRequestToXml();
 RequestToXml customRequestToXml = new RequestToXml() {
     public String getXml(Request request) {
         String xml = defaultRequestToXml.getXml(request);
         log(xml);
         return xml;
     }
 };
 builder.setRequestToXml(customRequestToXml);
 RequestProcessor processor = builder.build();
 

The processing process

If, for whatever reason, you're providing customized processing components, it's important to understand how these components are used in XmlHttpRequestProcessor.process(net.degreedays.api.Request). Here's a step-by-step explanation:

1. The RequestToXml component turns the Request into an XML string.
2. The EndpointGetter component provides the endpoint URL that the XML request should be sent to.
3. A RequestSecurityInfo object is created using:
   • The endpoint URL.
   • The AccountKey.
   • A request timestamp fetched from the TimestampFactory component and formatted using the DateFormatter component.
   • A random string created by the RandomFactory component.
4. The XmlRequestWrapper component takes the request XML from step 1 and adds in the security info from step 3 to make a complete XML request.
5. The StringToBytes component turns the complete XML into a byte array.
6. The Signer component uses the SecurityKey (a representation of which it holds internally) to create a Signature of the request-XML byte array, so that its integrity can be checked on the API servers. Note that the security key itself is not sent over the wire, only a signature created using that key.
7. The BytesToEncodedString component turns both the XML byte array and the signature byte array into EncodedString objects that each contain an encoded string version of the byte array (that can easily be sent over HTTP) and a code name to indicate the encoding used.
8. An HttpRequest object is created to store the request parameters that should be sent over HTTP to the endpoint URL:
   • The request_encoding parameter holds the encoding() of the string-encoded request XML byte array.
   • The signature_encoding parameter holds the encoding() of the string-encoded signature byte array.
   • The signature_method parameter holds the name of the algorithm used to create the signature.
   • The encoded_request parameter holds the string-encoded request XML.
   • The encoded_signature parameter holds the string-encoded signature.
9. The HttpRequestDispatcher component POSTs the parameters from the HttpRequest to the endpoint URL, and returns a stream containing the XML response.
10. The ResponseParser component parses the XML response into a Response object - the end result of the processing.

Instances of this builder class are designed for single-threaded use only. It's fine to create and use instances in multiple concurrent threads, but, in the absence of external synchronization, the use of each individual builder instance should be restricted to one thread only.

Constructor Summary

Constructors

Constructor and Description
Builder(AccountKey accountKey, SecurityKey securityKey)

Method Summary

Modifier and Type	Method and Description
XmlHttpRequestProcessor	build()
BytesToEncodedString	getBytesToEncodedString()
DateFormatter	getDateFormatter()
EndpointGetter	getEndpointGetter()
HttpRequestDispatcher	getHttpRequestDispatcher()
RandomFactory	getRandomFactory()
RequestToXml	getRequestToXml()
ResponseParser	getResponseParser()
Signer	getSigner()
StringToBytes	getStringToBytes()
TimestampFactory	getTimestampFactory()
XmlRequestWrapper	getXmlRequestWrapper()
XmlHttpRequestProcessor.Builder	setBytesToEncodedString(BytesToEncodedString bytesToEncodedString)
XmlHttpRequestProcessor.Builder	setDateFormatter(DateFormatter dateFormatter)
XmlHttpRequestProcessor.Builder	setEndpointGetter(EndpointGetter endpointGetter)
XmlHttpRequestProcessor.Builder	setHttpRequestDispatcher(HttpRequestDispatcher httpRequestDispatcher)
XmlHttpRequestProcessor.Builder	setRandomFactory(RandomFactory randomFactory)
XmlHttpRequestProcessor.Builder	setRequestToXml(RequestToXml requestToXml)
XmlHttpRequestProcessor.Builder	setResponseParser(ResponseParser responseParser)
XmlHttpRequestProcessor.Builder	setSigner(Signer signer)
XmlHttpRequestProcessor.Builder	setStringToBytes(StringToBytes stringToBytes)
XmlHttpRequestProcessor.Builder	setTimestampFactory(TimestampFactory timestampFactory)
XmlHttpRequestProcessor.Builder	setXmlRequestWrapper(XmlRequestWrapper xmlRequestWrapper)

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

public Builder(AccountKey accountKey,
               SecurityKey securityKey)

Parameters:

accountKey - the non-null public account key associated with the account.

securityKey - the non-null private security key associated with the account (the one that you need to keep secret).

Throws:

java.lang.NullPointerException - if accountKey or securityKey is null.

See Also:

API access keys

Method Detail

getEndpointGetter

public EndpointGetter getEndpointGetter()

getTimestampFactory

public TimestampFactory getTimestampFactory()

getDateFormatter

public DateFormatter getDateFormatter()

getRandomFactory

public RandomFactory getRandomFactory()

getRequestToXml

public RequestToXml getRequestToXml()

getXmlRequestWrapper

public XmlRequestWrapper getXmlRequestWrapper()

getStringToBytes

public StringToBytes getStringToBytes()

getSigner

public Signer getSigner()

getBytesToEncodedString

public BytesToEncodedString getBytesToEncodedString()

getHttpRequestDispatcher

public HttpRequestDispatcher getHttpRequestDispatcher()

getResponseParser

public ResponseParser getResponseParser()

setEndpointGetter

public XmlHttpRequestProcessor.Builder setEndpointGetter(EndpointGetter endpointGetter)

setTimestampFactory

public XmlHttpRequestProcessor.Builder setTimestampFactory(TimestampFactory timestampFactory)

setDateFormatter

public XmlHttpRequestProcessor.Builder setDateFormatter(DateFormatter dateFormatter)

setRandomFactory

public XmlHttpRequestProcessor.Builder setRandomFactory(RandomFactory randomFactory)

setRequestToXml

public XmlHttpRequestProcessor.Builder setRequestToXml(RequestToXml requestToXml)

setXmlRequestWrapper

public XmlHttpRequestProcessor.Builder setXmlRequestWrapper(XmlRequestWrapper xmlRequestWrapper)

setStringToBytes

public XmlHttpRequestProcessor.Builder setStringToBytes(StringToBytes stringToBytes)

setSigner

public XmlHttpRequestProcessor.Builder setSigner(Signer signer)

setBytesToEncodedString

public XmlHttpRequestProcessor.Builder setBytesToEncodedString(BytesToEncodedString bytesToEncodedString)

setHttpRequestDispatcher

public XmlHttpRequestProcessor.Builder setHttpRequestDispatcher(HttpRequestDispatcher httpRequestDispatcher)

setResponseParser

public XmlHttpRequestProcessor.Builder setResponseParser(ResponseParser responseParser)

build

public XmlHttpRequestProcessor build()