uk.co.visalia.brightpearl.apiclient.request

Class ServiceSearchRequestBuilder<T>

java.lang.Object

uk.co.visalia.brightpearl.apiclient.request.ServiceSearchRequestBuilder<T>

Type Parameters:

T - A placeholder for the type expected in the response, avoiding the requirement to cast responses. This is not linked to the Type set on a request so a ClassCastException is possible if the type is set incorrectly.

All Implemented Interfaces:

SearchRequestBuilder<T>

public class ServiceSearchRequestBuilder<T>
extends Object
implements SearchRequestBuilder<T>

A builder used to construct generic ServiceSearchRequest instances that may be used against any search resource. This provides methods for setting filters, pagination and sorting parameters, and column selection on the request. These are all sent as querystring parameters, so be aware that using the withAddedParam(String, String) method can overwrite values set by other methods.

Resource-specific search request builders are included in the accompanying services package; these provide dedicated methods for each column in that search and enums respresenting the columns.

Field Summary

Fields

Modifier and Type	Field and Description
static String	COLUMNS_PARAM
static String	FIRST_RESULT_COLUMN
static String	PAGE_SIZE_COLUMN
static String	SORT_PARAM

Method Summary

Methods

Modifier and Type	Method and Description
ServiceSearchRequest<T>	build() Constructs the immutable request instance for execution.
protected Method	getMethod()
protected Map<String,String>	getParams()
protected String	getPath()
protected Type	getResponseType()
protected String	getRuid()
protected ServiceName	getService()
protected ServiceSearchRequestBuilder<T>	getThis()
static <T> ServiceSearchRequestBuilder<T>	newSearchRequest(ServiceName service, String path, Class<T> responseType) Creates a new search request builder configured with the URL to call and expected response type.
static <T> ServiceSearchRequestBuilder<T>	newSearchRequest(ServiceName service, String path, Type responseType) Creates a new search request builder configured with the URL to call and expected response type.
ServiceSearchRequestBuilder<T>	withAddedColumn(String column) Adds a column to be included in search results.
ServiceSearchRequestBuilder<T>	withAddedFilter(String column, String value) Add an additional column value filter to be applied to the search.
ServiceSearchRequestBuilder<T>	withAddedFilters(Map<String,String> filters) Add additional column value filters to be applied to the search, preserving previous filters set on this builder.
B	withAddedParam(String name, String value) Add an additional unencoded querystring parameter to be added to the request, preserving the existing set but overwriting any param with the same name.
B	withAddedParams(Map<String,String> params) Add additional unencoded querystring parameters to be added to the request, preserving the existing set but overwriting any param with the same names.
ServiceSearchRequestBuilder<T>	withAddedSort(String column, SortDirection direction) Add an additional column sort to be applied to the search.
ServiceSearchRequestBuilder<T>	withColumns(List<String> columns) Sets the columns to be included in search results, replacing any previously set.
ServiceSearchRequestBuilder<T>	withColumns(String... columns) Sets the columns to be included in search results, replacing any previously set.
ServiceSearchRequestBuilder<T>	withFilters(Map<String,String> filters) Set the column value filters to be applied to the search, replacing any previous filters set on this builder.
ServiceSearchRequestBuilder<T>	withFirstResult(Integer firstResult) Sets the first result to return, allowing paging through large result sets.
ServiceSearchRequestBuilder<T>	withPage(Integer pageSize, Integer firstResult) Set paging parameters in one call.
ServiceSearchRequestBuilder<T>	withPageSize(Integer pageSize) Sets the number of results to return per page, allowing paging through large result sets.
B	withParams(Map<String,String> params) Add querystring parameters to the request, replacing any previously set.
B	withPath(String path) Set the path of the Brightpearl resource within the service provided to withService(ServiceName).
B	withResponseType(Type responseType) Set the generic type token representing the expected type of the response element in the JSON response body.
B	withRuid(String ruid) Set a unique identifier for the request.
B	withService(ServiceName service) Returns the name of the Brightpearl service that contains the resource to be called.
ServiceSearchRequestBuilder<T>	withSorts(Map<String,SortDirection> sorts) Set the sort columns and directions, replacing any previously added.

