ERXQuery (Project Wonder Reference Documentation)

java.lang.Object
- er.extensions.eof.ERXQuery

```
public class ERXQuery
extends Object
```
ERXQuery

Overview
This class has a fluent API that mimics a select statement:
```
 
 NSArray<NSDictionary<String,Object>> records =
     ERXQuery.create()
         .select(keys)
         .from(entity)
         .where(qualifier)
         .groupBy(groupings)
         .having(havingQualifier)
         .orderBy(sortings)
         .fetch();
 
 
```
It allows you to use EOF/Wonder higher-level constructs (qualifiers, attributes, orderings, key paths, ERXKeys, etc.) to create a query that looks like this:
```
 SELECT ...
 FROM ...
 WHERE ...
 GROUP BY ...
 HAVING ...
 ORDER BY ...
 
```
Specifying the Attributes to Fetch
The select() method is very flexible and powerful. It accepts a variable number of objects of different types that specify the attributes to fetch. These objects can be EOAttributes, ERXKeys, Strings. You may also specify any Iterable such as NSArray, List, Collection, etc. containing any combination of these (EOAttributes, ERXKeys, Strings).
The ERXKeys and String objects correspond to keys and key paths to the attributes to fetch, i.e. "customer.name". The keys and key paths can also be relationships to objects, i.e. "customer" which translate into a fetch of foreign keys used to build object faults and return them in the results.
You may call the select() method multiple times to keep adding to the list of attributes to fetch.
Using Ad Hoc Attributes
It is very common to aggregate attributes in these queries. For this purpose, you may want to create what ERXQuery refers to as ad hoc attributes. These attributes have a definition but are not physically attached to the entity. You can use the ERXQueryAttributes class to easily create multiple ad hoc attributes. The definition of the attribute can reference relationships and attributes as shown below. If you just want to create a single ad hoc attribute you may use the ERXQueryEOAttribute class.
```
 
 // Using a single query against the order entity to count the number of
 // orders and line items that match an order qualifier.
 
 ERXQueryAttributes attributes = ERXQueryAttributes.create(orderEntity)
     .add("itemCount", "COUNT(DISTINCT lineItems.lineItemID)", "intNumber")
     .add("orderCount", "COUNT(DISTINCT orderID)", "intNumber");
 
 ERXQuery query =
     ERXQuery.create()
         .select(attributes)
         .from(orderEntity)
         .where(qualifier);
 
 // Fetch into a dictionary
 NSDictionary<String,Object> row = query.fetch().lastObject();
 
 int orderCount = ((Number) row.objectForKey("orderCount")).intValue();
 int itemCount = ((Number) row.objectForKey("itemCount")).intValue();
 
 
```
Fetching Results into a Custom Class
It is useful to fetch results into objects of a custom class. This allows you to have type checking on the getter methods and add methods for computed values on the data fetched. For the example above you could have fetched the results into a custom class as follows:
```
 
 // Fetch into object instances of the a custom Result class
 Result result = query.fetch(editingContext, Result.class).lastObject();
 int orderCount = result.orderCount();
 int itemCount = result.itemCount();
 
 
```
The Result custom class would have to be defined as shown below. The constructor may keep the mutable dictionary passed in to the constructor or make an immutable copy from it as shown below.
```
 public static class Result {
      NSDictionary<String,Object> data;
     
     public Result(EOEditingContext ec,  NSMutableDictionary<String,Object> row) {
         data = row.immutableClone();
     }
     
     public int itemCount() {
         return ((Number) data.objectForKey("itemCount")).intValue();
     }
     public int orderCount() {
         return ((Number) data.objectForKey("orderCount")).intValue();
     }
 }
 
```
In general, fetching into a custom class can be done in several ways:
```
 // If your custom class has a constructor that takes an editing context and
 // a mutable dictionary then it is very simple:
  NSArray<Foo> objs = query.fetch(editingContext, Foo.class);
 
 // Using java 8 or later you may use a lambda expression:
  NSArray<Foo> objs = query.fetch(editingContext, (ec, row) -> new Foo(ec, row));
 
 // You may also create an implementation of the RecordConstructor
 // functional interface and pass it into the fetch method:
  ERXQuery.RecordConstructor<Foo> recordConstructor =
     new  ERXQuery.RecordConstructor<Foo> {
          @Override
         public Foo constructRecord(EOEditingContext ec,  NSMutableDictionary<String,Object> row) {
             return new Foo(ec, row);
         }
     };
 NSArray objs = query.fetch(editingContext, recordConstructor);
 
```
Augmenting Row Values
You can have entries from a dictionary added in to the rows fetched from the database. The mutable dictionary passed in to the record constructor will contain the data fetched along with the keys/values from this recordInitializationValues dictionary.
```
 
 NSDictionary<String,Object> recordInitializationValues = new NSDictionary<>((Object)2017, "preferredYear");
 NSArray<Foo> objs = query.fetch(editingContext, recordInitializationValues, Foo.class);
 Foo aFoo = objs.lastObject();
 int preferredYear = aFoo.preferredYear(); // i.e. 2017
 
 
```
Defining Ad Hoc Attributes in the Entity
An alternate way to define your ad hoc attributes is to define them in your entity and flagging them as non-class properties. Unlike ERXQueryEOAttribute objects, these attributes will be instances of EOAttribute and reside in your entity. They may be a bit distracting when looking at the entity if you have a lot but this method allows you to reuse all the existing attributes and relationships already defined in the entity and does not require code for creating the attributes.
One incovenience is that eogeneration templates do not generate ERXKeys for non-class properties. However, this problem could be overcome by enhancing the eogeneration templates to generate ERXKeys for derived non-class property attributes.
```
 // Fetch last year's customer order totals exceeding $1000 in descending order
  NSArray<OrderSummary> lastYearTopSales =
     ERXQuery.create()
         .select(Order.CUSTOMER)             // customer to-one
         .select(Order.SUM_TOTAL_AMOUNT)     // non-class property defined as SUM(totalAmount)
         .from(Order.ENTITY_NAME)
         .where(lastYearQualifier)
         .groupBy(Order.CUSTOMER)
         .having(Order.SUM_TOTAL_AMOUNT.greaterThan(1000.00))
         .orderBy(Order.SUM_TOTAL_AMOUNT.desc())
         .fetch(editingContext, OrderSummary.class);
 
 // Peek at top sale record
 OrderSummary topSale = ERXArrayUtilities.firstObject(lastYearTopSales);
 if (topSale != null) {
     System.out.println("Customer " + topSale.customer().fullName() 
         + " ordered " + moneyFormatter.format(topSale.sumTotalAmount()));
 }
 
```
It would be nice to enhance the eogeneration templates to also create a custom class for fetching the results, i.e. WonderEntitySummary.java and _WonderEntitySummary.java with the getters for attributes/relationships in the entity including derived non-class properties. These templates would be used when the entity has a user info key with ERXQuery.enabled=yes.
Limitations
Ad hoc attributes created with ERXQueryAttributes or ERXQueryEOAttribute are not physically attached to an entity. When EOF generates SQL for a qualifier it calls sqlStringForSQLExpression(q,e) where q is an EOQualifier and e is an EOSQLExpression. Qualifiers then try to reach the attribute by following the qualifier's referenced keys starting with the entity of the EOSQLExpression, i.e. e.entity().
The current workaround used by ERXQuery is to temporarily add to the entity any ad hoc attributes referenced by the qualifiers. This typically happens with the havingQualifier which normally references the ad hoc attributes corresponding to aggregated attributes. For example, "sumTotalAmount" defined as "SUM(totalAmount)" could be used in a having qualifier:
```
 
 // When grouping orders by customer and fetching sumTotalAmount we may want to have
 // this having qualifier so that we only fetch the groups totaling more than 1000.
 EOQualifier havingQualifier = ERXQ.greaterThan("sumTotalAmount", new BigDecimal(1000.0));
 
 
```
However, if you were to define your "sumTotalAmount" attribute in your entity as a derived non-class property with definition "SUM(totalAmount)" then ERXQuery doesn't have to add the attribute to the entity.
Defaults for Behavior Properties
1. er.extensions.eof.ERXQuery.useBindVariables=false
2. er.extensions.eof.ERXQuery.useEntityRestrictingQualifiers=true
3. er.extensions.eof.ERXQuery.removeForeignKeysFromRowValues=true
Author:

