com.strategicgains.restexpress.common.query

Class QueryRange

java.lang.Object

com.strategicgains.restexpress.common.query.QueryRange

public class QueryRange
extends Object

Supports the concept of 'pagination' via request 'Range' header or 'limit' and 'offset' parameters.

Paging is accomplished using the Range and Content-Range HTTP headers or 'limit' and 'offset' query-string parameters.

The client can request a range of results by including the "Range" header with the request. For example, to get the first 25 results:

GET /many_things.json
HTTP/1.1
Host: example.com
Range: items=0-24

To request the same using the 'limit' and 'offset' parameters, limit would be set to 25 with offset being set to 0 (or empty). For example, via the query-string: &limit=25 which is equivalent to &limit=25&offset=0.

When both 'Range' and 'limit' + 'offset are provided, the 'limit' and 'offset' parameters override the 'Range' header. In other words, the query-string parameters override the headers.

The server will respond with a "Content-Range" header that includes the start and end of the range, as well as a total count of all results. For example, the response for the first 25 of 67 total results:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Range: items 0-24/67

Since:

Apr 11, 2011

Author:

toddf

Constructor Summary

Constructors

Constructor and Description
QueryRange()
QueryRange(long offset, int limit)

Method Summary

Methods

Modifier and Type	Method and Description
String	asContentRange(long maxItems) Creates a string in the form "items 0-24/66" using the values from this QueryRange along with the maximum number of items available.
boolean	extendsBeyond(int size, long count)
long	getEnd() Returns an 'end' value calculated from the offset and limit values set on this QueryRange.
int	getLimit() Returns the limit value or zero if no limit is set.
long	getOffset()
long	getStart() getStart() is a synonym for getOffset().
boolean	hasLimit() Answers whether a limit is set on this QueryRange.
boolean	hasOffset()
boolean	isInitialized() Returns true if setLimit(int) and setOffset(long) were both called successfully, or the constructor QueryRange(long, int) was successfully called.
boolean	isInside(int size, long count)
boolean	isOutside(int size, long count)
boolean	isValid() Validates the range.
void	setLimit(int value) Set the query limit, which represents the maximum number of results returned in a query.
void	setLimitViaEnd(long value) Sets the limit of this range by calculating the difference between the already-set offset and the given 'end' value.
void	setOffset(long value)
void	setStart(long value) setStart() is a synonym for setOffset().
boolean	spans(int size, long count)
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

QueryRange

public QueryRange()

QueryRange

public QueryRange(long offset,
          int limit)

Method Detail

getEnd

public long getEnd()

Returns an 'end' value calculated from the offset and limit values set on this QueryRange. If there is no limit, end is calculated to be the 'offset' value.

Returns:

the computed end value of the range, or offset if there is no limit set.

getLimit

public int getLimit()

Returns the limit value or zero if no limit is set.

Returns:

the limit of this QueryRange, or zero.

hasLimit

public boolean hasLimit()

Answers whether a limit is set on this QueryRange.

Returns:

true if a limit is set

setLimit

public void setLimit(int value)

Set the query limit, which represents the maximum number of results returned in a query.

Parameters:

value - an integer >= zero

Throws:

IllegalArgumentException - if the limit is less-than zero

setLimitViaEnd

public void setLimitViaEnd(long value)

Sets the limit of this range by calculating the difference between the already-set offset and the given 'end' value.

Parameters:

value -

Throws:

IllegalArgumentException - if no offset is set or if end is less-than offset, which would cause a negative limit.

getStart

public long getStart()

getStart() is a synonym for getOffset().

setStart

public void setStart(long value)

setStart() is a synonym for setOffset().

Parameters:

value -

getOffset

public long getOffset()

hasOffset

public boolean hasOffset()

setOffset

public void setOffset(long value)

isInitialized

public boolean isInitialized()

Returns true if setLimit(int) and setOffset(long) were both called successfully, or the constructor QueryRange(long, int) was successfully called.

Returns:

true if both a limit and offset are set.

isValid

public boolean isValid()

Validates the range.

Returns:

true if the range is valid

toString

public String toString()

Overrides:

toString in class Object

asContentRange

public String asContentRange(long maxItems)

Creates a string in the form "items 0-24/66" using the values from this QueryRange along with the maximum number of items available. This value is suitable for setting the Content-Range header on the response from Range requests.

No range checking is performed. It is therefore, the caller's responsibility to ensure that maxItems is greater-than the end value.

Parameters:

maxItems - the maximum number of items available.

Returns:

a String of the form "items -/"

isOutside

public boolean isOutside(int size,
                long count)

extendsBeyond

public boolean extendsBeyond(int size,
                    long count)

spans

public boolean spans(int size,
            long count)

isInside

public boolean isInside(int size,
               long count)