net.degreedays.api.data

Class DataSets.Builder

java.lang.Object

net.degreedays.api.data.DataSets.Builder

Enclosing class:

DataSets

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

A builder class for creating immutable DataSets objects e.g. for testing purposes.

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(DataSpecs dataSpecs) Note that this constructor would only usually be called by a ResponseParser, and that's not an interface that you are likely to need to deal with unless you are replacing parts of the framework.

Method Summary

Modifier and Type	Method and Description
DataSets.Builder	add(DataSpec dataSpec, DataSet dataSet) Adds an association between a DataSpec from the request and a DataSet from the response, without dealing directly with the string keys that are used in the XML.
DataSets.Builder	add(java.lang.String key, DataSet dataSet) Adds an association between a string key from a DataSpec in the request and a DataSet from the response.
DataSets.Builder	addFailure(DataSpec dataSpec, Failure failure) Adds an association between a DataSpec from the request and a Failure from the response, without dealing directly with the string keys that are used in the XML.
DataSets.Builder	addFailure(java.lang.String key, Failure failure) Adds an association between a string key from a DataSpec in the request and a Failure from the response.
DataSets	build() Returns a new DataSets object created according to the specification held by this builder.

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

public Builder(DataSpecs dataSpecs)

Note that this constructor would only usually be called by a ResponseParser, and that's not an interface that you are likely to need to deal with unless you are replacing parts of the framework.

Parameters:

dataSpecs - should be the DataSpecs object from the LocationDataRequest that led to this response. You can also pass in null (and it's possible that you might want to if you're writing test cases for your own implementation of ResponseParser), but then you won't be able to use the methods of DataSets that take a DataSpec as an argument.

Method Detail

add

public DataSets.Builder add(java.lang.String key,
                            DataSet dataSet)

Adds an association between a string key from a DataSpec in the request and a DataSet from the response.

Parameters:

key - a string key from the XML response, associated with a particular DataSpec from the original XML request. If this builder was created with a DataSpecs object (which it typically would be), the key must match a key in that DataSpecs object. If you're parsing a genuine XML response the keys will match automatically, but, if you're setting up test objects, you can create a DataSpecs with your own custom keys for full control. Cannot be null, cannot be empty, cannot have more than 60 characters, and cannot contain characters outside of [-_.a-zA-Z0-9].

dataSet - the non-null DataSet associated with key.

Returns:

this, for method chaining.

Throws:

java.lang.NullPointerException - if key or dataSet is null.

java.lang.IllegalArgumentException - if key does not match the required specification, if key is not recognized as one from the original request (assuming this object has access to the DataSpecs to check), or if an item has already been added with key.

addFailure

public DataSets.Builder addFailure(java.lang.String key,
                                   Failure failure)

Adds an association between a string key from a DataSpec in the request and a Failure from the response.

Parameters:

key - a string key from the XML response, associated with a particular DataSpec from the original XML request. If this builder was created with a DataSpecs object (which it typically would be), the key must match a key in that DataSpecs object. If you're parsing a genuine XML response the keys will match automatically, but, if you're setting up test objects, you can create a DataSpecs with your own custom keys for full control. Cannot be null, cannot be empty, cannot have more than 60 characters, and cannot contain characters outside of [-_.a-zA-Z0-9].

failure - the non-null Failure associated with key.

Returns:

this, for method chaining.

Throws:

java.lang.NullPointerException - if key or failure is null.

java.lang.IllegalArgumentException - if key does not match the required specification, if key is not recognized as one from the original request (assuming this object has access to the DataSpecs to check), or if an item has already been added with key.

add

public DataSets.Builder add(DataSpec dataSpec,
                            DataSet dataSet)

Adds an association between a DataSpec from the request and a DataSet from the response, without dealing directly with the string keys that are used in the XML.

Parameters:

dataSpec - the non-null DataSpec object that dataSet was generated to satisfy.

dataSet - the non-null DataSet object that was generated to satisfy dataSpec.

Returns:

this, for method chaining.

Throws:

java.lang.IllegalStateException - if this builder does not have access to the original DataSpecs object.

java.lang.NullPointerException - if dataSpec or dataSet is null.

java.lang.IllegalArgumentException - if dataSpec is not found in the DataSpecs object that this builder holds internally, or if an item corresponding to dataSpec has already been added.

addFailure

public DataSets.Builder addFailure(DataSpec dataSpec,
                                   Failure failure)

Adds an association between a DataSpec from the request and a Failure from the response, without dealing directly with the string keys that are used in the XML.

Parameters:

dataSpec - the non-null DataSpec object that's processing resulted in failure.

failure - the non-null Failure object that resulted when the API tried to generate a DataSet to satisfy dataSpec.

Returns:

this, for method chaining.

Throws:

java.lang.IllegalStateException - if this builder does not have access to the original DataSpecs object.

java.lang.NullPointerException - if dataSpec or failure is null.

java.lang.IllegalArgumentException - if dataSpec is not found in the DataSpecs object that this builder holds internally, or if an item corresponding to dataSpec has already been added.

build

public DataSets build()

Returns a new DataSets object created according to the specification held by this builder.

Throws:

java.lang.IllegalStateException - if this builder was was created with a DataSpecs object (which it usually would be) but does not contain all the DataSet objects or Failure objects that would be expected in a response to a request for that data.