Ricardo J. Parada

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ERXQuery.DefaultRecordConstructor` This is the default constructor used by the fetch() and fetch(EOEditingContext) methods.
`static class`	`ERXQuery.EntityModificationAction`
`static class`	`ERXQuery.Record` Convenience class for fetching data into records conforming to key value coding.
`static interface`	`ERXQuery.RecordConstructor<T>` Functional interface for constructing a record from a dictionary with the data fetched from the database.

Field Summary

Fields
Modifier and Type	Field and Description
`protected NSMutableArray<EOAttribute>`	`adHocAttributes`
`protected NSMutableArray<EOAttribute>`	`adHocGroupings`
`protected NSMutableDictionary<String,EOAttribute>`	`attributesByName`
`protected int`	`clientFetchLimit`
`protected EOEditingContext`	`editingContext`
`protected NSMutableArray<String>`	`fetchKeys`
`protected NSMutableArray<EOAttribute>`	`groupingAttributes`
`protected NSMutableArray<String>`	`groupingKeys`
`protected EOQualifier`	`havingQualifier`
`protected boolean`	`isCountingStatement`
`protected EOEntity`	`mainEntity`
`protected EOQualifier`	`mainSelectQualifier`
`protected NSMutableArray<EOSortOrdering>`	`orderings`
`protected double`	`queryEvaluationTime`
`protected String`	`queryHint`
`protected boolean`	`refreshRefetchedObjects`
`protected NSMutableDictionary<String,String>`	`relationshipAliases`
`protected NSMutableSet<er.extensions.eof.ERXQuery.RelationshipKeyInfo>`	`relationshipKeysSet`
`protected NSMutableArray<EOAttribute>`	`selectAttributes`
`protected int`	`serverFetchLimit`
`protected boolean`	`useBindVariables`
`protected boolean`	`usesDistinct`

Constructor Summary

Constructors
Modifier Constructor and Description

protected ERXQuery()

Constructors
Modifier	Constructor and Description
`protected`	`ERXQuery()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected String`	`addLimitClause(EOEntity entity, String statement, int limit)` Turns the SQL statement into something like this:
`ERXQuery`	`clientFetchLimit(int limit)` If specified then the fetch will be stopped/canceled after fetching clientFetchLimit records.
`protected void`	`computeSelectAndGroupingAttributes()`
`static ERXQuery`	`create()`
`protected String`	`databaseProductName(EOEntity entity)`
`static EOEntity`	`destinationEntity(EOEntity rootEntity, String keyPath)` Returns the destination entity for this report attribute.
`static EOProperty`	`destinationProperty(EOEntity rootEntity, String keyPath)` Returns whether the property (either EOAttribute or EORelationship) referenced by the last component in the key path.
`protected EOAttribute`	`existingOrNewAttributeForKey(String keyPath)` Called by getExpression() to get the attribute or create an ad-hoc attribute for a key.
`NSArray<NSDictionary<String,Object>>`	`fetch()` Does the fetch and returns the values.
`NSArray<NSDictionary<String,Object>>`	`fetch(EOEditingContext ec)` Does the fetch and returns the values.
`<T> NSArray<T>`	`fetch(EOEditingContext ec, Class<T> recordClass)` Returns fetch(ec, recordClass, NSDictionary.emptyDictionary())
`<T> NSArray<T>`	`fetch(EOEditingContext ec, ERXQuery.RecordConstructor<T> recordConstructor)` Convenience method to return fetch(ec, NSDictionary.emptyDictionary(), recordConstructor)
`NSArray<NSDictionary<String,Object>>`	`fetch(EOEditingContext ec, NSDictionary<String,Object> recordInitializationValues)`
`<T> NSArray<T>`	`fetch(EOEditingContext anEC, NSDictionary<String,Object> recordInitializationValues, Class<T> recordClass)` Use this method to fetch results into objects of the specified class.
`<T> NSArray<T>`	`fetch(EOEditingContext ec, NSDictionary<String,Object> recordInitializationValues, ERXQuery.RecordConstructor<T> recordConstructor)` Use this method to fetch either by using an implementation of the RecordConstructor functional interface or by using a lambda expression as follows:
`protected <T> NSArray<T>`	`fetch(EOSQLExpression expression, NSArray<EOAttribute> fetchAttributes, EOEditingContext ec, NSDictionary<String,Object> initValues, ERXQuery.RecordConstructor<T> recordConstructor)` Core fetch method.
`Object`	`fetchValue()` Convenience method for fetching a single attribute from a query resulting in zero or one record.
`protected String`	`formattedTimestampForInlineUse(EOSQLExpression sqlExpression, Date timestamp, EOAttribute attribute)`
`protected String`	`formatValueForAttributeForInlineUse(EOSQLExpression sqlExpression, Object value, EOAttribute attribute)` Formats the value for inline use.
`ERXQuery`	`from(EOEntity entity)` Specifies the EOEntity object to select from.
`ERXQuery`	`from(String entityName)` Specifies the name of EOEntity object to select from.
`EOSQLExpression`	`getExpression(EOEditingContext ec)` Returns a complete select expression as follows:
`ERXQuery`	`groupBy(Object... attributesOrKeys)` Use this to specify the attributes to group by.
`ERXQuery`	`having(EOQualifier qual)` Specifies the qualifier for the having clause.
`ERXQuery`	`orderBy(Object... orderingObjects)` Specifies the sort orderings used to build the order by clause.
`double`	`queryEvaluationTime()`
`ERXQuery`	`refreshingRefetchedObjects()` Specifies whether to refresh refetched objects referenced by relationship keys, i.e.
`protected EOQualifier`	`restrictingQualifierForReferencedEntities()` Returns a qualifier by combining the restricting qualifiers (if any) in the entities referenced.
`ERXQuery`	`select(Object... attributesOrKeys)` Specifies the attributes to fetch.
`NSArray<EOAttribute>`	`selectAttributes()` Returns the array containing the EOAttributes that ERXQuery used to fetch the results.
`ERXQuery`	`selectCount()` Specifies whether to select count(*)
`ERXQuery`	`serverFetchLimit(int limit)` If specified then the query will be wrapped with something like this, depending on the database product:
`protected static void`	`setupAdaptorChannelEOAttributes(EOAdaptorChannel adaptorChannel, NSArray<EOAttribute> selectAttributes)`
`protected static EOSQLExpressionFactory`	`sqlExpressionFactory(EOEntity anEntity, EOEditingContext ec)` Returns a new EOSQLExpressionFactory for the entity and editing context specified.
`protected String`	`sqlStringForAttribute(EOSQLExpression e, EOAttribute a)` Returns the SQL string corresponding to attribute a.
`String`	`sqlStringForAttributeValue(EOSQLExpression e, EOAttribute att, Object value)` Uses the EOSQLExpression provided to get the SQL string for value and corresponding attribute.
`String`	`sqlStringForOrderingAttribute(EOSQLExpression e, EOAttribute orderingAttribute, NSSelector selector)` Returns the SQL string for the ordering of attribute a using the specified selector.
`protected String`	`sqlWithBindingsInline(String sql, EOSQLExpression expression)` Returns the SQL for the EOSQLExpression specified but with the place holder characters (?) replaced with their corresponding value from the bindings and formatted for in-line use.
`protected String`	`sqlWithBindingsInline2(String sql, EOSQLExpression expression)` Returns the SQL for the EOSQLExpression specified but with the place holder characters (?) replaced with their corresponding value from the bindings and formatted for inline use.
`protected RuntimeException`	`unknownPropertyException(String keyPath)`
`ERXQuery`	`usingBindVariables()` Enables use of bind variables.
`ERXQuery`	`usingDistinct()` Specifies whether or not to use DISTINCT.
`ERXQuery`	`usingQueryHint(String value)` This string is inserted after the SELECT keyword in the generated SQL padded with a space on both sides.
`ERXQuery`	`usingRelationshipAlias(String relationshipName, String alias)` Sets the table alias to use for a given relationship name.
`ERXQuery`	`where(EOQualifier qual)` Specifies the main qualifier used to build the where clause.
`protected String`	`wrapped(String leftHandSide, String statement, String rightHandSide)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - editingContext
```
protected EOEditingContext editingContext
```
  - mainEntity
