wt.query
Class QuerySpec

java.lang.Object
  wt.query.QuerySpec

All Implemented Interfaces:

Externalizable, Serializable, Cloneable, StatementSpec, wt.query.CloneableStatementSpec

public class QuerySpec
extends Object
implements wt.query.CloneableStatementSpec, Externalizable

This class represents a Query in terms of Windchill objects. The Query is constructed in terms of classes, search condtions, etc. When used by the PersistenceManager, this class constructs a SQL query statement based on its current property values.

Note that this implementation is not synchronized. If mulitple threads modify or execute the same instance, then access must be synchronized externally. Alternatively, a copy of the instance could be made via the clone() method so that each thread accesses its own instance.

Supported API: true

Extendable: false

See Also:

Serialized Form

Field Summary

Fields inherited from interface wt.pds.StatementSpec

ADVANCED_QUERY_ENABLED, USE_BIND

Constructor Summary

QuerySpec()
Create the specification object.

QuerySpec(Class queryClass)
Create the specification object and identify the base class to be searched.

QuerySpec(Class baseClass1, Class baseClass2)
Create the specification object and identify the base classes to be searched.

Method Summary

int	addClassList(Class newClass, boolean isSelectable) Adds the class to the class list.
void	appendAnd() Add an AND operator to the where clause.
int	appendClassList(Class newClass, boolean isSelectable) Appends a new class to the class list.
void	appendCloseParen() Add a closing parenthesis to the where clause.
int	appendFrom(TableExpression a_tableExpression) Appends a Table Expression to the From clause.
void	appendGroupBy(ColumnExpression a_column, int[] a_fromIndicies, boolean a_appendSelect) Appends the column expression to the GROUP BY clause.
void	appendHaving(WhereExpression a_where, int[] a_fromIndicies) Appends the where expression to the HAVING clause.
void	appendHint(String a_hint) This method appends a datastore specific query optimization hint.
void	appendJoin(int a_linkIndex, String a_role, int a_targetIndex) Appends a join condition for the link class specified by the link index to the target class specified by the target index for the role.
void	appendJoin(int a_linkIndex, String a_role, Persistable a_source) Appends a join condition for the link class specified by the link index to the source object for the role.
void	appendNot() Add a NOT operator to the where clause.
void	appendOpenParen() Add an opening parenthesis to the where clause.
void	appendOr() Add an OR operator to the where clause.
void	appendOrderBy(OrderBy a_orderBy, int[] a_fromIndicies) This method appends the OrderBy expression to the OrderBy clause of the query.
void	appendSelect(ColumnExpression a_column, boolean a_selectOnly) Appends the column expression to the select clause.
void	appendSelect(ColumnExpression a_column, int[] a_fromIndicies, boolean a_selectOnly) Appends the column expression to the select clause.
void	appendSelectAttribute(String a_attributeName, int a_classIndex, boolean a_selectOnly) Appends the class attribute to the select clause.
void	appendSelectReference(ColumnExpression a_className, ColumnExpression a_id, int a_classNameFromIndex, int a_idFromIndex, boolean a_fullObject) Appends the class reference to the select clause.
void	appendSelectReference(String a_attributeName, int a_classIndex, boolean a_fullObject) Appends the class reference to the select clause.
void	appendWhere(WhereExpression a_whereExpression, int a_fromIndex) Deprecated. As of 7.0, use appendWhere(WhereExpression, int[])
void	appendWhere(WhereExpression a_whereExpression, int[] a_fromIndicies) Appends an expression to the WHERE clause.
void	appendWhere(WhereExpression a_whereExpression, int a_fromIndex1, int a_fromIndex2) Deprecated. As of 7.0, use appendWhere(WhereExpression, int[])
void	appendWhere(WhereExpression a_whereExpression, TableExpression[] a_tableExpressions, String[] a_aliases) Appends an expression to the WHERE clause.
Object	getBindParameterAt(int a_index) Returns the bind parameter value at the specified offset.
int	getBindParameterCount() Gets the value of the attribute: bindParameterCount; Indicates the number bind parameters for this Query.
int	getConditionCount() Gets the value of the attribute: conditionCount; Indicates the number of search conditions appended to this Query.
int	getDepthThreshold() Gets the value of the attribute: depthThreshold; Threshold value for the number of subclass combinations.
FromClause	getFromClause() Gets the object for the association that plays role: fromClause.
int	getResultIndex(int a_classIndex) Returns the result index for the class index based on the current selectable settings of the class list.
int[]	getResultIndicies() Returns an array of result indecies for every class in the class list based on the current selectable settings.
boolean	getSelect(int position) Returns the selectable property for the specified position in the class list.
boolean	isAdvancedQueryEnabled() Gets the value of the attribute: advancedQueryEnabled; Indicates if advanced query capabilities are enabled.
boolean	isDistinct() Gets the value of the attribute: distinct; Indicates whether Query returns distinct results.
boolean	isUseBind() Gets the value of the attribute: useBind; Indicates if bind parameters should be used when appending SearchConditions.
void	setAdvancedQueryEnabled(boolean a_AdvancedQueryEnabled) Sets the value of the attribute: advancedQueryEnabled; Indicates if advanced query capabilities are enabled.
void	setDepthThreshold(int a_DepthThreshold) Sets the value of the attribute: depthThreshold; Threshold value for the number of subclass combinations.
void	setDistinct(boolean a_Distinct) Sets the value of the attribute: distinct; Indicates whether Query returns distinct results.
void	setLocale(Locale a_locale) Set the client locale.
void	setQueryLimit(int a_queryLimit) Set the query limit for the returned results from this query.
void	setSelect(int position, boolean isSelectable) Sets the selectable property for the specified position in the class list.
void	setUseBind(boolean a_UseBind) Sets the value of the attribute: useBind; Indicates if bind parameters should be used when appending SearchConditions.

