Package wt.query

Class QuerySpec

java.lang.Object
wt.query.QuerySpec
All Implemented Interfaces:
Externalizable, Serializable, Cloneable, StatementSpec, wt.query.CloneableStatementSpec, wt.query.CompoundComponentStatementSpec, wt.query.Hintable
Direct Known Subclasses:
NavigateSpec
public class QuerySpec extends Object implements wt.query.CloneableStatementSpec, wt.query.CompoundComponentStatementSpec, Externalizable, wt.query.Hintable
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:

  • Field Summary

    Fields inherited from interface wt.pds.StatementSpec

    ADVANCED_QUERY_ENABLED, USE_BIND

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
     
    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

    Modifier and Type
    Method
    Description
    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
    appendQueryHint(ArrayList<QueryHint> a_queryHintList)
    This method will accept the collection of QueryHint objects to improve query performance.
    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(String a_attributeName, int a_classIndex, boolean a_fullObject)
    Appends the class reference 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
    appendWhere(WhereExpression a_whereExpression, int[] a_fromIndicies)
    Appends an expression to the WHERE clause.
    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
    setBindParameterAt(Object a_value, int a_index)


    Supported API: true
    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
    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 Details

    • 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 Details

    • 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
      Specified by:
      isDistinct in interface wt.query.CompoundComponentStatementSpec
      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. Using this method on a QuerySpec instance that is executed using an API that enforces access control may result in a SQLException. This is because access control attributes will be added to the SELECT clause which are not compatible with the DISTINCT operation.

      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
      Specified by:
      getBindParameterCount in interface StatementSpec
      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, 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. Using this method on a QuerySpec instance that is executed using an API that enforces access control may result in a SQLException. This is because access control attributes will be added to the SELECT clause which are not compatible with 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

    • setBindParameterAt

      public void setBindParameterAt(Object a_value, int a_index)


      Supported API: true
      Specified by:
      setBindParameterAt in interface StatementSpec

    • 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

    • appendQueryHint

      public void appendQueryHint(ArrayList<QueryHint> a_queryHintList) throws QueryException
      This method will accept the collection of QueryHint objects to improve query performance.

      Supported API: true
      Specified by:
      appendQueryHint in interface wt.query.Hintable
      Parameters:
      a_queryHintList -
      Throws:
      QueryException

    • setQueryLimit

      public void setQueryLimit(int a_queryLimit)
      Set the query limit for the returned results from this query. The query limit is applied directly to results returned from the database before any AccessController filtering is applied (including standard access control). For queries where access control is applied, the number of results returned may be less than the query limit. If an end user or remotely accessible API can manipulate the query limit, ORDER BY or WHERE clause of the generated SQL, then using this query limit may result in revealing secured information.

      Supported API: true
      Parameters:
      a_queryLimit -