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:

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_NO_OPERANDS_SPECIFIED` Error message when a function is specified without operands
`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 number 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 taht this query should return the total value of each of the fields specified in the operationFields.

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.
`long`	`getUniqueIDAfter()` Support for automatic data pagination.
`boolean`	`matches(SandStructMessage 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`	`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, getSandTransmitAuthID, getSandTransmitErrorMessage, getSandTransmitStatus, setSandTransmissionCount, setSandTransmitAuthID, setSandTransmitErrorMessage, setSandTransmitStatus

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

getCollectionMessage, getQueryMessage, getShortName, getStructMessage, getUpdateMessage, isEquivalent

Field Detail

FUNCTION_DATA

public 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. The total number of matching entries is returned if available without additional processing overhead, otherwise it is set to zero.

See Also:: Constant Field Values

FUNCTION_COUNT

public static final int FUNCTION_COUNT

Specifies that this query should return the number 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

public 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

public 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

public 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

public static final int FUNCTION_SUM

Specified taht 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

APPERROR_NO_OPERANDS_SPECIFIED

public static final java.lang.String APPERROR_NO_OPERANDS_SPECIFIED

Error message when a function is specified without operands

See Also:: Constant Field Values

APPERROR_FUNCTION_NOT_SUPPORTED

public 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

Method Detail

getMatchInfo

public SandAttrVal[] getMatchInfo()

Zero or more match expressions further constraining this query.

setMatchInfo

public void setMatchInfo(SandAttrVal[] matchExpression)

Set the match expressions for this query.

addMatchInfo

public void addMatchInfo(SandAttrVal av)

Append a new match expressions to the match information.

getMaxReturn

public int getMaxReturn()

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

setMaxReturn

public void setMaxReturn(int max)

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

getOrderBy

public 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

public void setOrderBy(java.lang.String fieldsCSV)

Set the result collection ordering. See getOrderBy.

getUniqueIDAfter

public long getUniqueIDAfter()

Support for automatic data pagination. See getOrderBy.

setUniqueIDAfter

public void setUniqueIDAfter(long id)

Support for automatic data pagination. See getOrderBy.

getFunction

public 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

public void setFunction(int functionType)

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

getFunctionPrintValue

public java.lang.String getFunctionPrintValue()

Return a print value representation of the query type value.

getOperationFields

public 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

public void setOperationFields(java.lang.String fieldNamesCSV)

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

matches

public boolean matches(SandStructMessage msg)

Return true if the given message matches this query. For this method to return true:

The given message must be an instance of a class which can be aggregated into the result collection. So this must be an instanceof the corresponding SandStructMessage for this query.
The given message must fit the matchInfo for this query

normalize

public 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

public 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

public 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