com.sage.orion.sdata.servlet
Class QueryPayloadControl

java.lang.Object
  com.sage.orion.sdata.servlet.QueryPayloadControl

public class QueryPayloadControl
extends java.lang.Object

The QueryPayloadControl class represents the Query Payload Control concept in the SData Specification. This is the part of the request that specifies just how much of the data is to be returned in the response.

For the most up-to-date information refer to the SData specification. Currently this information is in Sections 2.11 and 6.5 of the SData 1.1 specification.

Method Summary

IncludeSpecification	getIncludesList() Deprecated. Use saysDescendInto(PayloadControlPath) instead, which caters for the interactions between the select and include parameters
int	getPrecedenceLevel() Returns the precedence level specified in the request, or Integer.MAX_VALUE if none was specified.
java.util.List<java.lang.String>	getSelectCriteria() Deprecated. Use getSelectedProperties(PayloadControlPath) , hasGetAllProperties(PayloadControlPath) and saysDescendInto(PayloadControlPath) directly.
java.util.List<java.lang.String>	getSelectedProperties(PayloadControlPath path) gets the list of properties that are selected for the given resource.
boolean	hasGetAllProperties(PayloadControlPath path) returns whether the response should include all properties of the specified resource.
boolean	hasSelectCriteria() returns true if the control includes an explicit set of select criteria.
boolean	includeDescriptors() gets whether the request specified including descriptors
boolean	saysDescendInto(PayloadControlPath path) checks if the response should descend into the specified resource.

Methods inherited from class java.lang.Object

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

Method Detail

getIncludesList

@Deprecated
public IncludeSpecification getIncludesList()

Deprecated. Use saysDescendInto(PayloadControlPath) instead, which caters for the interactions between the select and include parameters

Gets the list of related resources that are to be included in the response. The result is always non-null.

For further information refer to the description of the include parameter in the Query Payload Control section of the SData specification (currently section 6.5)

Returns:

an IncludeSpecification specifying which related resources are to be included.

getPrecedenceLevel

public int getPrecedenceLevel()

Returns the precedence level specified in the request, or Integer.MAX_VALUE if none was specified.

This controls which properties should be included in the payload based on the precedence values set in the schema.

If this level is set to 0, the payload should be omitted and only the atom data (id and title) should be used. This feature is useful when the consumer only needs basic information for each entry, for example, to fill a combo box. It saves processing on the provider side and bandwidth.

Returns:

the precedence level specified or the largest number if none was specified

getSelectCriteria

@Deprecated
public java.util.List<java.lang.String> getSelectCriteria()

Deprecated. Use getSelectedProperties(PayloadControlPath) , hasGetAllProperties(PayloadControlPath) and saysDescendInto(PayloadControlPath) directly.

Gets the select criteria from the request.

Returns:

the selection criteria for the request or an empty list if there is no select criteria.

getSelectedProperties

public java.util.List<java.lang.String> getSelectedProperties(PayloadControlPath path)

gets the list of properties that are selected for the given resource.

For example if the SData request specified "Select=headers/details/field1" then this would return a list containing "field1" if the resource was "headers/details".

In the list the property may be an atom (e.g. a string) or a related resource (e.g. a sub-resource). If the property is a related resource then this entry indicates that there must be at least the reference in the response; the caller must use saysDescendInto(PayloadControlPath) to see if the caller should go into its details.

Parameters:

path - the resource as a PayloadControlPath. For example "{headers,header}/{details,detail}" represents the "details" subresource of the "headers" subresource of the main resource. A base PayloadControlPath denotes the main resource.

Returns:

an unmodifiable list of properties and subresources within the resource.

Throws:

java.lang.IllegalStateException - if hasSelectCriteria returns false or hasGetAllProperties(PayloadControlPath) returns true for this path

hasGetAllProperties

public boolean hasGetAllProperties(PayloadControlPath path)

returns whether the response should include all properties of the specified resource.

For example if the SData request specified "Select=headers/details/*" then this would return true for the argument "headers/details", because of the '*'.

If there was no Select parameter specified (hasSelectCriteria returns false) then for consistency this will return true if no precedence level was specified and will return false if there was a precedence level specified.

Parameters:

path - the resource as a PayloadControlPath. For example "{headers,header}/{details,detail}" represents the "details" subresource of the "headers" subresource of the main resource. A base PayloadControlPath denotes the main resource.

Returns:

true if the response should include all properties of this resource

hasSelectCriteria

public boolean hasSelectCriteria()

returns true if the control includes an explicit set of select criteria.

Returns:

true if the control has select criteria.

saysDescendInto

public boolean saysDescendInto(PayloadControlPath path)

checks if the response should descend into the specified resource.

If there is a select parameter (hasSelectCriteria returns true) then this is true if the select parameter specifies some properties at or below this level.

If there is no select parameter the result is based upon any include parameter.

It is also true if the include specification includes some subresource of the specified one (since the caller would need to drill down into the specified resource to get to the one to be included, even if most of the properties of the specified resource will not be returned).

Parameters:

path - the resource as a PayloadControlPath. For example "{headers,header}/{details,detail}/" represents the "details" subresource of the "headers" subresource of the main resource. A base PayloadControlPath denotes the main resource.

Returns:

true if the response should include some sort of details of the given resource, requiring descending into it to investigate it.

includeDescriptors

public boolean includeDescriptors()

gets whether the request specified including descriptors

Returns:

true if the request specified including descriptors