com.edustructures.sifworks
Class Query

java.lang.Object
  com.edustructures.sifworks.Query

public class Query
extends java.lang.Object

Encapsulates a SIF Query.

An instance of this class is passed to the Zone.query and Topic.query methods when issuing a SIF Request. A Query object defines the following parameters to the request:

• The type of SIF Data Object to query for
• Conditions: One or more conditions may be placed on the query to select a subset of objects from the responder (when no conditions are present the responder returns all objects)
• Field Restrictions: An optional list of elements to include in responses to the query (when no field restrictions are present the responder returns the full set of elements for each object)

To construct a simple Query to query for all objects with no conditions or field restrictions, call the constructor that accepts an ElementDef constant from the SIFDTD class:

Query myQuery = new Query( SIFDTD.STUDENTPERSONAL );


More complex queries can be constructed by specifying conditions and field restrictions.

Conditions

A Query may optionally specify one or more conditions to restrict the number of objects returned by the responder. (Refer to the SIF Specification for a detailed description of how query conditions may be constructed.) When no conditions are specified, the responder interprets the query to mean "all objects". Note SIF 1.0r2 and earlier limit queries such that only root-level attributes may be included in query conditions, and only the equals ("EQ") comparison operator may be used. SIF 1.1 and later allow agents to query for elements within an object, but responders may return an error if they do not support that functionality.

Query conditions are encapsulated by the ADK's ConditionGroup class, which is used to build SIF_ConditionGroup, SIF_Conditions, and SIF_Condition elements when the class framework sends a SIF_Request message to a zone. Every Query with conditions has a root ConditionGroup with one or more child ConditionGroups. Unless you construct these groups manually, the Query class will automatically establish a root ConditionGroup and a single child when the addCondition method is called. Use the addCondition method to add conditions to a Query. Note the form of Query constructor you call determines how the addCondition method works. If you call the default constructor, the ADK automatically establishes a root SIF_ConditionGroup with a Type attribute of "None", and a single SIF_Conditions child with a Type attribute of "And". ("None" will be used if the query has only one condition.) SIF_Condition elements are then added to this element whenever the addCondition method is called.

For example,

// Query for a single student by RefId
Query query = new Query( SIFDTD.STUDENTPERSONAL );
query.addCondition(
SIFDTD.STUDENTPERSONAL_REFID, Condition.EQ,
"4A37969803F0D00322AF0EB969038483" );


If you want to specify the "Or" comparision operator instead of the default of "And", call the constructor that accepts a constant from the Condition class.

For example,

// Query for student where the RefId is A, B, or C
Query query = new Query( SIFDTD.STUDENTPERSONAL, Condition.OR );

query.addCondition(
SIFDTD.STUDENTPERSONAL_REFID, Condition.EQ,
"4A37969803F0D00322AF0EB969038483" );
query.addCondition(
SIFDTD.STUDENTPERSONAL_REFID, Condition.EQ,
"5A37969803F0D00322AF0EB969038484" );
query.addCondition(
SIFDTD.STUDENTPERSONAL_REFID, Condition.EQ,
"6A37969803F0D00322AF0EB969038485" );


The above examples show how to add simple conditions to a Query. To construct complex queries with nested groups of conditions, create your own root SIF_ConditionGroup object by calling the form of constructor that accepts a ConditionGroup instance. You can specify nested ConditionGroup children of this root object.

For example,

// Query for student where the Last Name is Jones and the First Name is
// Bob, and the graduation year is 2004, 2005, or 2006
ConditionGroup root = new ConditionGroup( Condition.AND );
ConditionGroup grp1 = new ConditionGroup( Condition.AND );
ConditionGroup grp2 = new ConditionGroup( Condition.OR );

// For nested elements, you cannot reference a SIFDTD constant. Instead, use
// the lookupElementDefBySQL function to lookup an ElementDef constant
// given a SIF Query Pattern (SQP)
ElementDef lname = ADK.DTD().lookupElementDefBySQP(
SIFDTD.STUDENTPERSONAL, "Name/LastName" );
ElementDef fname = ADK.DTD().lookupElementDefBySQP(
SIFDTD.STUDENTPERSONAL, "Name/FirstName" );
grp1.addCondition( lname, Condition.EQ, "Jones" );
grp1.addCondition( fname, Condition.EQ, "Bob" );

