SandQueryMessage

Query messages are used to retrieve matching data (typically via synchronous call) from other nodes. Most queries are over persistent data and eventually access the DataManager. For general information on querying persistent data, see Persist.html, For general information on form-based queries and processing, see UIGen.html.

A query consists of match information, result ordering information, and limits on the number of returned matching instances. For more information ordering and data pagination, see the SandCollectionMessage. The match information in a query is an array of match expresssions. These are the same expressions used for filtering incoming messages, but they are most commonly associated with queries and so they are documented here.

Match Expressions:

A SandAttrVal, where the attr is the name of the field within the object being referenced, and the val is a description of acceptable field values. The val can be a single value, or a compound expression. An example compound expression for an "age" field might be:


     >= 18 AND <= 65

which would match all age values between 18 and 65 inclusive. The following operators are always valid for a match expression:

<, <=, >, >=, =, !=, AND, OR, NOT

Parentheses and wildcard/regexp String value matching are both generally supported, but may not be available in all contexts. Match expression tokens are whitespace delimited by convention, to allow for simple text manipulation of expressions at runtime.

The operators AND, OR, NOT are case insensitive, but by convention upper case is encouraged to help with heuristic parsing of sloppy input and general readability. String value matching is generally assumed to be case insensitive, but this is not an absolute requirement and may be ignored (like for passwords and such). In general match expression processing follows SQL "where" clause processing rules.

A contained struct, or reference, may be dereferenced within a match expression using standard dot notation. So for example if BarStruct contains a protected int age, and FooStruct contains a reference to a BarStruct mybar, then mybar.age is a valid value for the attr part of a match expression.

Dot reference semantics extend to aggregate arrays. So if BarStruct in turn contained an array of BazStruct references mybazzes, and BazStruct contained a protected int frequency, then mybar.mybazzes.frequency would be a valid attr specification. If we were looking for a frequency >= 5, then the match expression can be thought of as: "find me all the Foo messages containing a Bar message that contains one or more Baz messages with a frequency >= 5".

A Query is not a general purpose database access mechanism, although there is potential overlap with alternative data access methods. If your application requires additional information outside of persistent message instances, you might consider:

Defining a database view.
Leveraging stored procedures as read-only data.
Generating parameterized database reports using COTS, and retrieving their data for processing, or posting them on a periodic basis.
Defining a SQLQueryStruct for holding arbitrary SQL statements, and a RecordSetStruct for holding arbitrary SQL results. Then defining a RawQueryNodeDecl for processing these messages.
Contacting Structs And Nodes Development Services

Field Summary
`static java.lang.String`	`APPERROR_FUNCTION_NOT_SUPPORTED` Error message used when the requested function is not supported by the query recipient.
`static java.lang.String`	`APPERROR_INVALID_OPERATION_FIELDS` Error message when the fields specified for a function are invalid.
`static java.lang.String`	`APPERROR_NO_OPERANDS_SPECIFIED` Error message when a function is specified without operands
`static java.lang.String`	`EXPRESSION_OPERATOR` Special attribute signifying an extended expression operator.
`static int`	`FUNCTION_AVG` Specifies that this query should return the average value of each of the fields specified in the operationFields.
`static int`	`FUNCTION_COUNT` Specifies that this query should return the total count of instances matching the query criteria.
`static int`	`FUNCTION_DATA` Specifies that this query should return the instances matching the query criteria.
`static int`	`FUNCTION_MAX` Specifies that this query should return the maximum value of each of the fields specified in the operationFields.
`static int`	`FUNCTION_MIN` Specifies that this query should return the minimum value of each of the fields specified in the operationFields.
`static int`	`FUNCTION_SUM` Specified that this query should return the total value of each of the fields specified in the operationFields.
`static int`	`FUNCTION_UIDS` Process the query as data, but return the uniqueID values for all matching instances without instantiating them.
`static int`	`ORDER_ASCENDING` Specifies that the query ordering should be ascending.
`static int`	`ORDER_DESCENDING` Specifies that the query ordering should be descending.
`static int`	`ORDER_UNSPECIFIED` Specifies that the query ordering is unspecified and should use whatever the default ordering is.
`static int`	`PAGE_ALL` In addition to processing the query, calculate the total and provide a data paging summary with page numbers and uniqueID values.
`static int`	`PAGE_NONE` Do not generate any paging info.
`static int`	`PAGE_TOTALONLY` In addition to processing the query, compute the total number of matching records and return that value.

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`	`addMatchInfo(SandAttrVal av)` Append a new match expressions to the match information.
`SandQueryMessage`	`cloneQuery()` Return a deep copy of this query message.
`int`	`getFunction()` One of the FUNCTION values describing what kind of query processing is being requested.
`java.lang.String`	`getFunctionPrintValue()` Return a print value representation of the query type value.
`SandAttrVal[]`	`getMatchInfo()` Zero or more match expressions further constraining this query.
`int`	`getMaxReturn()` Get the maximum number of matching items to return in a resulting collection message.
`java.lang.String`	`getOperationFields()` Returns the field name or CSV of field names which the specified function applies to.
`java.lang.String`	`getOrderBy()` Get the comma separated field names to order the resulting collection with.
`int`	`getOrderSense()` Return the order sense for this query.
`int`	`getPagination()` Return the level of data pagination information to be returned with the query.
`long`	`getUniqueIDAfter()` Support for automatic data pagination.
`boolean`	`matches(java.lang.Object msg)` Return true if the given message matches this query.
`void`	`normalize()` Fix any spacing, quoting or other issues in our match expression fields to whatever extent possible.
`void`	`setFunction(int functionType)` Set the FUNCTION value describing what kind of query processing is being requested.
`void`	`setMatchInfo(SandAttrVal[] matchExpression)` Set the match expressions for this query.
`void`	`setMaxReturn(int max)` Set the maximum number of matching items to return in a resulting collection message.
`void`	`setOperationFields(java.lang.String fieldNamesCSV)` Set the field name or CSV of field names which the speicifed function should be applied to.
`void`	`setOrderBy(java.lang.String fieldsCSV)` Set the result collection ordering.
`void`	`setOrderSense(int sense)` Set the order sense.
`void`	`setPagination(int level)` Set the level of data pagination information to be created when processing the query.
`void`	`setUniqueIDAfter(long id)` Support for automatic data pagination.
`java.lang.String`	`undecimalize(java.lang.String attr, java.lang.String val)` Given an attr, return the undecimalized form of the given val.

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`

