Click or drag to resize

XmlHttpRequestProcessorBuilder Class

Builds XmlHttpRequestProcessor objects: create and configure a Builder object, then call Build to create an XmlHttpRequestProcessor object.
Inheritance Hierarchy
SystemObject
  DegreeDays.Api.ProcessingXmlHttpRequestProcessorBuilder

Namespace:  DegreeDays.Api.Processing
Assembly:  DegreeDays (in DegreeDays.dll) Version: 1.3
Syntax
public sealed class Builder

The XmlHttpRequestProcessorBuilder type exposes the following members.

Constructors
  NameDescription
Public methodXmlHttpRequestProcessorBuilder(AccountKey, SecurityKey)
Initializes a new instance of the XmlHttpRequestProcessorBuilder class
Top
Methods
  NameDescription
Public methodBuild
Public methodGetBytesToEncodedString
Public methodGetDateTimeFormatter
Public methodGetEndpointGetter
Public methodGetHttpRequestDispatcher
Public methodGetRandomFactory
Public methodGetRequestToXml
Public methodGetResponseParser
Public methodGetSigner
Public methodGetStringToBytes
Public methodGetUtcTimestampFactory
Public methodGetXmlRequestWrapper
Public methodSetBytesToEncodedString(IBytesToEncodedString)
Public methodSetDateTimeFormatter(IDateTimeFormatter)
Public methodSetEndpointGetter(IEndpointGetter)
Public methodSetHttpRequestDispatcher(IHttpRequestDispatcher)
Public methodSetRandomFactory(IRandomFactory)
Public methodSetRequestToXml(IRequestToXml)
Public methodSetResponseParser(IResponseParser)
Public methodSetSigner(ISigner)
Public methodSetStringToBytes(IStringToBytes)
Public methodSetUtcTimestampFactory(IUtcTimestampFactory)
Public methodSetXmlRequestWrapper(IXmlRequestWrapper)
Top
Remarks

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 IHttpRequestDispatcher called customHttpRequestDispatcher (which we're assuming you have already created):

XmlHttpRequestProcessor.Builder builder =
        new XmlHttpRequestProcessor.Builder(accountKey, securityKey);
builder.SetHttpRequestDispatcher(customHttpRequestDispatcher);
IRequestProcessor 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:

static class LoggingRequestToXml : IRequestToXml {
    private readonly IRequestToXml wrappedRequestToXml;
    internal LoggingRequestToXml(IRequestToXml requestToXmlToWrap) {
        this.wrappedRequestToXml = requestToXmlToWrap;
    }
    private void Log(string s) {
        // Logging code would need to go here.
    }
    public string GetXml(Request request) {
        string xml = wrappedRequestToXml.GetXml(request);
        Log(xml);
        return xml;
    }
}

XmlHttpRequestProcessor.Builder builder =
        new XmlHttpRequestProcessor.Builder(accountKey, securityKey);
builder.SetRequestToXml(new LoggingRequestToXml(builder.GetRequestToXml()));
IRequestProcessor 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 Process(Request). Here's a step-by-step explanation:

  1. The IRequestToXml component turns the Request into an XML string.
  2. The IEndpointGetter component provides the endpoint URL that the XML request should be sent to.
  3. A RequestSecurityInfo object is created using:
  4. The IXmlRequestWrapper 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 IStringToBytes component turns the complete XML into a byte array.
  6. The ISigner 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 IBytesToEncodedString 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 HttpRequestData 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 IHttpRequestDispatcher component POSTs the parameters from the HttpRequestData to the endpoint URL, and returns a stream containing the XML response.
  10. The IResponseParser component parses the XML response into a Response object - the end result of the processing.
Thread Safety
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.
See Also