```
protected EOEntity mainEntity
```
  - mainSelectQualifier
```
protected EOQualifier mainSelectQualifier
```
  - havingQualifier
```
protected EOQualifier havingQualifier
```
  - orderings
```
protected NSMutableArray<EOSortOrdering> orderings
```
  - relationshipAliases
```
protected NSMutableDictionary<String,String> relationshipAliases
```
  - usesDistinct
```
protected boolean usesDistinct
```
  - isCountingStatement
```
protected boolean isCountingStatement
```
  - queryHint
```
protected String queryHint
```
  - useBindVariables
```
protected boolean useBindVariables
```
  - fetchKeys
```
protected NSMutableArray<String> fetchKeys
```
  - groupingKeys
```
protected NSMutableArray<String> groupingKeys
```
  - adHocAttributes
```
protected NSMutableArray<EOAttribute> adHocAttributes
```
  - adHocGroupings
```
protected NSMutableArray<EOAttribute> adHocGroupings
```
  - selectAttributes
```
protected NSMutableArray<EOAttribute> selectAttributes
```
  - groupingAttributes
```
protected NSMutableArray<EOAttribute> groupingAttributes
```
  - attributesByName
```
protected NSMutableDictionary<String,EOAttribute> attributesByName
```
  - relationshipKeysSet