Field Detail

ORDER_UNSPECIFIED

static final int ORDER_UNSPECIFIED

Specifies that the query ordering is unspecified and should use whatever the default ordering is. Typically this is equivalent to ASCENDING order, unless ordering is being specified explicitely.

See Also:: Constant Field Values

ORDER_ASCENDING

static final int ORDER_ASCENDING

Specifies that the query ordering should be ascending. Used when ordering is not specified explicitely and the results should be returned in ascending order.

See Also:: Constant Field Values

ORDER_DESCENDING

static final int ORDER_DESCENDING

Specifies that the query ordering should be descending. Used when ordering is not specified explicitely and the results should be returned in descending order.

See Also:: Constant Field Values

FUNCTION_DATA

static final int FUNCTION_DATA

Specifies that this query should return the instances matching the query criteria. This is the default query function used to retrieve instances.

See Also:: Constant Field Values

FUNCTION_COUNT

static final int FUNCTION_COUNT

Specifies that this query should return the total count of instances matching the query criteria. No instances are returned in the resulting collection.

If this function is not supported by the query recipient, then the resulting collection will be STATUS_APPERROR with a message of APPERROR_FUNCTION_NOT_SUPPORTED.

See Also:: Constant Field Values

FUNCTION_AVG

static final int FUNCTION_AVG

Specifies that this query should return the average value of each of the fields specified in the operationFields. If no fields are specified, then the resulting collection will have be STATUS_APPERROR with a message of APPERROR_NO_OPERANDS_SPECIFIED.

If this function is not supported by the query recipient, or if multiple fields are specified and the recipient cannot process multiple fields, then the resulting collection will be STATUS_APPERROR with a message of APPERROR_FUNCTION_NOT_SUPPORTED.

See Also:: Constant Field Values

FUNCTION_MAX

static final int FUNCTION_MAX

Specifies that this query should return the maximum value of each of the fields specified in the operationFields. If no fields are specified, then the resulting collection will have be STATUS_APPERROR with a message of APPERROR_NO_OPERANDS_SPECIFIED.

See Also:: Constant Field Values

FUNCTION_MIN

static final int FUNCTION_MIN

Specifies that this query should return the minimum value of each of the fields specified in the operationFields. If no fields are specified, then the resulting collection will have be STATUS_APPERROR with a message of APPERROR_NO_OPERANDS_SPECIFIED.

See Also:: Constant Field Values

FUNCTION_SUM

static final int FUNCTION_SUM

Specified that this query should return the total value of each of the fields specified in the operationFields. If no fields are specified, then the resulting collection will have be STATUS_APPERROR with a message of APPERROR_NO_OPERANDS_SPECIFIED.

See Also:: Constant Field Values

FUNCTION_UIDS

static final int FUNCTION_UIDS

Process the query as data, but return the uniqueID values for all matching instances without instantiating them. Useful for things like data pagination where the references are needed but the full instance is not.

See Also:: Constant Field Values

EXPRESSION_OPERATOR

static final java.lang.String EXPRESSION_OPERATOR

Special attribute signifying an extended expression operator. Used as a flag to signal that the value part of a SandAttrVal is an expression operator rather than a field value.