Methods inherited from class java.lang.Object

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

Constructor Detail

QuerySpec

public QuerySpec()
          throws QueryException

Create the specification object.

Supported API: true

Throws:

QueryException

QuerySpec

public QuerySpec(Class queryClass)
          throws QueryException

Create the specification object and identify the base class to be searched. Persistent subclasses will also be included in the search.

Supported API: true

Parameters:

queryClass - The class (plus it subclasses) being searched for persistent objects.

Throws:

QueryException - Occurs if the given class is not persistent.

QuerySpec

public QuerySpec(Class baseClass1,
                 Class baseClass2)
          throws QueryException

Create the specification object and identify the base classes to be searched. Persistent subclasses of each base class will also be included in the search.

Supported API: true

Parameters:

baseClass1 - first base class to be searched. If this QuerySpec is used as criteria for navigation, then this class is the target class of the navigation.

baseClass2 - second base class to be searched. If this QuerySpec is used as criteria for navigation, then this class is the link class of the navigation.

Throws:

QueryException - Occurs if the given class is not persistent.

Method Detail

isDistinct

public boolean isDistinct()

Gets the value of the attribute: distinct; Indicates whether Query returns distinct results. If true, the SQL DISTINCT is included in the select statement.

Supported API: true

Returns:

boolean

setDistinct

public void setDistinct(boolean a_Distinct)
                 throws WTPropertyVetoException

Sets the value of the attribute: distinct; Indicates whether Query returns distinct results. If true, the SQL DISTINCT is included in the select statement.

Supported API: true

Parameters:

a_Distinct -

Throws:

WTPropertyVetoException

getConditionCount

public int getConditionCount()

Gets the value of the attribute: conditionCount; Indicates the number of search conditions appended to this Query.

Supported API: true

Returns:

int

isUseBind

public boolean isUseBind()

Gets the value of the attribute: useBind; Indicates if bind parameters should be used when appending SearchConditions.

Supported API: true

Specified by:

isUseBind in interface StatementSpec

Returns:

boolean

setUseBind

public void setUseBind(boolean a_UseBind)
                throws WTPropertyVetoException