grp2.addCondition( SIFDTD.STUDENTPERSONAL_GRADYEAR, Condition.EQ, "2004" );
grp2.addCondition( SIFDTD.STUDENTPERSONAL_GRADYEAR, Condition.EQ, "2005" );
grp2.addCondition( SIFDTD.STUDENTPERSONAL_GRADYEAR, Condition.EQ, "2006" );

// Add condition groups to the root group
root.addGroup( grp1 );
root.addGroup( grp2 );

// Query for student with the conditions prepared above by passing the
// root ConditionGroup to the constructor
Query query = new Query( SIFDTD.STUDENTPERSONAL, root );


Field Restrictions

If only a subset of elements and attributes are requested, use the setFieldRestrictions method to indicate which elements and attributes should be returned to your agent by the responder. For example, to request the <StudentPersonal> object with RefId "4A37969803F0D00322AF0EB969038483" but to only include the RefId attribute and Name and PhoneNumber elements in the response,

// Query for a single student by RefId
Query query = new Query( SIFDTD.STUDENTPERSONAL );

query.addCondition(
SIFDTD.STUDENTPERSONAL_REFID, Condition.EQ,
"4A37969803F0D00322AF0EB969038483" );
query.setFieldRestrictions(
new ElementDef[] {
SIFDTD.STUDENTPERSONAL_REFID,
SIFDTD.STUDENTPERSONAL_NAME,
SIFDTD.STUDENTPERSONAL_PHONENUMBER
} );

Version:

1.0

Constructor Summary

Query(ElementDef objectType)
Constructs a Query object with no initial conditions or field restrictions.

Query(ElementDef objectType, ConditionGroup conditions)
Constructs a Query object with a ConditionGroup.

Query(ElementDef objectType, GroupOperators logicalOp)
Constructs a Query object with one ConditionGroup where all conditions in the group are evaluated using the supplied boolean operator (either Condition.AND or Condition.OR).

Query(SIF_Query query)
Constructs a Query object from a SIF_QueryObject.

Method Summary

