uk.co.visalia.brightpearl.apiclient.common

Class IdSet

java.lang.Object

uk.co.visalia.brightpearl.apiclient.common.IdSet

All Implemented Interfaces:

Serializable, Iterable<Integer>

public final class IdSet
extends Object
implements Iterable<Integer>, Serializable

Many of Brightpearl's GET APIs, and some searches and destructive resources, allow multiple IDs to be fetched or modified in one request by specifying comma or dot separated ID ranges (e.g. "1-3,6-15,20"). This class represents a set of ID ranges and includes a toString() method that generates a valid ID set string for inclusion in URLs.

Internally, an ordered Set implementation is used, so duplicates are automatically filtered and the ID string is generated in ascending order, therefore period (.) separation, which indicates unordered IDs, is not used.

This client does not place any limit on the size of an ID set, however Brightpearl does have limits that are not always documented. Bear in mind that requesting a large number of non-sequential IDs will produce an excessively long URL, and that any large number of IDs may result in the request being rejected by Brightpearl or returning a very large response. Some GET resources have corresponding OPTIONs resources that provide a list of individual requests to make in order to retrieve a large set of entities. Where no OPTIONs resource is available, consider limiting ID sets to fewer than 100 IDs and test whether Brightpearl accepts these requests.

See Also:

http://www.brightpearl.com/developer/latest/concept/id-set.html, Serialized Form

Constructor Summary

Constructors

Constructor and Description
IdSet() Initialise a new empty ID set.
IdSet(Collection<Integer> ids) Initialise an ID set containing a collection of IDs.
IdSet(Integer... ids) Initialise an ID set containing IDs from an array or varargs argument.

Method Summary

Methods

Modifier and Type	Method and Description
IdSet	add(Collection<Integer> ids) Add IDs from a collection.
IdSet	add(Integer... ids) Add IDs from an array or varargs argument.
IdSet	addRange(int from, int to) Add a range of IDs.
static IdSet	all() Initialise an empty ID set.
static IdSet	any() Initialise an empty ID set.
boolean	equals(Object o)
Set<Integer>	getIds() Returns the IDs as a Set.
int	getSize() Returns the number of IDs in the set.
int	hashCode()
static IdSet	ids(Collection<Integer> ids) Initialise an ID set containing a collection of IDs.
static IdSet	ids(Integer... ids) Initialise an ID set containing IDs from an array or varargs argument.
boolean	isEmpty() Returns true if this set contains no IDs.
Iterator<Integer>	iterator() Returns an iterator over the set of IDs.
static IdSet	parse(String str) Parse the string representation of an ID set.
static IdSet	range(int from, int to) Initialise an ID set with a single range of IDs.
Set<IdSet>	split(int batchSize) Splits this IdSet into batches of the given size.
String	toString() Creates a string representation of the ID set for inclusion in URLs.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

IdSet

public IdSet()

Initialise a new empty ID set.

IdSet

public IdSet(Integer... ids)

Initialise an ID set containing IDs from an array or varargs argument. Additional IDs may be added.

Parameters:

ids - Initial set of IDs to add to the ID set.

IdSet

public IdSet(Collection<Integer> ids)

Initialise an ID set containing a collection of IDs. Additional IDs may be added.

Parameters:

ids - Initial set of IDs to add to the ID set.

Method Detail

any

public static IdSet any()

Initialise an empty ID set. The naming of this method reflects its intended use with methods in the accompanying services package, which supports generation of URLs with wildcards or omitted final path components when an empty ID set is used. For example, the URL /order/[ORDER-ID-SET]/goods-note/goods-out/[GOODS-OUT-NOTE-ID-SET] will become /order/*/goods-note/goods-out if any() and all() are passed as arguments to the request builder. Passing null achieves the same result but is less expressive.

all

public static IdSet all()

Initialise an empty ID set. The naming of this method reflects its intended use with methods in the accompanying services package, which supports generation of URLs with wildcards or omitted final path components when an empty ID set is used. For example, the URL /order/[ORDER-ID-SET]/goods-note/goods-out/[GOODS-OUT-NOTE-ID-SET] will become /order/*/goods-note/goods-out if any() and all() are passed as arguments to the request builder. Passing null achieves the same result but is less expressive.

ids

public static IdSet ids(Integer... ids)

Initialise an ID set containing IDs from an array or varargs argument. Additional IDs may be added.

Parameters:

ids - Initial set of IDs to add to the ID set.

Returns:

A new ID set containing the given IDs.

ids

public static IdSet ids(Collection<Integer> ids)

Initialise an ID set containing a collection of IDs. Additional IDs may be added.

Parameters:

ids - Initial set of IDs to add to the ID set.

Returns:

A new ID set containing the given IDs.

range

public static IdSet range(int from,
          int to)

Initialise an ID set with a single range of IDs. Additional IDs may be added.

Parameters:

from - first ID (inclusive)

to - last ID (inclusive)

Returns:

A new ID set for the given range of IDs.

parse

public static IdSet parse(String str)

Parse the string representation of an ID set.

Parameters:

str - A string ID set.

Returns:

add

public IdSet add(Integer... ids)

Add IDs from an array or varargs argument. Duplicates are filtered and ranges automatically calculated.

Parameters:

ids - a set of IDs to add to the ID set.

Returns:

this instance for method chaining.

add

public IdSet add(Collection<Integer> ids)

Add IDs from a collection. Duplicates are filtered and ranges automatically calculated.

Parameters:

ids - a collection of IDs to add to the ID set.

Returns:

this instance for method chaining.

addRange

public IdSet addRange(int from,
             int to)

Add a range of IDs. Duplicate IDs are filtered.

Parameters:

from - first ID of the range (inclusive)

to - last ID of the range (inclusive)

Returns:

this instance for method chaining.

getSize

public int getSize()

Returns the number of IDs in the set.

Returns:

number of IDs in the set.

isEmpty

public boolean isEmpty()

Returns true if this set contains no IDs.

Returns:

true if the set is empty.

getIds

public Set<Integer> getIds()

Returns the IDs as a Set.

Returns:

the set of IDs.

iterator

public Iterator<Integer> iterator()

Returns an iterator over the set of IDs. Uses Set.iterator() internally. Iteration will be in ascending order.

Specified by:

iterator in interface Iterable<Integer>

Returns:

an iterator for the IDs.

split

public Set<IdSet> split(int batchSize)

Splits this IdSet into batches of the given size. All Brightpearl APIs, with the possible exception of some search APIs, have limits on the size of the IdSet they will accept. Some have accompanying OPTIONS APIs to help you fetch large sets. For others, use this method to split the IdSet and send a request for each batch.

If this IdSet is empty, the returned set will be empty.

Parameters:

batchSize - Size of batch.

Returns:

A Set of IDSets.

toString

public String toString()

Creates a string representation of the ID set for inclusion in URLs.

Overrides:

toString in class Object

Returns:

an ID set string.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object