Sets the value of the attribute: useBind; Indicates if bind parameters should be used when appending SearchConditions.

Supported API: true

Specified by:

setUseBind in interface StatementSpec

Parameters:

a_UseBind -

Throws:

WTPropertyVetoException

getBindParameterCount

public int getBindParameterCount()

Gets the value of the attribute: bindParameterCount; Indicates the number bind parameters for this Query.

Supported API: true

Returns:

int

getDepthThreshold

public int getDepthThreshold()

Gets the value of the attribute: depthThreshold; Threshold value for the number of subclass combinations. Once this threshold is reached, a UNION statement is executed to determine which of the subclass combinations contains data that will need to be retrieved.

Supported API: true

Returns:

int

setDepthThreshold

public void setDepthThreshold(int a_DepthThreshold)
                       throws WTPropertyVetoException

Sets the value of the attribute: depthThreshold; Threshold value for the number of subclass combinations. Once this threshold is reached, a UNION statement is executed to determine which of the subclass combinations contains data that will need to be retrieved.

Supported API: true

Parameters:

a_DepthThreshold -

Throws:

WTPropertyVetoException

isAdvancedQueryEnabled

public boolean isAdvancedQueryEnabled()

Gets the value of the attribute: advancedQueryEnabled; Indicates if advanced query capabilities are enabled. By design, this attribute is transient and its value is not passed between Java Virtual Machine (JVM) processes. The value should be set within the same JVM process that executes the statement.

Supported API: true

Specified by:

isAdvancedQueryEnabled in interface StatementSpec

Returns:

boolean

setAdvancedQueryEnabled

public void setAdvancedQueryEnabled(boolean a_AdvancedQueryEnabled)

Sets the value of the attribute: advancedQueryEnabled; Indicates if advanced query capabilities are enabled. By design, this attribute is transient and its value is not passed between Java Virtual Machine (JVM) processes. The value should be set within the same JVM process that executes the statement.

Supported API: true

Specified by:

setAdvancedQueryEnabled in interface StatementSpec

Parameters:

a_AdvancedQueryEnabled -

getFromClause

public FromClause getFromClause()

Gets the object for the association that plays role: fromClause.

Supported API: true

Returns:

FromClause

getResultIndex

public int getResultIndex(int a_classIndex)

Returns the result index for the class index based on the current selectable settings of the class list. If the class index is not selectable, then -1 is returned. Note that this value can become invalid, if the selectable settings are modified.

Supported API: true

Parameters:

a_classIndex -

Returns:

int

getResultIndicies

public int[] getResultIndicies()

Returns an array of result indecies for every class in the class list based on the current selectable settings. If a class is not selectable, then -1 is returned in the associated array position. Note that these values can become invalid, if the selectable settings are modified.

Supported API: true

Returns:

int[]

appendSelectAttribute

public void appendSelectAttribute(String a_attributeName,
                                  int a_classIndex,
                                  boolean a_selectOnly)
                           throws QueryException

Appends the class attribute to the select clause.

Supported API: true

Parameters:

a_attributeName -

a_classIndex -

a_selectOnly -

Throws:

QueryException

appendFrom

public int appendFrom(TableExpression a_tableExpression)

Appends a Table Expression to the From clause.

Supported API: true

Parameters:

a_tableExpression -

Returns:

int

getBindParameterAt

public Object getBindParameterAt(int a_index)

Returns the bind parameter value at the specified offset.

Supported API: true

Parameters:

a_index -

Returns:

Object

appendWhere

public void appendWhere(WhereExpression a_whereExpression,
                        int a_fromIndex)
                 throws QueryException

Deprecated. As of 7.0, use appendWhere(WhereExpression, int[])

Appends an expression to the WHERE clause.

Supported API: true

Parameters:

a_whereExpression -

a_fromIndex -

Throws:

QueryException

appendWhere

public void appendWhere(WhereExpression a_whereExpression,
                        int a_fromIndex1,
                        int a_fromIndex2)
                 throws QueryException

Deprecated. As of 7.0, use appendWhere(WhereExpression, int[])