```
protected NSMutableSet<er.extensions.eof.ERXQuery.RelationshipKeyInfo> relationshipKeysSet
```
  - refreshRefetchedObjects
```
protected boolean refreshRefetchedObjects
```
  - serverFetchLimit
```
protected int serverFetchLimit
```
  - clientFetchLimit
```
protected int clientFetchLimit
```
  - queryEvaluationTime
```
protected double queryEvaluationTime
```
- Constructor Detail
  - ERXQuery
```
protected ERXQuery()
```
- Method Detail
  - create
```
public static ERXQuery create()
```
  - selectCount
```
public ERXQuery selectCount()
```
    Specifies whether to select count(*)
    
    Returns:
    
    this query
  - select
```
public ERXQuery select(Object... attributesOrKeys)
```
    Specifies the attributes to fetch. The attributes may be specified using EOAttributes, ERXKeys, String objects (for keys and key paths), or Iterable objects such as NSArray, List, Collection containing EOAttributes, ERXKeys, Strings or inclusive other Iterables. The String and ERXKey objects must correspond to the names of the attributes to fetch or to the key paths to leading to the attributes to fetch. You may call the select() method multiple times to keep adding to the list of attributes to fetch.
    
    Parameters:
    
    attributesOrKeys - list of attributes to select in the fetch
    
    Returns:
    
    this query
  - usingDistinct