Methods inherited from class java.lang.Object

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

Field Detail

COLUMNS_PARAM

public static final String COLUMNS_PARAM

See Also:

Constant Field Values

PAGE_SIZE_COLUMN

public static final String PAGE_SIZE_COLUMN

See Also:

Constant Field Values

FIRST_RESULT_COLUMN

public static final String FIRST_RESULT_COLUMN

See Also:

Constant Field Values

SORT_PARAM

public static final String SORT_PARAM

See Also:

Constant Field Values

Method Detail

getThis

protected ServiceSearchRequestBuilder<T> getThis()

newSearchRequest

public static <T> ServiceSearchRequestBuilder<T> newSearchRequest(ServiceName service,
                                                  String path,
                                                  Class<T> responseType)

Creates a new search request builder configured with the URL to call and expected response type. Filters, column selection, pagination and sorting parameters can be added if required.

Type Parameters:

T - Placeholder for the response type, used to avoid casting of responses.

Parameters:

service - Brightpearl service that contains the resource.

path - Path to the search resource, for example '/product-search'.

responseType - Type of search result expected. In many cases this will be a different class to that used for resource GET requests; it must have a flat structure with fields corresponding to column names.

Returns:

A search request builder instance.

newSearchRequest

public static <T> ServiceSearchRequestBuilder<T> newSearchRequest(ServiceName service,
                                                  String path,
                                                  Type responseType)

Creates a new search request builder configured with the URL to call and expected response type. Filters, column selection, pagination and sorting parameters can be added if required.

Type Parameters:

T - Placeholder for the response type, used to avoid casting of responses. Responses are parsed into the type defined by responseType, not this type parameter.

Parameters:

service - Brightpearl service that contains the resource.

path - Path to the search resource, for example '/product-search'.

responseType - Type of search result expected. In many cases this will be a different class to that used for resource GET requests; it must have a flat structure with fields corresponding to column names.

Returns:

A search request builder instance.

build

public ServiceSearchRequest<T> build()

Constructs the immutable request instance for execution.

Specified by:

build in interface SearchRequestBuilder<T>

Returns:

an immutable search request.

withAddedFilter

public ServiceSearchRequestBuilder<T> withAddedFilter(String column,
                                             String value)

Add an additional column value filter to be applied to the search. If the column name is the same as an existing filter, the existing filter will be replaced.

Parameters:

column - name of column to filter on.

value - value of filter.

Returns:

builder instance for method chaining.

withAddedFilters

public ServiceSearchRequestBuilder<T> withAddedFilters(Map<String,String> filters)

Add additional column value filters to be applied to the search, preserving previous filters set on this builder. If entries in the supplied map have the same key (column name) as an existing filter, the existing filter will be replaced.

Parameters:

filters - map of filters (column name to filter string) to be applied.

Returns:

builder instance for method chaining.

withFilters

public ServiceSearchRequestBuilder<T> withFilters(Map<String,String> filters)

Set the column value filters to be applied to the search, replacing any previous filters set on this builder.

Parameters:

filters - Map of filters (column name to filter string) to be applied.

Returns:

builder instance for method chaining.

withAddedSort

public ServiceSearchRequestBuilder<T> withAddedSort(String column,
                                           SortDirection direction)

Add an additional column sort to be applied to the search. If more than one sort column is specified, the sorting is applied in order as with an SQL query.

Parameters:

column - Name of the column to sort by.

direction - Direction to sort in.

Returns:

builder instance for method chaining.

withSorts

public ServiceSearchRequestBuilder<T> withSorts(Map<String,SortDirection> sorts)

Set the sort columns and directions, replacing any previously added. Be sure to use a Map implementation that preserves insertion order, for example LinkedHashMap.

Parameters:

sorts - Map of column name to sort direction.

Returns:

builder instance for method chaining.

withPage

public ServiceSearchRequestBuilder<T> withPage(Integer pageSize,
                                      Integer firstResult)