Appends an expression to the WHERE clause.

Supported API: true

Parameters:

a_whereExpression -

a_fromIndex1 -

a_fromIndex2 -

Throws:

QueryException

appendWhere

public void appendWhere(WhereExpression a_whereExpression,
                        TableExpression[] a_tableExpressions,
                        String[] a_aliases)
                 throws QueryException

Appends an expression to the WHERE clause. This method explicitly uses the TableExpressions and aliases specified which may be from outer selects.

Supported API: true

Parameters:

a_whereExpression -

a_tableExpressions -

a_aliases -

Throws:

QueryException

appendSelect

public void appendSelect(ColumnExpression a_column,
                         boolean a_selectOnly)
                  throws QueryException

Appends the column expression to the select clause. Note that ColumnExpression will not have a table alias applied. If one is required, then appendSelect(ColumnExpression, int[], boolean) should be used.

Supported API: true

Parameters:

a_column -

a_selectOnly -

Throws:

QueryException

appendSelectReference

public void appendSelectReference(String a_attributeName,
                                  int a_classIndex,
                                  boolean a_fullObject)
                           throws QueryException

Appends the class reference to the select clause.

Supported API: true

Parameters:

a_attributeName - Attribute name of the ObjectReference.

a_classIndex - Index in the From clause for the class that contains the ObjectReference attribute.

a_fullObject - Indicates whether a full ObjectReference instance should be returned in the result set. This value should be false if this QuerySpec is to be used as the primary statement of a PageableQuerySpec.

Throws:

QueryException

appendSelectReference

public void appendSelectReference(ColumnExpression a_className,
                                  ColumnExpression a_id,
                                  int a_classNameFromIndex,
                                  int a_idFromIndex,
                                  boolean a_fullObject)
                           throws QueryException

Appends the class reference to the select clause. The specified ColumnExpressions must return a classname and id value in the result set.

Supported API: true

Parameters:

a_className - ColumnExpression of the ObjectReference class name.

a_id - ColumnExpression of the ObjectReference ID.

a_classNameFromIndex - Index in the From clause for the ColumnExpression of the ObjectReference class name.

a_idFromIndex - Index in the From clause for the ColumnExpression of the ObjectReference ID.

a_fullObject - Indicates whether a full ObjectReference instance should be returned in the result set. This value should be false if this QuerySpec is to be used as the primary statement of a PageableQuerySpec.

Throws:

QueryException

appendWhere

public void appendWhere(WhereExpression a_whereExpression,
                        int[] a_fromIndicies)
                 throws QueryException

Appends an expression to the WHERE clause. This method uses the specified indicies to reference TableExpressions and aliases in the FromClause.

Supported API: true

Parameters:

a_whereExpression -

a_fromIndicies - array of ordinal index values into the QuerySpec's FromClause that reference TableExpressions used by the ColumnExpressions in the WhereExpression

Throws:

QueryException

appendSelect

public void appendSelect(ColumnExpression a_column,
                         int[] a_fromIndicies,
                         boolean a_selectOnly)
                  throws QueryException

Appends the column expression to the select clause.

Supported API: true

Parameters:

a_column - ColumnExpression to append to the query SELECT clause.

a_fromIndicies - array of ordinal index values into the QuerySpec's FromClause that reference TableExpressions used by the ColumnExpression

a_selectOnly - Indicates if the appended ColumnExpression should be added to the SELECT clause only. If true, then the value associated with this ColumnExpression will not be returned in the query results.

Throws:

QueryException

appendOrderBy

public void appendOrderBy(OrderBy a_orderBy,
                          int[] a_fromIndicies)
                   throws QueryException

This method appends the OrderBy expression to the OrderBy clause of the query. The indicies specifies the association of the from clause items with the expression.

Supported API: true

Parameters:

a_orderBy - OrderBy expression to append

a_fromIndicies - array of ordinal index values into the QuerySpec's FromClause that reference TableExpressions used by the ColumnExpression in the OrderBy

Throws:

QueryException