```
public ERXQuery usingDistinct()
```
    Specifies whether or not to use DISTINCT.
    
    Returns:
    
    this query
  - refreshingRefetchedObjects
```
public ERXQuery refreshingRefetchedObjects()
```
    Specifies whether to refresh refetched objects referenced by relationship keys, i.e. "customer".
    
    Returns:
    
    this query
  - from
```
public ERXQuery from(EOEntity entity)
```
    Specifies the EOEntity object to select from.
    
    Parameters:
    
    entity - the entity to fetch
    
    Returns:
    
    this query
  - from
```
public ERXQuery from(String entityName)
```
    Specifies the name of EOEntity object to select from.
    
    Parameters:
    
    entityName - the entity to fetch
    
    Returns:
    
    this query
  - where
```
public ERXQuery where(EOQualifier qual)
```
    Specifies the main qualifier used to build the where clause.
    
    Parameters:
    
    qual - the qualifier for the fetch
    
    Returns:
    
    this query
  - groupBy
```
public ERXQuery groupBy(Object... attributesOrKeys)
```
    Use this to specify the attributes to group by. The objects can be EOAttributes, ERXKeys, Strings, or any Iterable such as NSArrays, Lists, Collections, etc. containing EOAttributes, ERXKeys, Strings or inclusive other Iterables. The ERXKeys and String objects must correspond to the keys or key paths to the attributes to group by. You may call this method multiple times to keep on adding to the list of attributes to group by.
    
    Parameters:
    
    attributesOrKeys - list of attributes to use for the group by
    
    Returns:
    
    this query
  - orderBy
```
public ERXQuery orderBy(Object... orderingObjects)
```
    Specifies the sort orderings used to build the order by clause. The objects passed in can be EOSortOrderings or Iterables containing EOSortOrderings or other Iterables. You may call this method multiple times to keep adding to the list of orderings.
    
    Parameters:
    
    orderingObjects - sort orders
    
    Returns:
    
    this query
  - having
```
public ERXQuery having(EOQualifier qual)
```
    Specifies the qualifier for the having clause.
    
    Parameters:
    
    qual - qualifier for the having clause
    
    Returns:
    
    this query
  - usingQueryHint
```
public ERXQuery usingQueryHint(String value)
```
    This string is inserted after the SELECT keyword in the generated SQL padded with a space on both sides. This allows you to send a hint to the database server.
    
    Parameters:
    
    value - query hint
    
    Returns:
    
    this query
  - usingBindVariables
```
public ERXQuery usingBindVariables()
```
    Enables use of bind variables. If this is not called then ERXQuery looks at the er.extensions.eof.ERXQuery.useBindVariables property which defaults to false currently, thereby placing values in-line with the SQL generated.
    
    Returns:
    
    this query
  - serverFetchLimit
```
public ERXQuery serverFetchLimit(int limit)
```
    If specified then the query will be wrapped with something like this, depending on the database product:
```
SELECT * FROM ( query ) WHERE ROWNUM <= limit
```
    Parameters:
    
    limit - max number of rows in result
    
    Returns:
    
    this query
  - clientFetchLimit
```
public ERXQuery clientFetchLimit(int limit)
```
    If specified then the fetch will be stopped/canceled after fetching clientFetchLimit records. This does not affect the SQL generated unlike serverFetchLimit.
    
    Parameters:
    
    limit - max number of rows in result
    
    Returns:
    
    this query
  - fetch
```
public NSArray<NSDictionary<String,Object>> fetch()
```
    Does the fetch and returns the values.
    
    Returns:
    
    list of fetched records
  - fetch
```
public NSArray<NSDictionary<String,Object>> fetch(EOEditingContext ec)
```
    Does the fetch and returns the values.
    
    Parameters:
    
    ec - the editing context to use for the fetch
    
    Returns:
    
    list of fetched records
  - fetch
