Class EntityQuery


  • public class EntityQuery
    extends java.lang.Object
    Used to setup various options for and subsequently execute entity queries. All methods to set options modify the EntityQuery instance then return this modified object to allow method call chaining. It is important to note that this object is not immutable and is modified internally, and returning EntityQuery is just a self reference for convenience. After a query the object can be further modified and then used to perform another query if desired.
    • Constructor Summary

      Constructors 
      Constructor Description
      EntityQuery​(Delegator delegator)
      Construct an EntityQuery object for use against the specified Delegator
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      EntityQuery cache()
      Specifies whether results should be read from the cache (or written to the cache if the results have not yet been cached)
      EntityQuery cache​(boolean useCache)
      Specifies whether results should be read from the cache (or written to the cache if the results have not yet been cached)
      EntityQuery cursorForwardOnly()
      Indicate that the ResultSet object's cursor may move only forward (this is the default behavior)
      EntityQuery cursorScrollInsensitive()
      Indicate that the ResultSet object's cursor is scrollable but generally not sensitive to changes to the data that underlies the ResultSet.
      EntityQuery cursorScrollSensitive()
      Indicate that the ResultSet object's cursor is scrollable but generally sensitive to changes to the data that underlies the ResultSet.
      EntityQuery distinct()
      Specifies that the values returned should be filtered to remove duplicate values.
      EntityQuery distinct​(boolean distinct)
      Specifies whether the values returned should be filtered to remove duplicate values.
      EntityQuery fetchSize​(int fetchSize)
      Specifies the fetch size for this query.
      EntityQuery filterByDate()
      Specifies whether the query should return only values that are currently active using from/thruDate fields.
      EntityQuery filterByDate​(java.lang.String... filterByFieldName)
      Specifies whether the query should return only values that are currently active using the specified from/thru field name pairs.
      EntityQuery filterByDate​(java.sql.Timestamp moment)
      Specifies whether the query should return only values that are active during the specified moment using from/thruDate fields.
      EntityQuery filterByDate​(java.sql.Timestamp moment, java.lang.String... filterByFieldName)
      Specifies whether the query should return only values that are active during the specified moment using the specified from/thru field name pairs.
      EntityQuery filterByDate​(java.util.Date moment)
      Specifies whether the query should return only values that are active during the specified moment using from/thruDate fields.
      EntityQuery from​(java.lang.String entityName)
      Set the entity to query against
      EntityQuery from​(DynamicViewEntity dynamicViewEntity)
      Set the entity to query against
      <T> java.util.List<T> getFieldList​(java.lang.String fieldName)
      Gets a list of values (no matter which type) for a specified entity field name.
      java.lang.Integer getLimit()
      Gets limit.
      java.lang.Integer getOffset()
      Gets offset.
      EntityQuery having​(EntityCondition entityCondition)
      Set the EntityCondition to be used as the HAVING clause for the query.
      EntityQuery limit​(int limit)
      Limit entity query.
      EntityQuery maxRows​(int maxRows)
      Specifies the max number of rows to return, 0 means all rows.
      EntityQuery offset​(int offset)
      Offset entity query.
      EntityQuery orderBy​(java.lang.String... fields)
      The fields of the named entity to order the resultset by; optionally add a " ASC" for ascending or " DESC" for descending NOTE: Each successive call to any of the orderBy(...) methods will replace the currently set orderBy fields for the query.
      EntityQuery orderBy​(java.util.List<java.lang.String> orderBy)
      The fields of the named entity to order the resultset by; optionally add a " ASC" for ascending or " DESC" for descending NOTE: Each successive call to any of the orderBy(...) methods will replace the currently set orderBy fields for the query.
      EntityBatchIterator queryBatchIterator()
      query batch iterator
      long queryCount()
      Executes the EntityQuery and returns the result count If the query generates more than a single result then an exception is thrown
      GenericValue queryFirst()
      Executes the EntityQuery and returns the first result
      EntityListIterator queryIterator()
      Executes the EntityQuery and returns an EntityListIterator representing the result of the query.
      java.util.List<GenericValue> queryList()
      Executes the EntityQuery and returns a list of results
      GenericValue queryOne()
      Executes the EntityQuery and a single result record
      PagedList<GenericValue> queryPagedList​(int viewIndex, int viewSize)  
      EntityQuery select​(java.lang.String... fields)
      Set the fields to be returned when the query is executed.
      EntityQuery select​(java.util.Set<java.lang.String> fieldsToSelect)
      Set the fields to be returned when the query is executed.
      static EntityQuery use​(Delegator delegator)
      Construct an EntityQuery object for use against the specified Delegator
      EntityQuery where​(java.lang.Object... fields)
      Set a series of field name/values to be ANDed together as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
      <T extends EntityCondition>
      EntityQuery
      where​(java.util.List<T> andConditions)
      Set a list of EntityCondition objects to be ANDed together as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
      EntityQuery where​(java.util.Map<java.lang.String,​java.lang.Object> fieldMap)
      Set a Map of field name/values to be ANDed together as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
      EntityQuery where​(EntityCondition entityCondition)
      Set the EntityCondition to be used as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
      EntityQuery where​(EntityCondition... entityCondition)
      Set a series of EntityConditions to be ANDed together as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • EntityQuery

        public EntityQuery​(Delegator delegator)
        Construct an EntityQuery object for use against the specified Delegator
        Parameters:
        delegator - The delegator instance to use for the query
    • Method Detail

      • use

        public static EntityQuery use​(Delegator delegator)
        Construct an EntityQuery object for use against the specified Delegator
        Parameters:
        delegator - The delegator instance to use for the query
      • select

        public EntityQuery select​(java.util.Set<java.lang.String> fieldsToSelect)
        Set the fields to be returned when the query is executed. Note that the select methods are not additive, if a subsequent call is made to select then the existing fields for selection will be replaced.
        Parameters:
        fieldsToSelect - - A Set of Strings containing the field names to be selected
        Returns:
        this EntityQuery object, to enable chaining
      • select

        public EntityQuery select​(java.lang.String... fields)
        Set the fields to be returned when the query is executed. Note that the select methods are not additive, if a subsequent call is made to select then the existing fields for selection will be replaced.
        Parameters:
        fields - - Strings containing the field names to be selected
        Returns:
        this EntityQuery object, to enable chaining
      • from

        public EntityQuery from​(java.lang.String entityName)
        Set the entity to query against
        Parameters:
        entityName - - The name of the entity to query against
        Returns:
        this EntityQuery object, to enable chaining
      • from

        public EntityQuery from​(DynamicViewEntity dynamicViewEntity)
        Set the entity to query against
        Parameters:
        dynamicViewEntity - - The DynamicViewEntity object to query against
        Returns:
        this EntityQuery object, to enable chaining
      • where

        public EntityQuery where​(EntityCondition entityCondition)
        Set the EntityCondition to be used as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
        Parameters:
        entityCondition - - An EntityCondition object to be used as the where clause for this query
        Returns:
        this EntityQuery object, to enable chaining
      • where

        public EntityQuery where​(java.util.Map<java.lang.String,​java.lang.Object> fieldMap)
        Set a Map of field name/values to be ANDed together as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
        Parameters:
        fieldMap - - A Map of field names/values to be ANDed together as the where clause for the query
        Returns:
        this EntityQuery object, to enable chaining
      • where

        public EntityQuery where​(java.lang.Object... fields)
        Set a series of field name/values to be ANDed together as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
        Parameters:
        fields - - A series of field names/values to be ANDed together as the where clause for the query
        Returns:
        this EntityQuery object, to enable chaining
      • where

        public EntityQuery where​(EntityCondition... entityCondition)
        Set a series of EntityConditions to be ANDed together as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
        Parameters:
        entityCondition - - A series of EntityConditions to be ANDed together as the where clause for the query
        Returns:
        this EntityQuery object, to enable chaining
      • where

        public <T extends EntityConditionEntityQuery where​(java.util.List<T> andConditions)
        Set a list of EntityCondition objects to be ANDed together as the WHERE clause for the query NOTE: Each successive call to any of the where(...) methods will replace the currently set condition for the query.
        Parameters:
        andConditions - - A list of EntityCondition objects to be ANDed together as the WHERE clause for the query
        Returns:
        this EntityQuery object, to enable chaining
      • having

        public EntityQuery having​(EntityCondition entityCondition)
        Set the EntityCondition to be used as the HAVING clause for the query. NOTE: Each successive call to any of the having(...) methods will replace the currently set condition for the query.
        Parameters:
        entityCondition - - The EntityCondition object that specifies how to constrain this query after any groupings are done (if this is a view entity with group-by aliases)
        Returns:
        this EntityQuery object, to enable chaining
      • orderBy

        public EntityQuery orderBy​(java.util.List<java.lang.String> orderBy)
        The fields of the named entity to order the resultset by; optionally add a " ASC" for ascending or " DESC" for descending NOTE: Each successive call to any of the orderBy(...) methods will replace the currently set orderBy fields for the query.
        Parameters:
        orderBy - - The fields of the named entity to order the resultset by
        Returns:
        this EntityQuery object, to enable chaining
      • orderBy

        public EntityQuery orderBy​(java.lang.String... fields)
        The fields of the named entity to order the resultset by; optionally add a " ASC" for ascending or " DESC" for descending NOTE: Each successive call to any of the orderBy(...) methods will replace the currently set orderBy fields for the query.
        Parameters:
        fields - - The fields of the named entity to order the resultset by
        Returns:
        this EntityQuery object, to enable chaining
      • cursorForwardOnly

        public EntityQuery cursorForwardOnly()
        Indicate that the ResultSet object's cursor may move only forward (this is the default behavior)
        Returns:
        this EntityQuery object, to enable chaining
      • cursorScrollSensitive

        public EntityQuery cursorScrollSensitive()
        Indicate that the ResultSet object's cursor is scrollable but generally sensitive to changes to the data that underlies the ResultSet.
        Returns:
        this EntityQuery object, to enable chaining
      • cursorScrollInsensitive

        public EntityQuery cursorScrollInsensitive()
        Indicate that the ResultSet object's cursor is scrollable but generally not sensitive to changes to the data that underlies the ResultSet.
        Returns:
        this EntityQuery object, to enable chaining
      • fetchSize

        public EntityQuery fetchSize​(int fetchSize)
        Specifies the fetch size for this query. -1 will fall back to datasource settings.
        Parameters:
        fetchSize - - The fetch size for this query
        Returns:
        this EntityQuery object, to enable chaining
      • maxRows

        public EntityQuery maxRows​(int maxRows)
        Specifies the max number of rows to return, 0 means all rows.
        Parameters:
        maxRows - - the max number of rows to return
        Returns:
        this EntityQuery object, to enable chaining
      • offset

        public EntityQuery offset​(int offset)
        Offset entity query.
        Parameters:
        offset - the offset
        Returns:
        the entity query
      • getOffset

        public java.lang.Integer getOffset()
        Gets offset.
        Returns:
        the offset
      • limit

        public EntityQuery limit​(int limit)
        Limit entity query.
        Parameters:
        limit - the limit
        Returns:
        the entity query
      • getLimit

        public java.lang.Integer getLimit()
        Gets limit.
        Returns:
        the limit
      • distinct

        public EntityQuery distinct()
        Specifies that the values returned should be filtered to remove duplicate values.
        Returns:
        this EntityQuery object, to enable chaining
      • distinct

        public EntityQuery distinct​(boolean distinct)
        Specifies whether the values returned should be filtered to remove duplicate values.
        Parameters:
        distinct - - boolean indicating whether the values returned should be filtered to remove duplicate values
        Returns:
        this EntityQuery object, to enable chaining
      • cache

        public EntityQuery cache()
        Specifies whether results should be read from the cache (or written to the cache if the results have not yet been cached)
        Returns:
        this EntityQuery object, to enable chaining
      • cache

        public EntityQuery cache​(boolean useCache)
        Specifies whether results should be read from the cache (or written to the cache if the results have not yet been cached)
        Parameters:
        useCache - - boolean to indicate if the cache should be used or not
        Returns:
        this EntityQuery object, to enable chaining
      • filterByDate

        public EntityQuery filterByDate()
        Specifies whether the query should return only values that are currently active using from/thruDate fields.
        Returns:
        this EntityQuery object, to enable chaining
      • filterByDate

        public EntityQuery filterByDate​(java.sql.Timestamp moment)
        Specifies whether the query should return only values that are active during the specified moment using from/thruDate fields.
        Parameters:
        moment - - Timestamp representing the moment in time that the values should be active during
        Returns:
        this EntityQuery object, to enable chaining
      • filterByDate

        public EntityQuery filterByDate​(java.util.Date moment)
        Specifies whether the query should return only values that are active during the specified moment using from/thruDate fields.
        Parameters:
        moment - - Date representing the moment in time that the values should be active during
        Returns:
        this EntityQuery object, to enable chaining
      • filterByDate

        public EntityQuery filterByDate​(java.lang.String... filterByFieldName)
        Specifies whether the query should return only values that are currently active using the specified from/thru field name pairs.
        Parameters:
        filterByFieldName - - String pairs representing the from/thru date field names e.g. "fromDate", "thruDate", "contactFromDate", "contactThruDate"
        Returns:
        this EntityQuery object, to enable chaining
      • filterByDate

        public EntityQuery filterByDate​(java.sql.Timestamp moment,
                                        java.lang.String... filterByFieldName)
        Specifies whether the query should return only values that are active during the specified moment using the specified from/thru field name pairs.
        Parameters:
        moment - - Timestamp representing the moment in time that the values should be active during
        filterByFieldName - - String pairs representing the from/thru date field names e.g. "fromDate", "thruDate", "contactFromDate", "contactThruDate"
        Returns:
        this EntityQuery object, to enable chaining
      • queryIterator

        public EntityListIterator queryIterator()
                                         throws GenericEntityException
        Executes the EntityQuery and returns an EntityListIterator representing the result of the query. NOTE: THAT THIS MUST BE CLOSED (preferably in a finally block) WHEN YOU ARE DONE WITH IT, AND DON'T LEAVE IT OPEN TOO LONG BEACUSE IT WILL MAINTAIN A DATABASE CONNECTION.
        Returns:
        Returns an EntityListIterator representing the result of the query
        Throws:
        GenericEntityException
      • queryCount

        public long queryCount()
                        throws GenericEntityException
        Executes the EntityQuery and returns the result count If the query generates more than a single result then an exception is thrown
        Returns:
        GenericValue representing the only result record from the query
        Throws:
        GenericEntityException
      • getFieldList

        public <T> java.util.List<T> getFieldList​(java.lang.String fieldName)
                                           throws GenericEntityException
        Gets a list of values (no matter which type) for a specified entity field name.

        The field of the entity is first selected and the cache usage turned off to ensure no values are missing.

        Type Parameters:
        T -
        Parameters:
        fieldName -
        Returns:
        list with field values
        Throws:
        GenericEntityException