Set paging parameters in one call. Sets the start position and number of results to request, allowing paging through large result sets.

Parameters:

pageSize - Number of results per page.

firstResult - Position of first result to return.

Returns:

builder instance for method chaining.

withPageSize

public ServiceSearchRequestBuilder<T> withPageSize(Integer pageSize)

Sets the number of results to return per page, allowing paging through large result sets.

Parameters:

pageSize - Number of results per page.

Returns:

builder instance for method chaining.

withFirstResult

public ServiceSearchRequestBuilder<T> withFirstResult(Integer firstResult)

Sets the first result to return, allowing paging through large result sets.

Parameters:

firstResult - Position of the first result to return.

Returns:

builder instance for method chaining.

withAddedColumn

public ServiceSearchRequestBuilder<T> withAddedColumn(String column)

Adds a column to be included in search results. Requesting fewer columns may improve response times. When columns are omitted, each individual result is returned with the corresponding fields left null. By default, all available columns are included.

Parameters:

column - Columns to be included in the results.

Returns:

builder instance for method chaining.

withColumns

public ServiceSearchRequestBuilder<T> withColumns(String... columns)

Sets the columns to be included in search results, replacing any previously set. Requesting fewer columns may improve response times. When columns are omitted, each individual result is returned with the corresponding fields left null. By default, all available columns are included.

Parameters:

columns - Columns to be included in the results.

Returns:

builder instance for method chaining.

withColumns

public ServiceSearchRequestBuilder<T> withColumns(List<String> columns)

Sets the columns to be included in search results, replacing any previously set. Requesting fewer columns may improve response times. When columns are omitted, each individual result is returned with the corresponding fields left null. By default, all available columns are included.

Parameters:

columns - Columns to be included in the results.

Returns:

builder instance for method chaining.

withRuid

public B withRuid(String ruid)

Set a unique identifier for the request. All requests are given a unique identifier automatically, for use in logging and as a label for a request contained in a multimessage, and this method may be used to override it with a custom ID.

Note this RUID is applied only to the first request built by this builder; if you call build() more than once, the second and subsequent requests will have randomly generated IDs unless you also call this method between each invocation.

Parameters:

ruid - the custom unique identifier to use.

Returns:

builder instance for method chaining.

withService

public B withService(ServiceName service)

Returns the name of the Brightpearl service that contains the resource to be called.

Parameters:

service - service containing the target resource.

Returns:

builder instance for method chaining.

withPath

public B withPath(String path)

Set the path of the Brightpearl resource within the service provided to withService(ServiceName). For example, for the product GET API, this would be '/product'.

Parameters:

path - the path to be set.

Returns:

builder instance for method chaining.

withResponseType

public B withResponseType(Type responseType)

Set the generic type token representing the expected type of the response element in the JSON response body. This is used by the client to deserialise the response, so if it does not match the expected response an exception may be thrown or an empty object returned. Type is used instead of Class to provide support for deserialising generic types e.g. collections and maps, however this does mean the type is not guaranteed to match the type token T, which is used to avoid casting responses.

Parameters:

responseType - the type to set.

Returns:

builder instance for method chaining.

withAddedParam

public B withAddedParam(String name,
               String value)

Add an additional unencoded querystring parameter to be added to the request, preserving the existing set but overwriting any param with the same name.

Parameters:

name - parameter name.

value - parameter value.

Returns:

builder instance for method chaining.

withAddedParams

public B withAddedParams(Map<String,String> params)

Add additional unencoded querystring parameters to be added to the request, preserving the existing set but overwriting any param with the same names.

Parameters:

params - map of querystring params.

Returns:

builder instance for method chaining.

withParams

public B withParams(Map<String,String> params)

Add querystring parameters to the request, replacing any previously set.

Parameters:

params - map of querystring params.

Returns:

builder instance for method chaining.

getRuid

protected String getRuid()

getService

protected ServiceName getService()

getMethod

protected Method getMethod()

getPath

protected String getPath()

getResponseType

protected Type getResponseType()

getParams

protected Map<String,String> getParams()