void	addCondition(Condition condition) Add a condition to this query.
void	addCondition(ElementDef field, ComparisonOperators ops, java.lang.String value) Add a condition to this query.
void	addCondition(java.lang.String xPath, ComparisonOperators ops, java.lang.String value) Add a condition to this query using a deeply nested path.
void	addCondition(java.lang.String field, java.lang.String ops, java.lang.String value) Add a condition to this query.
void	addFieldRestriction(ElementDef field) Restricts the query to a specific field (i.e.
boolean	evaluate(SIFDataObject obj) Evaluate the given the SIFDataObject against the conditions provided in the Query.
boolean	evaluate(SIFDataObject obj, java.util.Comparator comparer) Evaluate the given the SIFDataObject against the conditions provided in the Query.
ConditionGroup[]	getConditions() Gets the conditions placed on this query.
SIFVersion	getEffectiveVersion() From the list of SIFVersions associated with this Query, returns the latest SIFVersion supported by the current ADK instance.
ElementDef[]	getFieldRestrictions() Gets the fields to include in the result of the query.
java.lang.String	getObjectTag() Gets the tag name of the object type being queried
ElementDef	getObjectType() Gets the object type being queried
ConditionGroup	getRootConditionGroup() Gets the root ConditionGroup.
SIFContext	getSIFContext() Gets the SIF Context that this Query applies to
SIFVersion[]	getSIFVersions() Sets the value of the SIF_Request/SIF_Version element.
java.io.Serializable	getUserData() Gets the custom state object associated with this query
Condition	hasCondition(ElementDef elementOrAttr) Tests if this Query has a specific element or attribute condition
Condition	hasCondition(java.lang.String xPath) Tests if this Query has a condition referencing a specific xPath
boolean	hasConditions() Determines if this Query has any conditions
boolean	hasFieldRestrictions() Determines if this Query has any field restrictions
void	setConditionGroup(ConditionGroup root) Sets the root ConditionGroup.
void	setFieldRestrictions(ElementDef[] fields) Restricts the query to the specified elements and attributes
void	setSIFContext(SIFContext context) Sets the SIFContext that this query should apply to
void	setSIFVersions(SIFVersion... versions) Sets the value of the SIF_Request/SIF_Version element.
void	setUserData(java.io.Serializable userData) Allows a custom state object to be associated with a query
SIF_Query	toSIF_Query() Returns the SIF_Query representation of this Query in the format required by SIF
SIF_Query	toSIF_Query(SIFVersion version) Returns the SIF_Query representation of this Query in the format required by SIF for the specified version
java.lang.String	toXML() Returns the XML representation of this Query in the format required by SIF
java.lang.String	toXML(SIFVersion version) Returns the XML representation of this Query in the format required by SIF for the specified version

Methods inherited from class java.lang.Object

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

Constructor Detail

Query

public Query(ElementDef objectType)

Constructs a Query object with no initial conditions or field restrictions. If conditions are subsequently added to the Query, they will be evaluated as a group with the logical AND operator. To specify that the logical OR operator be used, call the form of constructor that accepts an alternate operator.

Parameters:

objectType - An ElementDef describing the object type to query (e.g. ADK.DTD.STUDENTPERSONAL)

Query

public Query(ElementDef objectType,
             GroupOperators logicalOp)

Constructs a Query object with one ConditionGroup where all conditions in the group are evaluated using the supplied boolean operator (either Condition.AND or Condition.OR). All Conditions subsequently added to this Query will be placed into the ConditionGroup created by the constructor.

This constructor is provided as a convenience so that callers do not have to explicitly create a ConditionGroup for simple queries.

Parameters:

objectType - An ElementDef describing the object type to query (e.g. ADK.DTD.STUDENTPERSONAL)

logicalOp - The logical operator that defines how to compare this group with other condition groups that comprise the query (e.g. GroupOperators.OR)

Query

public Query(ElementDef objectType,
             ConditionGroup conditions)

Constructs a Query object with a ConditionGroup.

Parameters:

objectType - An ElementDef describing the object type to query (e.g. ADK.DTD.STUDENTPERSONAL)

conditions - A ConditionGroup comprised of one or more query Conditions

Query

public Query(SIF_Query query)
      throws ADKUnknownOperatorException,
             ADKSchemaException

Constructs a Query object from a SIF_QueryObject.

This constructor is not typically called by agents but is used internally by the class framework. The other constructors can be used to safely create Query instances to request a specific SIF Data Object. Use the addCondition and setFieldRestrictions methods to further define the conditions and SIF elements specified by the query.

Parameters:

query - A SIF_Query object received in a SIF_Request message

Throws:

ADKUnknownOperatorException - If one of the operators in the SIF_Query is unrecognized by the ADK

ADKSchemaException - If the object or elements defined in the query or not recognized by the ADK

Method Detail

toXML

public java.lang.String toXML()

Returns the XML representation of this Query in the format required by SIF

Returns:

a string containing the XML representation as a SIF_Query element. If an error occurs during the conversion, an empty string ("") is returned.

toXML

public java.lang.String toXML(SIFVersion version)

Returns the XML representation of this Query in the format required by SIF for the specified version

Parameters:

version - The SIF Version to render the Query in. The ADK will attempt to render the query path using the proper element or attribute names for the version of SIF

Returns:

a string containing the XML representation as a SIF_Query element. If an error occurs during the conversion, an empty string ("") is returned.

toSIF_Query

public SIF_Query toSIF_Query()

Returns the SIF_Query representation of this Query in the format required by SIF

Returns:

A SIF_Query element.

toSIF_Query

public SIF_Query toSIF_Query(SIFVersion version)

Returns the SIF_Query representation of this Query in the format required by SIF for the specified version

Parameters:

version - The SIF Version to render the Query in. The ADK will attempt to render the query path using the proper element or attribute names for the version of SIF

Returns:

A SIF_Query element.

getObjectType

public ElementDef getObjectType()

Gets the object type being queried

Returns:

The name of the object passed to the constructor

getObjectTag

public java.lang.String getObjectTag()

Gets the tag name of the object type being queried

Returns:

The tag name of the object passed to the constructor

getUserData

public java.io.Serializable getUserData()

Gets the custom state object associated with this query

Returns:

The custom data that was set to setUserData(Serializable)

setUserData

public void setUserData(java.io.Serializable userData)

Allows a custom state object to be associated with a query

Parameters:

userData - A custom state object that implements the Serializable interface

addCondition

public void addCondition(ElementDef field,
                         ComparisonOperators ops,
                         java.lang.String value)

Add a condition to this query.

This method of adding conditions is convenient for adding conditions involving root attributes or elements to a query. If you need to add conditions on deeply nested elements, use addCondition(String, ComparisonOperators, String)

Parameters:

field - A constant from the SIFDTD class that identifies an element or attribute of the data object (e.g. SIFDTD.STUDENTPERSONAL_REFID).

ops - The comparison operator. Comparison operator constants are defined by the ComparisionOperators enum

value - The data that is used to compare to the element or attribute

Throws:

java.lang.IllegalArgumentException - if the ElementDef does not represent an immediate child of the object being queried.

addCondition

public void addCondition(Condition condition)

Add a condition to this query.

Parameters:

condition - The condition to add. This condition is added to the root condition group.

See Also:

getRootConditionGroup(), getConditions()

addCondition

public void addCondition(java.lang.String xPath,
                         ComparisonOperators ops,
                         java.lang.String value)

Add a condition to this query using a deeply nested path. Using this method of adding query condition allows for specifying deeply nested query conditions. However, the xpath specified here is specific to the version of SIF

To ensure your code works with all versions of SIF, you should use addCondition(ElementDef, ComparisonOperators, String) whenever possible.

Parameters:

xPath - The Simple XPath to use for this query condition. E.g. SIF_ExendedElements/SIF_ExtendedElement[@Name='eyecolor']

ops - The comparison operator. Comparison operator value from the ComparisonOperators enum

value - The data that is used to compare to the element or attribute

addCondition

public void addCondition(java.lang.String field,
                         java.lang.String ops,
                         java.lang.String value)

Add a condition to this query. This form of the addCondition method is intended to be called internally by the ADK when parsing an incoming SIF_Query element. To ensure your code works with all versions of SIF, you should use the other form of this method that accepts an ElementDef constant for the field parameter whenever possible.

Parameters:

field - Identifies an element or attribute of the data object in SIF Query Pattern form as described by the SIF 1.0r2 Specification (e.g. "@RefId"). With SIF 1.0r2 and earlier, only root-level attributes may be specified in a query. Note this string is specific to the version of SIF associated with the Query as element and attribute names may vary from one version of SIF to the next. The version defaults to the version of SIF in effect for the agent or the version of SIF associated with the SIF_Query object passed to the constructor.

ops - A value from the ComparisonOperators enum

value - The data that is used to compare to the element or attribute

addFieldRestriction

public void addFieldRestriction(ElementDef field)

Restricts the query to a specific field (i.e. element or attribute) of the data object being requested. If invoked, the results of the query will only contain the elements or attributes specified by the fields for which this method is called (call this method repeatedly for each field). Otherwise, the results will contain a complete object.

Parameters:

field - A ElementDef object defined by the static constants of the SIFDTD class. For example, to restrict a query for the StudentPersonal topic to include only the StatePr element of the student address, pass SIFDTD.ADDRESS_STATEPR. This would cause the query results to include only StudentPersonal/Address/StatePr elements.

setFieldRestrictions

public void setFieldRestrictions(ElementDef[] fields)

Restricts the query to the specified elements and attributes

Parameters:

fields - An array of ElementDef objects identifying one or more elements and/or attributes

getFieldRestrictions

public ElementDef[] getFieldRestrictions()

Gets the fields to include in the result of the query.

Returns:

An array of fields that should be included in the results of this query, or null if all fields are to be included

getConditions

public ConditionGroup[] getConditions()

Gets the conditions placed on this query.

Returns:

An array of ConditionGroup objects in evaluation order. The children of the root ConditionGroup are returned. If no conditions have been specified, an empty array is returned.

getRootConditionGroup

public ConditionGroup getRootConditionGroup()

Gets the root ConditionGroup.

Returns:

The root ConditionGroup that was established by the constructor. If this query has no conditions, null is returned.

hasConditions

public boolean hasConditions()

Determines if this Query has any conditions

Returns:

true if the query has one or more conditions

See Also:

getConditions(), addCondition(ElementDef, ComparisonOperators, String)

hasFieldRestrictions

public boolean hasFieldRestrictions()

Determines if this Query has any field restrictions

Returns:

true if the query specifies a subset of fields to be returned; false if the query returns all elements and attributes of each object matching the query conditions

See Also:

getFieldRestrictions(), addFieldRestriction(com.edustructures.sifworks.ElementDef), setFieldRestrictions(com.edustructures.sifworks.ElementDef[])

hasCondition

public Condition hasCondition(ElementDef elementOrAttr)

Tests if this Query has a specific element or attribute condition

Parameters:

elementOrAttr - The ElementDef constant from the SIFDTD class that identifies the specific attribute or element to search for

Returns:

The string value of the element or attribute, if found. If no Condition exists for the element or attribute, null is returned

hasCondition

public Condition hasCondition(java.lang.String xPath)

Tests if this Query has a condition referencing a specific xPath

Parameters:

xPath - The ElementDef constant from the SIFDTD class that identifies the specific attribute or element to search for

Returns:

The string value of the element or attribute, if found. If no Condition exists for the element or attribute, null is returned

setSIFVersions

public void setSIFVersions(SIFVersion... versions)

Sets the value of the SIF_Request/SIF_Version element. By default, this value is set to the version of SIF declared for the agent when the ADK was initialized.

Parameters:

versions - The version(s) of SIF the responding agent should use when returning SIF_Response messages for this query

getSIFVersions

public SIFVersion[] getSIFVersions()

Sets the value of the SIF_Request/SIF_Version element. By default, this value is set to the version of SIF declared for the agent when the ADK was initialized.

Returns:

The version of SIF the responding agent should use when returning SIF_Response messages for this query

getEffectiveVersion

public SIFVersion getEffectiveVersion()

From the list of SIFVersions associated with this Query, returns the latest SIFVersion supported by the current ADK instance.

Returns:

The latest SIFVersion supported by the ADK for this Query

See Also:

ADK.getLatestSupportedVersion(SIFVersion[])

setConditionGroup

public void setConditionGroup(ConditionGroup root)

Sets the root ConditionGroup.

By default a Query is constructed with a ConditionGroup to which individual conditions will be added by the addCondition methods. You can call this method to prepare a ConditionGroup ahead of time and replace the default with your own.

Note calling this method after addCondition will replace any conditions previously added to the Query with the conditions in the supplied ConditionGroup.

Parameters:

root - The root ConditionGroup to use for this query

evaluate

public boolean evaluate(SIFDataObject obj)
                 throws ADKSchemaException

Evaluate the given the SIFDataObject against the conditions provided in the Query. All conditions are evaluated using standard string comparisons using the system's locale-specific collator

Parameters:

obj - The SIFDataObject to evalaute against this query

Returns:

TRUE if the SIFDataObject satisfies the conditions in the Query, otherwise FALSE

Throws:

ADKSchemaException - If the condition contains references to invalid elements

evaluate

public boolean evaluate(SIFDataObject obj,
                        java.util.Comparator comparer)
                 throws ADKSchemaException

Evaluate the given the SIFDataObject against the conditions provided in the Query. All conditions are evaluated using the provided comparer

Parameters:

obj - The SIFDataObject to evalaute against this query

comparer - The comparer used to do comparisons

Returns:

TRUE if the SIFDataObject satisfies the conditions in the Query, otherwise FALSE

Throws:

ADKSchemaException - If the condition contains references to invalid elements

setSIFContext

public void setSIFContext(SIFContext context)

Sets the SIFContext that this query should apply to

Parameters:

context - The SIF Context that this query applies to

getSIFContext

public SIFContext getSIFContext()

Gets the SIF Context that this Query applies to

Returns:

The SIF Context that this query applies to