```
public NSArray<NSDictionary<String,Object>> fetch(EOEditingContext ec,
                                                  NSDictionary<String,Object> recordInitializationValues)
```
  - fetch
```
public <T> NSArray<T> fetch(EOEditingContext ec,
                            Class<T> recordClass)
```
    Returns fetch(ec, recordClass, NSDictionary.emptyDictionary())
    
    Parameters:
    
    ec - the editing context to use for the fetch
    
    recordClass - class to use for record entries
    
    Returns:
    
    list of fetched records
  - fetch
```
public <T> NSArray<T> fetch(EOEditingContext anEC,
                            NSDictionary<String,Object> recordInitializationValues,
                            Class<T> recordClass)
```
    Use this method to fetch results into objects of the specified class. The class must have a constructor that takes an EOEditingContext and an NSMutableDictionary as arguments The row passed into the constructor will contain data fetched for the row as well as the entries from recordInitializatonValues dictionary.
    
    Parameters:
    
    anEC - the editing context to use for the fetch
    
    recordInitializationValues - values to add as record entries to result
    
    recordClass - class to use for record entries
    
    Returns:
    
    list of fetched records
  - fetch
```
public <T> NSArray<T> fetch(EOEditingContext ec,
                            NSDictionary<String,Object> recordInitializationValues,
                            ERXQuery.RecordConstructor<T> recordConstructor)
```
    Use this method to fetch either by using an implementation of the RecordConstructor functional interface or by using a lambda expression as follows:
    1. Define your custom record class
```
 public class Foo {
     NSMutableDictionary<String,Object> data;
    
    // Constructor
    public Foo(EOEditingContext ec,  NSMutableDictionary<String,Object> row) {
       data = row;
    }
 }
 
```
    2. Fetch the records
```
 EOEditingContext editingContext = ERXEC.newEditingContext();
 ERXQuery query = ...;
 
 // This assumes Java <= 7
  ERXQuery.RecordConstructor<Foo> recordConstructor =
    new  ERXQuery.RecordConstructor<Foo>(){
    
        @Override
       public Foo constructRecord(EOEditingContext ec,  NSMutableDictionary<String,Object> row) {
          return new Foo(ec, row);
       }
       
    };
 
  NSArray<Foo> foos = query.fetch(editingContext, recordConstructor);
 
 // This assumes Java >= 8
  NSArray<Foo> foos = query.fetch(editingContext, (ec, row) -> new Foo(ec, row));
 
```
    Parameters:
    
    ec - the editing context to use for the fetch
    
    recordInitializationValues - values to add as record entries to result
    
    recordConstructor - constructor for record entries
    
    recordClass - class to use for record entries
    
    Returns:
    
    list of fetched records
  - fetch
```
public <T> NSArray<T> fetch(EOEditingContext ec,
                            ERXQuery.RecordConstructor<T> recordConstructor)
```
    Convenience method to return fetch(ec, NSDictionary.emptyDictionary(), recordConstructor)
    
    Parameters:
    
    ec - the editing context to use for the fetch
    
    recordConstructor - constructor for record entries
    
    Returns:
    
    list of fetched records
  - fetch
```
protected <T> NSArray<T> fetch(EOSQLExpression expression,
                               NSArray<EOAttribute> fetchAttributes,
                               EOEditingContext ec,
                               NSDictionary<String,Object> initValues,
                               ERXQuery.RecordConstructor<T> recordConstructor)
```
    Core fetch method. Given the EOSQLExpression built to fetch the selectAttributes this method fetches the results. As each row result is fetched this method calls the recordConstructor with the editing context and mutable dictionary containing the row values and the entries from the initValues dictionary. The record constructor should return an instance of T. The T instances are then placed into an array that this method returns, i.e. NSArray<T>
    
    Parameters:
    
    expression - the SQL expression for the fetch
    
    fetchAttributes - attributes to fetch
    
    ec - the editing context to use for the fetch
    
    initValues - values to add as record entries to result
    
    recordConstructor - constructor for record entries
    
    Returns:
    
    list of fetched records
  - setupAdaptorChannelEOAttributes
```
protected static void setupAdaptorChannelEOAttributes(EOAdaptorChannel adaptorChannel,
                                                      NSArray<EOAttribute> selectAttributes)
```
  - fetchValue
```
public Object fetchValue()
```
    Convenience method for fetching a single attribute from a query resulting in zero or one record. For example: Number count = (Number) ERXQuery.create().selectCount().from(entity).where(qual).fetchValue();
    
    Returns:
    
    The value or null when the query returns zero records or an NSKeyValueCoding.NullValue.
  - usingRelationshipAlias
