org.sandev.basics.structs
Interface SandCollectionMessage

All Superinterfaces:

SandMessage, SandTransmitMessage, SandVerbMessage

All Known Implementing Classes:

BaseUserCollection, BaseUserEmailCollection, CacheItemSummaryCollection, CacheMemSummaryCollection, CacheStatsCollection, ErrorInfoCollection, FormOutput, ServerDeclarationCollection

public interface SandCollectionMessage
extends SandVerbMessage

A collection of SandStructMessages, as would be returned from a query.

SandMessage

SandInstanceMessage
SandStructMessage
SandPersistMessage
NodeInstance
SandTransmitMessage
SandVerbMessage
SandUpdateMessage
SandQueryMessage
SandCollectionMessage

If a collection isComplete then it contains all of the required instances. For example if the collection is being returned in response to a SandQueryMessage, and all of the matching instances are contained in the collection, then isComplete would be true. If the collection is not complete, then the application must retrieve the additional instances through subsequent queries.

Two factors contribute to the number of elements in a collection being constrained:

1. The DataManager defines a maxQueryReturn parameter and a maxQueryReturnSize parameter which can be accessed by the Persister. This is an upper bound for all queries in the system, and is typically set high enough so that the resulting collection is complete for all except very large numbers of instances (over 1k instances).
2. The maxReturn value of the query message.

The default ordering for collections is by uniqueID. To retrieve the collection for the next dataset page with default ordering, simply set the uniqueIDAfter field to the last uniqueID in the collection. If custom ordering was used, then the application will need to figure out the appropriate subsequent query based on that ordering. More information on dataset pagination can be found in UIGen.html

Field Summary

Fields inherited from interface org.sandev.basics.structs.SandTransmitMessage

APPERROR_NODE_UNAVAILABLE, APPERROR_NODE_UNKNOWN, APPERROR_NODE_UNREACHABLE, STATUS_APPERROR, STATUS_NORMAL, STATUS_SANDERROR, STATUS_SYSERROR

Method Summary

void	addElement(SandInstanceMessage elem) Append an element to this collection.
void	addElements(SandInstanceMessage[] elems) Append an array of elements to this collection.
SandInstanceMessage[]	getElements() Retrieve the elements of this collection regardless of what kind of actual array it is.
SandAttrVal[]	getPagination() Return the pagination values, or null if no pagination was created for the query when it was processed.
java.lang.String	getQueryResult() Return the result of the query function.
int	getTotal() Return the total number of matching records available.
boolean	isComplete() Return true if this collection contains all of the elements matching the source query, false otherwise.
boolean	removeElement(SandInstanceMessage elem) Remove this element from the collection.
void	setComplete(boolean val) Set the complete flag for this collection.
void	setElements(java.lang.Object[] elements) Set the elements of this collection to the given array.
void	setPagination(SandAttrVal[] pages) Set the pagination values.
void	setQueryResult(java.lang.String val) Set the result of the query function.
void	setTotal(int total) Set the total number of matching records available.

Methods inherited from interface org.sandev.basics.structs.SandTransmitMessage

getSandTransmissionCount, getSandTransmissionLocale, getSandTransmitAuthID, getSandTransmitErrorCode, getSandTransmitErrorMessage, getSandTransmitStatus, setSandTransmissionCount, setSandTransmissionLocale, setSandTransmitAuthID, setSandTransmitError, setSandTransmitErrorCode, setSandTransmitErrorMessage, setSandTransmitStatus

Methods inherited from interface org.sandev.basics.structs.SandMessage

getBaseMemoryUse, getCollectionMessage, getQueryMessage, getShortName, getStructMessage, getUpdateMessage, isEquivalent

Method Detail

getElements

SandInstanceMessage[] getElements()

Retrieve the elements of this collection regardless of what kind of actual array it is.

setElements

void setElements(java.lang.Object[] elements)

Set the elements of this collection to the given array. The elements array given as a parameter must match the base element type of the underlying collection.

addElement

void addElement(SandInstanceMessage elem)

Append an element to this collection. The given element will be downcast as needed.

addElements

void addElements(SandInstanceMessage[] elems)

Append an array of elements to this collection. The given array will be downcast to the message instance type.

removeElement

boolean removeElement(SandInstanceMessage elem)

Remove this element from the collection. Return true if the element was found, false otherwise. The given element is downcast as needed.

isComplete

boolean isComplete()

Return true if this collection contains all of the elements matching the source query, false otherwise. If this is false, then there is at least one more page of data available beyond this one.

setComplete

void setComplete(boolean val)

Set the complete flag for this collection. See isComplete method.

getQueryResult

java.lang.String getQueryResult()

Return the result of the query function. If no function was specified, or if the function is not supported, then this field contains "0" (the String zero). When multiple operationFields are specified, then this contains the CSV of the results.

setQueryResult

void setQueryResult(java.lang.String val)

Set the result of the query function.

getTotal

int getTotal()

Return the total number of matching records available. This value is -1 if the total was not calculated when the query was processed. In the case of a complete collection, this number would be the same as getElements().length, but is still set to -1 unless it is explicitely calculated by the query. This is to prevent the appearance of the total being available unless it will also be available the same query over a larger data set.

setTotal

void setTotal(int total)

Set the total number of matching records available.

getPagination

SandAttrVal[] getPagination()

Return the pagination values, or null if no pagination was created for the query when it was processed. Each SandAttrVal in the pagination array consists of a page number as the attr and a uniqueID as the value. The uniqueID can be used as a value for the uniqueIDAfter in the query to get the data for the given page.

setPagination

void setPagination(SandAttrVal[] pages)

Set the pagination values.