Purpose: Query for information about a set of objects instead of the objects themselves. This supports select single attributes, nested attributes, aggregation functions and group bys.
Attribute Types:
addAttribute("directQueryKey") is a short cut method to add an attribute with the same name as its corresponding direct query key.
addAttribute("attributeName", expBuilder.get("oneToOneMapping").get("directQueryKey")) is the full approach for get values through joined 1:1 relationships.
addAttribute("attributeName", expBuilder.getField("TABLE.FIELD")) allows the addition of raw values or values which were not mapped in the object model directly (i.e. FK attributes).
addAttribute("attributeName", null) Leave a place holder (NULL) value in the result (used for included values from other systems or calculated values).
Retrieving Primary Keys: It is possible to retrieve the primary key raw values within each result, but stored in a separate (internal) vector. This primary key vector can later be used to retrieve the real object.
Since:
TOPLink/Java 2.0
Author:
Doug Clarke
See Also:
retrievePrimaryKeys(), If the values are wanted in the result array then they must be added as attributes. For primary keys which are not mapped directly you can add them as DatabaseFields (see above)., Serialized Form
Field Summary
protected boolean
addToConstructorItem
flag to allow items to be added to the last ConstructorReportItem
returnChoice
Can be one of (ShouldReturnSingleResult, ShouldReturnSingleValue, ShouldReturnSingleAttribute) Simplifies the result by only returning the first result, first value, or all attribute values
ReportQuery(java.lang.Class javaClass, ExpressionBuilder builder)
PUBLIC: The report query is require to be constructor with an expression builder.
ReportQuery(ExpressionBuilder builder)
PUBLIC: The report query is require to be constructor with an expression builder.
Method Summary
void
addAttribute(java.lang.String itemName)
PUBLIC: Add the attribute from the reference class to be included in the result.
void
addAttribute(java.lang.String itemName, Expression attributeExpression)
PUBLIC: Add the attribute to be included in the result.
void
addAttribute(java.lang.String itemName, Expression attributeExpression, java.lang.Class type)
PUBLIC: Add the attribute to be included in the result.
void
addAverage(java.lang.String itemName)
PUBLIC: Add the average value of the attribute to be included in the result.
void
addAverage(java.lang.String itemName, java.lang.Class resultType)
PUBLIC: Add the average value of the attribute to be included in the result and return it as the specified resultType.
void
addAverage(java.lang.String itemName, Expression attributeExpression)
PUBLIC: Add the average value of the attribute to be included in the result.
void
addAverage(java.lang.String itemName, Expression attributeExpression, java.lang.Class resultType)
PUBLIC: Add the average value of the attribute to be included in the result and return it as the specified resultType.
addCount()
PUBLIC: Include the number of rows returned by the query in the result.
void
addCount(java.lang.String attributeName)
PUBLIC: Include the number of rows returned by the query in the result, where attributeExpression is not null.
void
addCount(java.lang.String attributeName, java.lang.Class resultType)
PUBLIC: Include the number of rows returned by the query in the result, where attributeExpression is not null.
void
addCount(java.lang.String itemName, Expression attributeExpression)
PUBLIC: Include the number of rows returned by the query in the result, where attributeExpression is not null.
void
addCount(java.lang.String itemName, Expression attributeExpression, java.lang.Class resultType)
PUBLIC: Include the number of rows returned by the query in the result, where attributeExpression is not null.
void
addFunctionItem(java.lang.String itemName, Expression attributeExpression, java.lang.String functionName)
ADVANCED: Add the function against the attribute expression to be included in the result.
void
addGrouping(Expression expression)
PUBLIC: Add the attribute expression to the group by expressions.
void
addGrouping(java.lang.String attributeName)
PUBLIC: Add the attribute to the group by expressions.
private void
addItem(org.eclipse.persistence.internal.queries.ReportItem item)
INTERNAL: Method used to abstract addToConstructorItem behavour from the public addItem methods
void
addItem(java.lang.String itemName, Expression attributeExpression)
ADVANCED: Add the expression value to be included in the result.
protected void
addItem(java.lang.String itemName, Expression attributeExpression, java.lang.Class resultType)
INTERNAL: Add the expression value to be included in the result.
void
addItem(java.lang.String itemName, Expression attributeExpression, java.util.List joinedExpressions)
ADVANCED: Add the expression value to be included in the result.
void
addMaximum(java.lang.String itemName)
PUBLIC: Add the maximum value of the attribute to be included in the result.
void
addMaximum(java.lang.String itemName, Expression attributeExpression)
PUBLIC: Add the maximum value of the attribute to be included in the result.
void
addMinimum(java.lang.String itemName)
PUBLIC: Add the minimum value of the attribute to be included in the result.
void
addMinimum(java.lang.String itemName, Expression attributeExpression)
PUBLIC: Add the minimum value of the attribute to be included in the result.
void
addStandardDeviation(java.lang.String itemName)
PUBLIC: Add the standard deviation value of the attribute to be included in the result.
void
addStandardDeviation(java.lang.String itemName, Expression attributeExpression)
PUBLIC: Add the standard deviation value of the attribute to be included in the result.
void
addSum(java.lang.String itemName)
PUBLIC: Add the sum value of the attribute to be included in the result.
void
addSum(java.lang.String itemName, java.lang.Class resultType)
PUBLIC: Add the sum value of the attribute to be included in the result and return it as the specified resultType.
void
addSum(java.lang.String itemName, Expression attributeExpression)
PUBLIC: Add the sum value of the attribute to be included in the result.
void
addSum(java.lang.String itemName, Expression attributeExpression, java.lang.Class resultType)
PUBLIC: Add the sum value of the attribute to be included in the result and return it as the specified resultType.
void
addVariance(java.lang.String itemName)
PUBLIC: Add the variance value of the attribute to be included in the result.
void
addVariance(java.lang.String itemName, Expression attributeExpression)
PUBLIC: Add the variance value of the attribute to be included in the result.
beginAddingConstructorArguments(java.lang.Class constructorClass, java.lang.Class[] constructorArgTypes)
PUBLIC: Call a constructor for the given class with the results of this query.
java.lang.Object
buildObject(org.eclipse.persistence.internal.sessions.AbstractRecord row)
INTERNAL: By default return the row.
java.lang.Object
buildObject(org.eclipse.persistence.internal.sessions.AbstractRecord row, java.util.Vector toManyJoinData)
INTERNAL: Construct a result from a row.
java.lang.Object
buildObjects(java.util.Vector rows)
INTERNAL: Construct a container of ReportQueryResult from the rows.
protected java.lang.Object
checkEarlyReturnLocal(org.eclipse.persistence.internal.sessions.AbstractSession session, org.eclipse.persistence.internal.sessions.AbstractRecord translationRow)
INTERNAL: The cache check is done before the prepare as a hit will not require the work to be done.
checkForCustomQuery(org.eclipse.persistence.internal.sessions.AbstractSession session, org.eclipse.persistence.internal.sessions.AbstractRecord translationRow)
INTERNAL: Check to see if a custom query should be used for this query.
copyReportItems(java.util.Map alreadyDone)
INTERNAL: Required for a very special case of bug 2612185: ReportItems from parallelExpressions, on a ReportQuery which is a subQuery, which is being batch read.
void
dontRetrievePrimaryKeys()
PUBLIC: Set if the query results should contain the primary keys or each associated object.
endAddingToConstructorItem()
PUBLIC: Used in conjunction with beginAddingConstructorArguments to signal that expressions should no longer be be added to the collection used in the constructor.
boolean
equals(java.lang.Object object)
INTERNAL: Return if the query is equal to the other.
extractRemoteResult(org.eclipse.persistence.internal.sessions.remote.Transporter transporter)
INTERNAL: Extract the correct query result from the transporter.
prepareSubSelect(org.eclipse.persistence.internal.sessions.AbstractSession session, org.eclipse.persistence.internal.sessions.AbstractRecord translationRow, java.util.Map clonedExpressions)
INTERNAL: Prepare the receiver for being printed inside a subselect.
java.util.Map
replaceValueHoldersIn(java.lang.Object object, org.eclipse.persistence.internal.sessions.remote.RemoteSessionController controller)
INTERNAL: replace the value holders in the specified result object(s)
void
retrievePrimaryKeys()
PUBLIC: Set if the query results should contain the primary keys or each associated object.
void
returnSingleAttribute()
PUBLIC: Simplify the result by returning a single attribute.
void
returnSingleResult()
PUBLIC: Simplifies the result by only returning the first result.
void
returnSingleValue()
PUBLIC: Simplifies the result by only returning a single value.
setItems(java.util.List<org.eclipse.persistence.internal.queries.ReportItem> items)
INTERNAL: Set the ReportQueryItems defining the attributes to be read.
boolean
setLockModeType(java.lang.String lockModeType, org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Sets a javax.persistence.LockModeType to used with this queries execution.
protected void
setNames(java.util.List<java.lang.String> names)
INTERNAL: Set the item names.
void
setReturnType(int returnChoice)
PUBLIC: Set the return type.
void
setShouldRetrieveFirstPrimaryKey(boolean shouldRetrieveFirstPrimaryKey)
ADVANCED: Sets if the query results should contain the first primary key of each associated object.
void
setShouldRetrievePrimaryKeys(boolean shouldRetrievePrimaryKeys)
PUBLIC: Set if the query results should contain the primary keys or each associated object.
void
setShouldReturnSingleAttribute(boolean newChoice)
PUBLIC: Simplifies the result by only returning the attribute (as opposed to wrapping in a ReportQueryResult).
void
setShouldReturnSingleResult(boolean newChoice)
PUBLIC: Simplifies the result by only returning the first result.
void
setShouldReturnSingleValue(boolean newChoice)
PUBLIC: Simplifies the result by only returning a single value.
Can be one of (ShouldReturnSingleResult, ShouldReturnSingleValue, ShouldReturnSingleAttribute) Simplifies the result by only returning the first result, first value, or all attribute values
addToConstructorItem
protected boolean addToConstructorItem
flag to allow items to be added to the last ConstructorReportItem
public ReportQuery(java.lang.Class javaClass,
Expression expression)
ReportQuery
public ReportQuery(java.lang.Class javaClass,
ExpressionBuilder builder)
PUBLIC: The report query is require to be constructor with an expression builder. This build must be used for the selection critiera, any item expressions, group bys and order bys.
PUBLIC: The report query is require to be constructor with an expression builder. This build must be used for the selection critiera, any item expressions, group bys and order bys.
Method Detail
addAttribute
public void addAttribute(java.lang.String itemName)
PUBLIC: Add the attribute from the reference class to be included in the result. EXAMPLE: reportQuery.addAttribute("firstName");
addAttribute
public void addAttribute(java.lang.String itemName,
Expression attributeExpression)
PUBLIC: Add the attribute to be included in the result. EXAMPLE: reportQuery.addAttribute("city", expBuilder.get("address").get("city"));
addAttribute
public void addAttribute(java.lang.String itemName,
Expression attributeExpression,
java.lang.Class type)
PUBLIC: Add the attribute to be included in the result. Return the result as the provided class EXAMPLE: reportQuery.addAttribute("city", expBuilder.get("period").get("startTime"), Time.class);
addAverage
public void addAverage(java.lang.String itemName)
PUBLIC: Add the average value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addAverage("salary");
addAverage
public void addAverage(java.lang.String itemName,
java.lang.Class resultType)
PUBLIC: Add the average value of the attribute to be included in the result and return it as the specified resultType. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addAverage("salary", Float.class);
addAverage
public void addAverage(java.lang.String itemName,
Expression attributeExpression)
PUBLIC: Add the average value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addAverage("managerSalary", expBuilder.get("manager").get("salary"));
addAverage
public void addAverage(java.lang.String itemName,
Expression attributeExpression,
java.lang.Class resultType)
PUBLIC: Add the average value of the attribute to be included in the result and return it as the specified resultType. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addAverage("managerSalary", expBuilder.get("manager").get("salary"), Double.class);
PUBLIC: Include the number of rows returned by the query in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: Java: reportQuery.addCount(); SQL: SELECT COUNT (*) FROM ...
public void addCount(java.lang.String attributeName)
PUBLIC: Include the number of rows returned by the query in the result, where attributeExpression is not null. Aggregation functions can be used with a group by, or on the entire result set.
Example:
TopLink: reportQuery.addCount("id"); SQL: SELECT COUNT (t0.EMP_ID) FROM EMPLOYEE t0, ...
Parameters:
attributeName - the number of rows where attributeName is not null will be returned.
public void addCount(java.lang.String attributeName,
java.lang.Class resultType)
PUBLIC: Include the number of rows returned by the query in the result, where attributeExpression is not null. Aggregation functions can be used with a group by, or on the entire result set. Set the count to be returned as the specified resultType.
public void addCount(java.lang.String itemName,
Expression attributeExpression)
PUBLIC: Include the number of rows returned by the query in the result, where attributeExpression is not null. Aggregation functions can be used with a group by, or on the entire result set.
public void addCount(java.lang.String itemName,
Expression attributeExpression,
java.lang.Class resultType)
PUBLIC: Include the number of rows returned by the query in the result, where attributeExpression is not null. Aggregation functions can be used with a group by, or on the entire result set. Set the count to be returned as the specified resultType.
public void addFunctionItem(java.lang.String itemName,
Expression attributeExpression,
java.lang.String functionName)
ADVANCED: Add the function against the attribute expression to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. Example: reportQuery.addFunctionItem("average", expBuilder.get("salary"), "average");
addGrouping
public void addGrouping(java.lang.String attributeName)
PUBLIC: Add the attribute to the group by expressions. This will group the result set on that attribute and is normally used in conjunction with aggregation functions. Example: reportQuery.addGrouping("lastName")
PUBLIC: Add the attribute expression to the group by expressions. This will group the result set on that attribute and is normally used in conjunction with aggregation functions. Example: reportQuery.addGrouping(expBuilder.get("address").get("country"))
setHavingExpression
public void setHavingExpression(Expression expression)
PUBLIC: Add the expression to the query to be used in the HAVING clause. This epression will be used to filter the result sets after they are grouped. It must be used in conjunction with the GROUP BY clause.
INTERNAL: Add the expression value to be included in the result. EXAMPLE: reportQuery.addItem("name", expBuilder.get("firstName").toUpperCase()); The resultType can be specified to support EJBQL that adheres to the EJB 3.0 spec.
addMaximum
public void addMaximum(java.lang.String itemName)
PUBLIC: Add the maximum value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addMaximum("salary");
addMaximum
public void addMaximum(java.lang.String itemName,
Expression attributeExpression)
PUBLIC: Add the maximum value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addMaximum("managerSalary", expBuilder.get("manager").get("salary"));
addMinimum
public void addMinimum(java.lang.String itemName)
PUBLIC: Add the minimum value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addMinimum("salary");
addMinimum
public void addMinimum(java.lang.String itemName,
Expression attributeExpression)
PUBLIC: Add the minimum value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addMinimum("managerSalary", expBuilder.get("manager").get("salary"));
addStandardDeviation
public void addStandardDeviation(java.lang.String itemName)
PUBLIC: Add the standard deviation value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addStandardDeviation("salary");
addStandardDeviation
public void addStandardDeviation(java.lang.String itemName,
Expression attributeExpression)
PUBLIC: Add the standard deviation value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addStandardDeviation("managerSalary", expBuilder.get("manager").get("salary"));
addSum
public void addSum(java.lang.String itemName)
PUBLIC: Add the sum value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addSum("salary");
addSum
public void addSum(java.lang.String itemName,
java.lang.Class resultType)
PUBLIC: Add the sum value of the attribute to be included in the result and return it as the specified resultType. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addSum("salary", Float.class);
addSum
public void addSum(java.lang.String itemName,
Expression attributeExpression)
PUBLIC: Add the sum value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addSum("managerSalary", expBuilder.get("manager").get("salary"));
addSum
public void addSum(java.lang.String itemName,
Expression attributeExpression,
java.lang.Class resultType)
PUBLIC: Add the sum value of the attribute to be included in the result and return it as the specified resultType. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addSum("managerSalary", expBuilder.get("manager").get("salary"), Float.class);
addVariance
public void addVariance(java.lang.String itemName)
PUBLIC: Add the variance value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addVariance("salary");
addVariance
public void addVariance(java.lang.String itemName,
Expression attributeExpression)
PUBLIC: Add the variance value of the attribute to be included in the result. Aggregation functions can be used with a group by, or on the entire result set. EXAMPLE: reportQuery.addVariance("managerSalary", expBuilder.get("manager").get("salary"));
beginAddingConstructorArguments
public ConstructorReportItembeginAddingConstructorArguments(java.lang.Class constructorClass)
PUBLIC: Call a constructor for the given class with the results of this query.
Parameters:
constructorClass -
beginAddingConstructorArguments
public ConstructorReportItembeginAddingConstructorArguments(java.lang.Class constructorClass,
java.lang.Class[] constructorArgTypes)
PUBLIC: Call a constructor for the given class with the results of this query.
Parameters:
constructorClass -
constructorArgTypes - - sets the argument types to be passed to the constructor.
buildObject
public java.lang.Object buildObject(org.eclipse.persistence.internal.sessions.AbstractRecord row)
INTERNAL: By default return the row. Used by cursored stream.
INTERNAL: Check to see if a custom query should be used for this query. This is done before the query is copied and prepared/executed. null means there is none.
public void copyReportItems(java.util.Map alreadyDone)
INTERNAL: Required for a very special case of bug 2612185: ReportItems from parallelExpressions, on a ReportQuery which is a subQuery, which is being batch read. In a batch query the selection criteria is effectively cloned twice, meaning the ReportItems need to be cloned an extra time also to stay in sync. Each call to copiedVersionFrom() will take O(1) time as the expression was already cloned.
dontRetrievePrimaryKeys
public void dontRetrievePrimaryKeys()
PUBLIC: Set if the query results should contain the primary keys or each associated object. This make retrieving the real object easier. By default they are not retrieved.
dontReturnSingleAttribute
public void dontReturnSingleAttribute()
PUBLIC: Don't simplify the result by returning the single attribute. Wrap in a ReportQueryResult.
dontReturnSingleResult
public void dontReturnSingleResult()
PUBLIC: Simplifies the result by only returning the first result. This can be used if it known that only one row is returned by the report query.
dontReturnSingleValue
public void dontReturnSingleValue()
PUBLIC: Simplifies the result by only returning a single value. This can be used if it known that only one row is returned by the report query and only a single item is added to the report.
dontReturnWithoutReportQueryResult
public void dontReturnWithoutReportQueryResult()
PUBLIC: Simplifies the result by only returning a single value. This can be used if it known that only one row is returned by the report query and only a single item is added to the report.
endAddingToConstructorItem
public void endAddingToConstructorItem()
PUBLIC: Used in conjunction with beginAddingConstructorArguments to signal that expressions should no longer be be added to the collection used in the constructor.
executeDatabaseQuery
public java.lang.Object executeDatabaseQuery()
throws DatabaseException
INTERNAL: Execute the query. Get the rows and build the objects or report data from the rows.
INTERNAL: Returns the specific default redirector for this query type. There are numerous default query redirectors. See ClassDescriptor for their types.
public java.util.List<org.eclipse.persistence.internal.queries.ReportItem> getItems()
INTERNAL:
Returns:
ReportItems defining the attributes to be read.
setItems
public void setItems(java.util.List<org.eclipse.persistence.internal.queries.ReportItem> items)
INTERNAL: Set the ReportQueryItems defining the attributes to be read.
setLockModeType
public boolean setLockModeType(java.lang.String lockModeType,
org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Sets a javax.persistence.LockModeType to used with this queries execution. The valid types are: - WRITE - READ - OPTIMISTIC - OPTIMISTIC_FORCE_INCREMENT - PESSIMISTIC - PESSIMISTIC_FORCE_INCREMENT - NONE Setting a null type will do nothing.
returns a failure flag indicating that we were UNABLE to set the lock mode because of validation. Callers to this method should check the return value and throw the necessary exception.
clearItems
public void clearItems()
INTERNAL: Clear the ReportQueryItems
getNames
public java.util.List<java.lang.String> getNames()
INTERNAL: Lazily initialize and return the names of the items requested for use in each result object.
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 EJBQL parse cache to allow preparsed queries to be used to prepare dynamic queries. This only copies over properties that are configured through EJBQL.
PUBLIC: Set if the query results should contain the primary keys or each associated object. This make retrieving the real object easier. By default they are not retrieved.
getReturnType
public int getReturnType()
PUBLIC: Return the return type.
setReturnType
public void setReturnType(int returnChoice)
PUBLIC: Set the return type. This can be one of several constants,
ShouldReturnReportResult - return List<ReportQueryResult> : ReportQueryResult (Map) of each row is returned.
ShouldReturnSingleResult - return ReportQueryResult : Only first row is returned.