```
public ERXQuery usingRelationshipAlias(String relationshipName,
                                       String alias)
```
    Sets the table alias to use for a given relationship name. For example, if the query selects from CLAIM and the main query qualifier joins to other tables including the LINE_ITEM table via the lineItems relationship. If you don't specify a table alias for the lineItems relationship then it would use whatever EOF comes up with, for example T3. If you wanted X1 to be used as the table alias then simply call this method with "lineItems" as the relationship name and "X1" as the table alias.
    
    Parameters:
    
    relationshipName - name of relationship
    
    alias - alias name to use
    
    Returns:
    
    this query
  - getExpression
```
public EOSQLExpression getExpression(EOEditingContext ec)
```
    Returns a complete select expression as follows:
```
      SELECT ...
      FROM ...
      WHERE ...
      GROUP BY ...
      HAVING ...
      ORDER BY ...
 
```
    The WHERE clause is constructed from the qualifier (if any) passed into the where() method and any required joins necessary to access any referenced properties.
    The GROUP BY clause is constructed from the grouping attributes specified by calling any of the groupBy() methods.
    The HAVING clause is constructed if a qualifier is specified by calling the having() method.
    The ORDER BY clause is constructed from attributes passed in to the orderBy() method.
    Parameters:
    
    ec - the editing context to use for SQL construction
    
    Returns:
    
    SQL expression
  - addLimitClause
```
protected String addLimitClause(EOEntity entity,
                                String statement,
                                int limit)
```
    Turns the SQL statement into something like this:
```
"SELECT * FROM ( " + statement + " ) WHERE ROWNUM <= " + limit;
```
    Parameters:
    
    entity - entity on which to fetch
    
    statement - SQL statement
    
    limit - max number of rows in result
    
    Returns:
    
    SQL string
  - wrapped
```
protected String wrapped(String leftHandSide,
                         String statement,
                         String rightHandSide)
```
  - selectAttributes
```
public NSArray<EOAttribute> selectAttributes()
```
    Returns the array containing the EOAttributes that ERXQuery used to fetch the results. This must be called after the results have been fetched or after calling the getExpression(editingContext) method. These attributes normally includes attributes specified by the select() or the groupBy() methods.
    
    Returns:
    
    attributes that are fetched by this query
  - computeSelectAndGroupingAttributes
```
protected void computeSelectAndGroupingAttributes()
```
  - existingOrNewAttributeForKey
```
protected EOAttribute existingOrNewAttributeForKey(String keyPath)
```
    Called by getExpression() to get the attribute or create an ad-hoc attribute for a key. The keyPath can be relationship key path, i.e. "customer.shippingAddress". This method keeps track of ad hoc attributes created so that if it gets called with the same key path it returns the previously created attribute.
    
    Parameters:
    
    keyPath - a key path
    
    Returns:
    
    corresponding attribute
  - unknownPropertyException
```
protected RuntimeException unknownPropertyException(String keyPath)
```
  - destinationEntity
```
public static EOEntity destinationEntity(EOEntity rootEntity,
                                         String keyPath)
```
    Returns the destination entity for this report attribute. For example, if keyPath is provider.specialtyCategory then this method would return the SpecialtyCategory entity.
    
    Parameters:
    
    rootEntity - starting entity
    
    keyPath - a key path
    
    Returns:
    
    entity keyPath points to
  - destinationProperty
```
public static EOProperty destinationProperty(EOEntity rootEntity,
                                             String keyPath)
```
    Returns whether the property (either EOAttribute or EORelationship) referenced by the last component in the key path.
    
    Parameters:
    
    rootEntity - starting entity
    
    keyPath - a key path
    
    Returns:
    
    property keyPath points to
  - sqlExpressionFactory
```
protected static EOSQLExpressionFactory sqlExpressionFactory(EOEntity anEntity,
                                                             EOEditingContext ec)
```
    Returns a new EOSQLExpressionFactory for the entity and editing context specified.
    
    Parameters:
    
    anEntity - an entity
    
    ec - an editing context
    
    Returns:
    
    expression factory for given entity
  - restrictingQualifierForReferencedEntities
```
protected EOQualifier restrictingQualifierForReferencedEntities()
```
    Returns a qualifier by combining the restricting qualifiers (if any) in the entities referenced. The resulting qualifier is rooted at mainEntity. When this method is called the editingContext, mainEntity, mainSelectQualifier and selectAttributes i-vars must be set.
    
    Returns:
    
    the restricting qualifier
  - sqlStringForAttribute