See Also:: Constant Field Values

APPERROR_NO_OPERANDS_SPECIFIED

static final java.lang.String APPERROR_NO_OPERANDS_SPECIFIED

Error message when a function is specified without operands

See Also:: Constant Field Values

APPERROR_INVALID_OPERATION_FIELDS

static final java.lang.String APPERROR_INVALID_OPERATION_FIELDS

Error message when the fields specified for a function are invalid.

See Also:: Constant Field Values

APPERROR_FUNCTION_NOT_SUPPORTED

static final java.lang.String APPERROR_FUNCTION_NOT_SUPPORTED

Error message used when the requested function is not supported by the query recipient.

See Also:: Constant Field Values

PAGE_NONE

static final int PAGE_NONE

Do not generate any paging info. The query will be processed and returned directly without any additional work done to create the paging information. This is the default processing.

See Also:: Constant Field Values

PAGE_TOTALONLY

static final int PAGE_TOTALONLY

In addition to processing the query, compute the total number of matching records and return that value. Do not generate full paging information. This is slower than PAGE_NONE because it needs to calculate the total, but faster than PAGE_ALL since it only requires one additional query.

See Also:: Constant Field Values

PAGE_ALL

static final int PAGE_ALL

In addition to processing the query, calculate the total and provide a data paging summary with page numbers and uniqueID values. The paging summary values can be used to jump to the most relevant areas of the data collection such as the first page, last page, and areas around the current page. Generating this information requires additional (and potentially significant) processing beyond just the query result so this value should only be used when the need to easily skip to a section of the resulting collection outweighs the additional processing required.

See Also:: Constant Field Values

Method Detail

getMatchInfo

SandAttrVal[] getMatchInfo()

Zero or more match expressions further constraining this query.

setMatchInfo

void setMatchInfo(SandAttrVal[] matchExpression)

Set the match expressions for this query.

addMatchInfo

void addMatchInfo(SandAttrVal av)

Append a new match expressions to the match information.

getMaxReturn

int getMaxReturn()

Get the maximum number of matching items to return in a resulting collection message.

setMaxReturn

void setMaxReturn(int max)

Set the maximum number of matching items to return in a resulting collection message.

getOrderBy

java.lang.String getOrderBy()

Get the comma separated field names to order the resulting collection with. If this is null or the empty string, then the collection is ordered by uniqueID, and data pagination is handled automatically. See Persist.html for more information.

setOrderBy

void setOrderBy(java.lang.String fieldsCSV)

Set the result collection ordering. See getOrderBy.

getOrderSense

int getOrderSense()

Return the order sense for this query. Values are one of the ORDER constants for ASCENDING, DESCENDING, or UNSPECIFIED (default).

setOrderSense

void setOrderSense(int sense)

Set the order sense. See getOrderSense for description.

getUniqueIDAfter

long getUniqueIDAfter()

Support for automatic data pagination. See getOrderBy.

setUniqueIDAfter

void setUniqueIDAfter(long id)

Support for automatic data pagination. See getOrderBy.

getFunction

int getFunction()

One of the FUNCTION values describing what kind of query processing is being requested. By default this is FUNCTION_DATA, see the constant value definitions for details.

setFunction

void setFunction(int functionType)

Set the FUNCTION value describing what kind of query processing is being requested.

getFunctionPrintValue

java.lang.String getFunctionPrintValue()

Return a print value representation of the query type value.

getOperationFields

java.lang.String getOperationFields()

Returns the field name or CSV of field names which the specified function applies to. This value is ignored for DATA or COUNT, and required for AVG, MAX, MIN.

setOperationFields

void setOperationFields(java.lang.String fieldNamesCSV)

Set the field name or CSV of field names which the speicifed function should be applied to.

getPagination

int getPagination()

Return the level of data pagination information to be returned with the query. Returns one of the PAGE constants.

setPagination

void setPagination(int level)

Set the level of data pagination information to be created when processing the query. One of the PAGE constants.

matches

boolean matches(java.lang.Object msg)

Return true if the given message matches this query. For this method to return true, the given message must be an instance of the corresponding SandStructMessage class for this query, and it must fit the matchInfo. The msg parameter is declared as Object rather than SandStructMessage so the method can be applied to any instance without having to downcast first.

normalize

void normalize()

Fix any spacing, quoting or other issues in our match expression fields to whatever extent possible. This fixes common quoting issues, use of enumeration constant values and anything else it can. The resulting expression is not guaranteed to be valid, but is better than it was.

undecimalize

java.lang.String undecimalize(java.lang.String attr,
                              java.lang.String val)

Given an attr, return the undecimalized form of the given val. If the field specified is not stored in decimalized form, then return the val unchanged.

cloneQuery

SandQueryMessage cloneQuery()

Return a deep copy of this query message.

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.sandev.basics.structs Interface SandQueryMessage