appendGroupBy

public void appendGroupBy(ColumnExpression a_column,
                          int[] a_fromIndicies,
                          boolean a_appendSelect)
                   throws QueryException

Appends the column expression to the GROUP BY clause.

Supported API: true

Parameters:

a_column - object to append

a_fromIndicies - array of ordinal index values into the QuerySpec's FromClause that reference TableExpressions used by the ColumnExpression

a_appendSelect - Indicates if the ColumnExpression should be appended to the SELECT clause also.

Throws:

QueryException

appendJoin

public void appendJoin(int a_linkIndex,
                       String a_role,
                       Persistable a_source)
                throws WTException

Appends a join condition for the link class specified by the link index to the source object for the role.

Supported API: true

Parameters:

a_linkIndex - Index of the link class in this QuerySpec

a_role - The role on the link association

a_source - The Persistable instance to join the link to

Throws:

WTException

appendJoin

public void appendJoin(int a_linkIndex,
                       String a_role,
                       int a_targetIndex)
                throws WTException

Appends a join condition for the link class specified by the link index to the target class specified by the target index for the role.

Supported API: true

Parameters:

a_linkIndex - Index of the link class in this QuerySpec

a_role - The role on the link association

a_targetIndex - The index of the target class to join the link to

Throws:

WTException

appendHint

public void appendHint(String a_hint)
                throws QueryException

This method appends a datastore specific query optimization hint.

Supported API: true

Parameters:

a_hint - This is the hint which will be specified.

Throws:

QueryException

appendHaving

public void appendHaving(WhereExpression a_where,
                         int[] a_fromIndicies)
                  throws QueryException

Appends the where expression to the HAVING clause.

Supported API: true

Parameters:

a_where - object to append

a_fromIndicies - array of ordinal index values into the QuerySpec's FromClause that reference TableExpressions used by the ColumnExpressions in the WhereExpression

Throws:

QueryException

setLocale

public void setLocale(Locale a_locale)
               throws WTException

Set the client locale.

Supported API: true

Specified by:

setLocale in interface StatementSpec

Parameters:

a_locale -

Throws:

WTException

appendClassList

public int appendClassList(Class newClass,
                           boolean isSelectable)
                    throws QueryException

Appends a new class to the class list.

Supported API: true

Parameters:

newClass - class to append

isSelectable - indicates if the class is included in the SELECT

Returns:

int position in the class list where this class was appended

Throws:

QueryException

addClassList

public int addClassList(Class newClass,
                        boolean isSelectable)
                 throws QueryException

Adds the class to the class list. A new class is added, only if the class is currently not in the class list.

Supported API: true

Parameters:

newClass - class to add

isSelectable - indicates if the class is included in the SELECT

Returns:

int position in the class list

Throws:

QueryException

getSelect

public boolean getSelect(int position)
                  throws QueryException

Returns the selectable property for the specified position in the class list. A selectable class will be returned in the QueryResult.

Supported API: true

Parameters:

position - class list position

Returns:

boolean true, if the class is selectable

Throws:

QueryException - if invalid position is specified

setSelect

public void setSelect(int position,
                      boolean isSelectable)
               throws QueryException

Sets the selectable property for the specified position in the class list. A selectable class will be returned in the QueryResult.

Supported API: true

Parameters:

position - class list position

isSelectable - indicates the class is selectable

Throws:

QueryException - if invalid position is specified

appendOpenParen

public void appendOpenParen()

Add an opening parenthesis to the where clause.

Supported API: true

appendCloseParen

public void appendCloseParen()

Add a closing parenthesis to the where clause.

Supported API: true

appendAnd

public void appendAnd()

Add an AND operator to the where clause.

Supported API: true

appendOr

public void appendOr()

Add an OR operator to the where clause.

Supported API: true

appendNot

public void appendNot()

Add a NOT operator to the where clause.

Supported API: true

setQueryLimit

public void setQueryLimit(int a_queryLimit)

Set the query limit for the returned results from this query.

Supported API: true

Parameters:

a_queryLimit -