```
protected String sqlStringForAttribute(EOSQLExpression e,
                                       EOAttribute a)
```
    Returns the SQL string corresponding to attribute a. The EOSQLExpression e must correspond to the expression being built to which must include attribute a as one of the select the attributes.
    
    Parameters:
    
    e - an SQL expression
    
    a - attribute for SQL string
    
    Returns:
    
    SQL string
  - sqlStringForOrderingAttribute
```
public String sqlStringForOrderingAttribute(EOSQLExpression e,
                                            EOAttribute orderingAttribute,
                                            NSSelector selector)
```
    Returns the SQL string for the ordering of attribute a using the specified selector. The EOSQLExpression e must correspond to the expression being built which must include attribute a as one of the select attributes.
    
    Parameters:
    
    e - an SQL expression
    
    orderingAttribute - attribute to sort by
    
    selector - a sort ordering selector to use
    
    Returns:
    
    SQL string
  - sqlWithBindingsInline
```
protected String sqlWithBindingsInline(String sql,
                                       EOSQLExpression expression)
```
    Returns the SQL for the EOSQLExpression specified but with the place holder characters (?) replaced with their corresponding value from the bindings and formatted for in-line use.
    
    Parameters:
    
    sql - SQL string to convert
    
    expression - an SQL expression
    
    Returns:
    
    SQL string
  - sqlWithBindingsInline2
```
protected String sqlWithBindingsInline2(String sql,
                                        EOSQLExpression expression)
```
    Returns the SQL for the EOSQLExpression specified but with the place holder characters (?) replaced with their corresponding value from the bindings and formatted for inline use.
    
    Parameters:
    
    sql - SQL string to convert
    
    expression - an SQL expression
    
    Returns:
    
    SQL string
  - sqlStringForAttributeValue
```
public String sqlStringForAttributeValue(EOSQLExpression e,
                                         EOAttribute att,
                                         Object value)
```
    Uses the EOSQLExpression provided to get the SQL string for value and corresponding attribute. This method is similar to EOSQLExpression's sqlStringForValue(Object value, String keyPath) but this one does not attempt to get to the attribute from the key path as we already have the attribute.
    
    Parameters:
    
    e - an SQL expression
    
    att - an attribute
    
    value - value to use with attribute
    
    Returns:
    
    SQL string
  - formatValueForAttributeForInlineUse
```
protected String formatValueForAttributeForInlineUse(EOSQLExpression sqlExpression,
                                                     Object value,
                                                     EOAttribute attribute)
```
    Formats the value for inline use. For example, the string "I'm smart" would be formatted as "'I''m smart'". Similarly a NSTimestamp value would be converted to something like this "TO_DATE('1967-12-03 00:15:00','YYYY-MM-DD HH24:MI:SS')". Supported values are null, String, NSTimestamp, Boolean, Integer, Number. Other values are converted by calling toString().
    
    Parameters:
    
    sqlExpression - an SQL expression
    
    value - value to use with attribute
    
    attribute - an attribute
    
    Returns:
    
    SQL string
  - databaseProductName
```
protected String databaseProductName(EOEntity entity)
```
  - formattedTimestampForInlineUse
```
protected String formattedTimestampForInlineUse(EOSQLExpression sqlExpression,
                                                Date timestamp,
                                                EOAttribute attribute)
```
  - queryEvaluationTime
```
public double queryEvaluationTime()
```

Class ERXQuery

ERXQuery

Overview

Specifying the Attributes to Fetch

Using Ad Hoc Attributes

Fetching Results into a Custom Class

Augmenting Row Values

Defining Ad Hoc Attributes in the Entity

Limitations

Defaults for Behavior Properties

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

editingContext

mainEntity

mainSelectQualifier

havingQualifier

orderings

relationshipAliases

usesDistinct

isCountingStatement

queryHint

useBindVariables

fetchKeys

groupingKeys

adHocAttributes

adHocGroupings

selectAttributes

groupingAttributes

attributesByName

relationshipKeysSet

refreshRefetchedObjects

serverFetchLimit

clientFetchLimit

queryEvaluationTime

Constructor Detail

ERXQuery

Method Detail

create

selectCount

select

usingDistinct

refreshingRefetchedObjects

from

from

where

groupBy

orderBy

having

usingQueryHint

usingBindVariables

serverFetchLimit

clientFetchLimit

fetch

fetch

fetch

fetch

fetch

fetch

1. Define your custom record class

2. Fetch the records

fetch

fetch

setupAdaptorChannelEOAttributes

fetchValue

usingRelationshipAlias

getExpression

addLimitClause

wrapped

selectAttributes

computeSelectAndGroupingAttributes

existingOrNewAttributeForKey

unknownPropertyException

destinationEntity

destinationProperty

sqlExpressionFactory

restrictingQualifierForReferencedEntities