Module org.eclipse.persistence.core
Package org.eclipse.persistence.queries

Class ReadAllQuery

java.lang.Object
org.eclipse.persistence.queries.DatabaseQuery
org.eclipse.persistence.queries.ReadQuery
org.eclipse.persistence.queries.ObjectBuildingQuery
org.eclipse.persistence.queries.ObjectLevelReadQuery
org.eclipse.persistence.queries.ReadAllQuery
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
ReportQuery
public class ReadAllQuery extends ObjectLevelReadQuery

Purpose: Concrete class for all read queries involving a collection of objects.

Responsibilities: Return a container of the objects generated by the query. Implements the inheritance feature when dealing with abstract descriptors

Since:
TOPLink/Java 1.0
See Also:

  • Field Details

    • containerPolicy

      protected ContainerPolicy containerPolicy
      Used for collection and stream support.

    • startWithExpression

      protected Expression startWithExpression
      Used for Oracle HierarchicalQuery support

    • connectByExpression

      protected Expression connectByExpression

    • orderSiblingsByExpressions

      protected List<Expression> orderSiblingsByExpressions

    • direction

      protected ReadAllQuery.Direction direction

  • Constructor Details

    • ReadAllQuery

      public ReadAllQuery()
      PUBLIC: Return a new read all query. A reference class must be specified before execution. It is better to provide the class and expression builder on construction to ensure a single expression builder is used. If no selection criteria is specified this will read all objects of the class from the database.

    • ReadAllQuery

      public ReadAllQuery(Class<?> classToRead)
      PUBLIC: Return a new read all query. It is better to provide the class and expression builder on construction to ensure a single expression builder is used. If no selection criteria is specified this will read all objects of the class from the database.

    • ReadAllQuery

      public ReadAllQuery(Class<?> classToRead, Expression selectionCriteria)
      PUBLIC: Return a new read all query for the class and the selection criteria.

    • ReadAllQuery

      public ReadAllQuery(Class<?> classToRead, ExpressionBuilder builder)
      PUBLIC: Return a new read all query for the class. The expression builder must be used for all associated expressions used with the query.

    • ReadAllQuery

      public ReadAllQuery(Class<?> classToRead, Call call)
      PUBLIC: Return a new read all query. The call represents a database interaction such as SQL, Stored Procedure.

    • ReadAllQuery

      public ReadAllQuery(Object exampleObject, QueryByExamplePolicy policy)
      PUBLIC: Return a query by example query to find all objects matching the attributes of the example object.

    • ReadAllQuery

      public ReadAllQuery(ExpressionBuilder builder)
      PUBLIC: The expression builder should be provide on creation to ensure only one is used.

    • ReadAllQuery

      public ReadAllQuery(Call call)
      PUBLIC: Create a read all query with the database call.

  • Method Details

    • addAscendingOrdering

      public void addAscendingOrdering(String queryKeyName)
      PUBLIC: Order the query results by the object's attribute or query key name.

    • cacheResult

      public void cacheResult(Object unwrappedOriginal)
      INTERNAL:

      This method is called by the object builder when building an original. It will cause the original to be cached in the query results if the query is set to do so.

      Specified by:
      cacheResult in class ReadQuery

    • checkEarlyReturnLocal

      protected Object checkEarlyReturnLocal(AbstractSession session, AbstractRecord translationRow)
      INTERNAL: The cache check is done before the prepare as a hit will not require the work to be done.
      Specified by:
      checkEarlyReturnLocal in class ObjectLevelReadQuery

    • checkCustomQueryFlag

      protected Boolean checkCustomQueryFlag(AbstractSession session, AbstractRecord translationRow)
      INTERNAL: Check and return custom query flag. Custom query flag value is initialized when stored value is null. Called from ObjectLevelReadQuery.checkForCustomQuery(AbstractSession, AbstractRecord) to retrieve custom query flag.
      Specified by:
      checkCustomQueryFlag in class ObjectLevelReadQuery
      Parameters:
      session - Current session (not used).
      translationRow - Database record (not used).
      Returns:
      Current custom query flag. Value will never be null.

    • getReadQuery

      protected ObjectLevelReadQuery getReadQuery()
      INTERNAL: Get custom all read query from query manager. Called from ObjectLevelReadQuery.checkForCustomQuery(AbstractSession, AbstractRecord) to retrieve custom read query.
      Specified by:
      getReadQuery in class ObjectLevelReadQuery
      Returns:
      Custom all read query from query manager.

    • clone

      public Object clone()
      INTERNAL: Creates and returns a copy of this query.
      Overrides:
      clone in class ObjectLevelReadQuery
      Returns:
      A clone of this instance.

    • conformResult

      protected Object conformResult(Object result, UnitOfWorkImpl unitOfWork, AbstractRecord arguments, boolean buildDirectlyFromRows)
      INTERNAL: Conform the result if specified.

    • execute

      public Object execute(AbstractSession session, AbstractRecord row) throws DatabaseException
      INTERNAL: Execute the query. If there are cached results return those. This must override the super to support result caching.
      Overrides:
      execute in class ObjectLevelReadQuery
      Parameters:
      session - - the session in which the receiver will be executed.
      Returns:
      An object or vector, the result of executing the query.
      Throws:
      DatabaseException - - an error has occurred on the database

    • executeObjectLevelReadQuery

      protected Object executeObjectLevelReadQuery() throws DatabaseException
      INTERNAL: Execute the query. Get the rows and build the object from the rows.
      Specified by:
      executeObjectLevelReadQuery in class ObjectLevelReadQuery
      Returns:
      java.lang.Object collection of objects resulting from execution of query.
      Throws:
      DatabaseException - - an error has occurred on the database

    • executeObjectLevelReadQueryFromResultSet

      protected Object executeObjectLevelReadQueryFromResultSet() throws DatabaseException
      INTERNAL: Execute the query building the objects directly from the database result-set.
      Specified by:
      executeObjectLevelReadQueryFromResultSet in class ObjectLevelReadQuery
      Returns:
      an ArrayList of the resulting objects.
      Throws:
      DatabaseException - - an error has occurred on the database

    • extractRemoteResult

      public Object extractRemoteResult(Transporter transporter)
      INTERNAL: Extract the correct query result from the transporter.
      Overrides:
      extractRemoteResult in class DatabaseQuery

    • getContainerPolicy

      public ContainerPolicy getContainerPolicy()
      INTERNAL: Return the query's container policy.

    • getDefaultRedirector

      protected QueryRedirector getDefaultRedirector()
      INTERNAL: Returns the specific default redirector for this query type. There are numerous default query redirectors. See ClassDescriptor for their types.
      Overrides:
      getDefaultRedirector in class DatabaseQuery

    • getStartWithExpression

      public Expression getStartWithExpression()
      PUBLIC:
      Returns:
      Expression - the start with expression used to generated the hierarchical query clause in Oracle

    • getConnectByExpression

      public Expression getConnectByExpression()
      PUBLIC:
      Returns:
      Expression - the connect by expression used to generate the hierarchical query caluse in Oracle

    • getOrderSiblingsByExpressions

      public List<Expression> getOrderSiblingsByExpressions()
      PUBLIC:
      Returns:
      List<Expression> - the ordering expressions used to generate the hierarchical query clause in Oracle

    • getDirection

      public ReadAllQuery.Direction getDirection()
      PUBLIC:
      Returns:
      Direction - the direction in which the hierarchy is traversed

    • hasHierarchicalExpressions

      public boolean hasHierarchicalExpressions()
      INTERNAL: Verify that we have hierarchical query expressions

    • isDefaultPropertiesQuery

      public boolean isDefaultPropertiesQuery()
      INTERNAL: Return true if the query uses default properties. This is used to determine if this query is cacheable. i.e. does not use any properties that may conflict with another query with the same JPQL or selection criteria.
      Overrides:
      isDefaultPropertiesQuery in class ObjectLevelReadQuery

    • equals

      public boolean equals(Object object)
      INTERNAL: Return if the query is equal to the other. This is used to allow dynamic expression query SQL to be cached.
      Overrides:
      equals in class ObjectLevelReadQuery

    • isReadAllQuery

      public boolean isReadAllQuery()
      PUBLIC: Return if this is a read all query.
      Overrides:
      isReadAllQuery in class DatabaseQuery

    • prepare

      protected void prepare() throws QueryException
      INTERNAL: Prepare the receiver for execution in a session.
      Overrides:
      prepare in class ObjectLevelReadQuery
      Throws:
      QueryException

    • prepareFromQuery

      public void prepareFromQuery(DatabaseQuery query)
      INTERNAL: Prepare the query from the prepared query. This allows a dynamic query to prepare itself directly from a prepared query instance. This is used in the JPQL parse cache to allow preparsed queries to be used to prepare dynamic queries. This only copies over properties that are configured through JPQL.
      Overrides:
      prepareFromQuery in class ObjectLevelReadQuery

    • prepareCustomQuery

      protected void prepareCustomQuery(DatabaseQuery customQuery)
      INTERNAL: Set the properties needed to be cascaded into the custom query.
      Overrides:
      prepareCustomQuery in class ObjectBuildingQuery

    • prepareForExecution

      public void prepareForExecution() throws QueryException
      INTERNAL: Prepare the receiver for execution in a session.
      Overrides:
      prepareForExecution in class ReadQuery
      Throws:
      QueryException

    • prepareSelectAllRows

      protected void prepareSelectAllRows()
      INTERNAL: Prepare the mechanism.

    • registerResultInUnitOfWork

      public Object registerResultInUnitOfWork(Object result, UnitOfWorkImpl unitOfWork, AbstractRecord arguments, boolean buildDirectlyFromRows)
      INTERNAL: All objects queried via a UnitOfWork get registered here. If the query went to the database.

      Involves registering the query result individually and in totality, and hence refreshing / conforming is done here.

      Specified by:
      registerResultInUnitOfWork in class ObjectLevelReadQuery
      Parameters:
      result - may be collection (read all) or an object (read one), or even a cursor. If in transaction the shared cache will be bypassed, meaning the result may not be originals from the parent but raw database rows.
      unitOfWork - the unitOfWork the result is being registered in.
      arguments - the original arguments/parameters passed to the query execution. Used by conforming
      buildDirectlyFromRows - If in transaction must construct a registered result from raw database rows.
      Returns:
      the final (conformed, refreshed, wrapped) UnitOfWork query result

    • registerResultSetInUnitOfWork

      public Object registerResultSetInUnitOfWork(ResultSet resultSet, Vector fields, DatabaseField[] fieldsArray, UnitOfWorkImpl unitOfWork, AbstractRecord arguments) throws SQLException
      INTERNAL: Version of the previous method for ResultSet optimization.
      Returns:
      the final (conformed, refreshed, wrapped) UnitOfWork query result
      Throws:
      SQLException

    • remoteExecute

      public Object remoteExecute()
      INTERNAL: Execute the query through remote session.
      Overrides:
      remoteExecute in class DatabaseQuery

    • replaceValueHoldersIn

      public Map replaceValueHoldersIn(Object object, RemoteSessionController controller)
      INTERNAL: replace the value holders in the specified result object(s)
      Overrides:
      replaceValueHoldersIn in class DatabaseQuery

    • setContainerPolicy

      public void setContainerPolicy(ContainerPolicy containerPolicy)
      PUBLIC: Set the container policy. Used to support different containers (e.g. Collections, Maps).

    • setHierarchicalQueryClause

      public void setHierarchicalQueryClause(Expression startWith, Expression connectBy, List<Expression> orderSiblingsExpressions)
      PUBLIC: Set the Hierarchical Query Clause for the query

      Example:

      Expression startWith = builder.get("id").equal(Integer.valueOf(100)); //can be any expression which identifies a set of employees

      Expression connectBy = builder.get("managedEmployees"); //indicated the relationship that the hierarchy is based on, must be self-referential

      Vector orderBy = new Vector();

      orderBy.addElement(builder.get("startDate"));

      readAllQuery.setHierarchicalQueryClause(startWith, connectBy, orderBy);

      This query would generate SQL like this:

      SELECT * FROM EMPLOYEE START WITH ID=100 CONNECT BY PRIOR ID = MANAGER_ID ORDER SIBLINGS BY START_DATE

      Parameters:
      startWith - Describes the START WITH clause of the query - null if not needed
      connectBy - This should be a query key expression which indicates an attribute who's mapping describes the hierarchy
      orderSiblingsExpressions - Contains expressions which indicate fields to be included in the ORDER SIBLINGS BY clause - null if not required

    • setHierarchicalQueryClause

      public void setHierarchicalQueryClause(Expression startWith, Expression connectBy, List<Expression> orderSiblingsExpressions, ReadAllQuery.Direction direction)
      PUBLIC: Set the Hierarchical Query Clause for the query, specifying the hierarchy traversal direction

      Example:

      Expression startWith = builder.get("id").equal(Integer.valueOf(100)); //can be any expression which identifies a set of employees
      Expression connectBy = builder.get("managedEmployees"); //indicated the relationship that the hierarchy is based on, must be self-referential
      Vector orderBy = new Vector();
      orderBy.addElement(builder.get("startDate"));
      readAllQuery.setHierarchicalQueryClause(startWith, connectBy, orderBy, Direction.CHILD_TO_PARENT);

      This query would generate SQL like this:

      SELECT * FROM EMPLOYEE START WITH ID=100 CONNECT BY ID = PRIOR MANAGER_ID ORDER SIBLINGS BY START_DATE

      Parameters:
      startWith - Describes the START WITH clause of the query - null if not needed
      connectBy - This should be a query key expression which indicates an attribute who's mapping describes the hierarchy
      orderSiblingsExpressions - Contains expressions which indicate fields to be included in the ORDER SIBLINGS BY clause - null if not required
      direction - The direction in which the hierarchy is traversed; if not specified, CHILD_TO_PARENT is used for OneToOne relationships and PARENT_TO_CHILD is used for collections

    • useCollectionClass

      public void useCollectionClass(Class<?> concreteClass)
      PUBLIC: Configure the mapping to use an instance of the specified container class to hold the target objects.

      jdk1.2.x: The container class must implement (directly or indirectly) the Collection interface.

      jdk1.1.x: The container class must be a subclass of Vector.

    • useCursoredStream

      public void useCursoredStream()
      PUBLIC: Use a CursoredStream as the result collection. The initial read size is 10 and page size is 5.

    • useCursoredStream

      public void useCursoredStream(int initialReadSize, int pageSize)
      PUBLIC: Use a CursoredStream as the result collection.
      Parameters:
      initialReadSize - the initial number of objects to read
      pageSize - the number of objects to read when more objects are needed from the database

    • useCursoredStream

      public void useCursoredStream(int initialReadSize, int pageSize, ValueReadQuery sizeQuery)
      PUBLIC: Use a CursoredStream as the result collection.
      Parameters:
      initialReadSize - the initial number of objects to read
      pageSize - the number of objects to read when more objects are needed from the database
      sizeQuery - a query that will return the size of the result set; this must be set if an expression is not used (i.e. custom SQL)

    • useMapClass

      public void useMapClass(Class<?> concreteClass, String methodName)
      PUBLIC: Configure the query to use an instance of the specified container class to hold the result objects. The key used to index the value in the Map is the value returned by a call to the specified zero-argument method. The method must be implemented by the class (or a superclass) of the value to be inserted into the Map.

      jdk1.2.x: The container class must implement (directly or indirectly) the Map interface.

      jdk1.1.x: The container class must be a subclass of Hashtable.

      The referenceClass must set before calling this method.

    • useScrollableCursor

      public void useScrollableCursor()
      PUBLIC: Use a ScrollableCursor as the result collection.

    • useScrollableCursor

      public void useScrollableCursor(int pageSize)
      PUBLIC: Use a ScrollableCursor as the result collection.
      Parameters:
      pageSize - the number of elements to be read into a the cursor when more elements are needed from the database.

    • useScrollableCursor

      public void useScrollableCursor(ScrollableCursorPolicy policy)
      PUBLIC: Use a ScrollableCursor as the result collection.
      Parameters:
      policy - the scrollable cursor policy allows for additional result set options. Example:

      ScrollableCursorPolicy policy = new ScrollableCursorPolicy()

      policy.setResultSetType(ScrollableCursorPolicy.TYPE_SCROLL_INSENSITIVE);

      query.useScrollableCursor(policy);

    • supportsResultSetAccessOptimizationOnPrepare

      public boolean supportsResultSetAccessOptimizationOnPrepare()
      INTERNAL: Indicates whether the query can use ResultSet optimization. The method is called when the query is prepared, so it should refer only to the attributes that cannot be altered without re-preparing the query. If the query is a clone and the original has been already prepared this method will be called to set a (transient and therefore set to null) usesResultSetOptimization attribute.
      Overrides:
      supportsResultSetAccessOptimizationOnPrepare in class ObjectLevelReadQuery

    • supportsResultSetAccessOptimizationOnExecute

      public boolean supportsResultSetAccessOptimizationOnExecute()
      INTERNAL: Indicates whether the query can use ResultSet optimization. Note that the session must be already set. The method is called when the query is executed, so it should refer only to the attributes that can be altered without re-preparing the query.
      Overrides:
      supportsResultSetAccessOptimizationOnExecute in class ObjectLevelReadQuery