org.eclipse.persistence.internal.expressions

Class DataExpression

java.lang.Object

org.eclipse.persistence.expressions.Expression

org.eclipse.persistence.internal.expressions.BaseExpression

org.eclipse.persistence.internal.expressions.DataExpression

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

ClassTypeExpression, FieldExpression, ObjectExpression, TableExpression

public abstract class DataExpression
extends BaseExpression

Superclass for all expression that have a context. i.e. a base expression.

See Also:

Serialized Form

Field Summary

Fields inherited from class org.eclipse.persistence.expressions.Expression

shouldUseUpperCaseForIgnoreCase

Constructor Summary

Constructors

Constructor and Description
DataExpression() DataExpression constructor comment.

Method Summary

Modifier and Type	Method and Description
void	addDerivedField(Expression addThis)
void	addDerivedTable(Expression addThis)
DatabaseTable	aliasForTable(DatabaseTable table) INTERNAL: Find the alias for a given table
Expression	asOf(AsOfClause clause) Sets all tables represented by this expression to be queried as of a past time.
void	clearAliases() INTERNAL:
java.util.List<Expression>	copyCollection(java.util.List<Expression> in, java.util.Map alreadyDone)
boolean	equals(java.lang.Object object) INTERNAL: Return if the expression is equal to the other.
Expression	existingDerivedField(DatabaseField field) INTERNAL:
Expression	existingDerivedTable(DatabaseTable table) INTERNAL:
Expression	getAlias(Expression subSelect) ADVANCED: Return an expression representing a sub-select in the from clause.
DatabaseField	getAliasedField() INTERNAL: Return the field appropriately aliased
AsOfClause	getAsOfClause() Answers the past time the expression is explicitly as of.
ClassDescriptor	getContainingDescriptor() INTERNAL: Return the descriptor which contains this query key.
ClassDescriptor	getDescriptor()
DatabaseField	getField() INTERNAL:
Expression	getField(DatabaseField field) ADVANCED: Return an expression representing a field in a data-level query.
Expression	getField(java.lang.String fieldName) ADVANCED: Return an expression representing a field in a data-level query.
DatabaseMapping	getMapping()
QueryKey	getQueryKeyOrNull()
Expression	getTable(DatabaseTable table) ADVANCED: Return an expression representing a table in a data-level query.
Expression	getTable(java.lang.String tableName) ADVANCED: Return an expression representing a table in a data-level query.
TableAliasLookup	getTableAliases() INTERNAL: Return the aliases used.
boolean	hasAsOfClause() ADVANCED: Answers true if this is to be queried as of a past time.
boolean	hasBeenAliased() INTERNAL: Answers if the database tables associated with this expression have been aliased.
boolean	hasBeenNormalized() INTERNAL: Did the normalizer already add additional joins to the where clause due to this query key representing a foreign reference mapping? This insures that join criteria (for any query key expression) is not added twice.
boolean	isAttribute() INTERNAL:
boolean	isDataExpression() INTERNAL:
void	iterateOn(ExpressionIterator iterator) INTERNAL: For iterating using an inner class
Expression	newDerivedField(DatabaseField field) INTERNAL:
Expression	newDerivedTable(DatabaseTable table) INTERNAL:
Expression	normalize(ExpressionNormalizer normalizer) INTERNAL: Normalize the expression into a printable structure.
void	printSQL(ExpressionSQLPrinter printer) INTERNAL: Print SQL onto the stream, using the ExpressionPrinter for context
void	setHasBeenNormalized(boolean value)
void	setTableAliases(TableAliasLookup tableAliases) INTERNAL: For CR#2456, Table identity involves having two tables sharing the same aliasing table.
java.lang.String	tableAliasesDescription()
void	writeSubexpressionsTo(java.io.BufferedWriter writer, int indent) Print the base for debuggin purposes.

Methods inherited from class org.eclipse.persistence.internal.expressions.BaseExpression

getBaseExpression, getBuilder, resetPlaceHolderBuilder, setBaseExpression, shallowClone

Methods inherited from class org.eclipse.persistence.expressions.Expression

addDate, addDate, addMonths, addMonths, alias, all, all, all, all, all, all, all, all, all, all, all, all, all, allOf, and, any, any, any, any, any, any, any, any, any, any, any, any, any, anyOf, anyOf, anyOfAllowingNone, anyOfAllowingNone, as, as, ascending, asciiValue, assignTableAliasesStartingAt, average, between, between, between, between, between, between, between, between, between, caseConditionStatement, caseConditionStatement, caseStatement, caseStatement, cast, clone, cloneUsing, coalesce, coalesce, computeHashCode, concat, containsAllKeyWords, containsAnyKeyWords, containsSubstring, containsSubstring, containsSubstringIgnoringCase, containsSubstringIgnoringCase, convertToUseOuterJoin, copiedVersionFrom, count, create, create, createWithBaseLast, currentDate, currentDateDate, currentTime, currentTimeStamp, dateDifference, dateDifference, dateName, datePart, dateToString, decode, descending, descriptionOfNodeType, difference, distinct, doesConform, doesConform, equal, equal, equal, equal, equal, equal, equal, equal, equal, equal, equalOuterJoin, equalOuterJoin, equalsIgnoreCase, equalsIgnoreCase, except, except, exceptAll, exceptAll, exists, existsNode, extract, extractFields, extractPrimaryKeyValues, extractValue, extractValues, extractXml, from, fromConstant, fromLiteral, get, get, getAllowingNull, getAsOfClauseRecursively, getClonedField, getFields, getFieldValue, getFunction, getFunction, getFunction, getFunction, getFunction, getFunctionWithArguments, getFunctionWithArguments, getLeafDescriptor, getLeafMapping, getName, getNumberVal, getOperator, getOperator, getOwnedTables, getParameter, getParameter, getParameter, getProperty, getSelectionFields, getSelectionFields, getSession, getStringVal, greaterThan, greaterThan, greaterThan, greaterThan, greaterThan, greaterThan, greaterThan, greaterThan, greaterThan, greaterThan, greaterThanEqual, greaterThanEqual, greaterThanEqual, greaterThanEqual, greaterThanEqual, greaterThanEqual, greaterThanEqual, greaterThanEqual, greaterThanEqual, greaterThanEqual, hashCode, hexToRaw, ifNull, in, in, in, in, in, in, in, in, in, in, in, in, index, indexOf, intersect, intersect, intersectAll, intersectAll, isClassTypeExpression, isCompoundExpression, isConstantExpression, isEmpty, isExpressionBuilder, isFieldExpression, isFragment, isFunctionExpression, isLiteralExpression, isLogicalExpression, isMapEntryExpression, isNull, isObjectExpression, isParameterExpression, isQueryKeyExpression, isRelationExpression, isSubSelectExpression, isTableExpression, isTreatExpression, isValueExpression, join, lastDay, leftJoin, leftPad, leftPad, leftTrim, leftTrim, length, lessThan, lessThan, lessThan, lessThan, lessThan, lessThan, lessThan, lessThan, lessThan, lessThan, lessThanEqual, lessThanEqual, lessThanEqual, lessThanEqual, lessThanEqual, lessThanEqual, lessThanEqual, lessThanEqual, lessThanEqual, lessThanEqual, like, like, like, like, likeIgnoreCase, likeIgnoreCase, literal, locate, locate, locate, mapEntry, mapKey, maximum, minimum, monthsBetween, newTime, nextDay, noneOf, not, notBetween, notBetween, notBetween, notBetween, notBetween, notBetween, notBetween, notBetween, notBetween, notEmpty, notEqual, notEqual, notEqual, notEqual, notEqual, notEqual, notEqual, notEqual, notEqual, notEqual, notExists, notIn, notIn, notIn, notIn, notIn, notIn, notIn, notIn, notIn, notIn, notIn, notIn, notLike, notLike, notLike, notLike, notNull, nullIf, nullsFirst, nullsLast, operator, or, performOperator, postfixSQL, prefixSQL, printJava, rebuildOn, ref, regexp, regexp, replace, replicate, replicate, reverse, right, right, rightPad, rightPad, rightTrim, rightTrim, roundDate, selectIfOrderedBy, setLocalBase, setSelectIfOrderedBy, size, size, some, some, some, some, some, some, some, some, some, some, some, some, some, sql, standardDeviation, subQuery, substring, substring, substring, substring, sum, toChar, toChar, toCharacter, toDate, toLowerCase, toNumber, toString, toString, toUpperCase, toUppercaseCasedWords, translate, treat, trim, trim, truncateDate, twist, twistedForBaseAndContext, type, union, union, unionAll, unionAll, validateNode, value, value, value, value, value, value, value, value, value, value, valueFromObject, valueFromObject, variance, writeDescriptionOn, writeFields

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DataExpression

public DataExpression()

DataExpression constructor comment.

Method Detail

equals

public boolean equals(java.lang.Object object)

INTERNAL: Return if the expression is equal to the other. This is used to allow dynamic expression's SQL to be cached.

Overrides:

equals in class Expression

addDerivedField

public void addDerivedField(Expression addThis)

addDerivedTable

public void addDerivedTable(Expression addThis)

asOf

public Expression asOf(AsOfClause clause)

Description copied from class: Expression

Sets all tables represented by this expression to be queried as of a past time.

Example:

  EclipseLink: employee.asOf(new AsOfClause(pastTime))
  Java: None
  SQL (Flashback): SELECT ... FROM EMPLOYEE AS OF TIMESTAMP (pastTime) t0 ...
  SQL (Generic): .. WHERE (t1.START  <= pastTime) AND ((t1.END IS NULL) OR t1.END  > pastTime)
 

Set an as of clause at the expression level to still query for current objects while expressing selection criteria like:

• query objects as of one time that met some condition at another time.
• query objects that changed a certain way over a certain interval (querying for change).

Simultaneously querying on two versions of the same object (one past one present) lets you express these advanced selection criteria.

Example: Querying on past attributes using parallel expressions.

   // Finds all employees who lived in Ottawa as of a past time.
   ExpressionBuilder employee = new ExpressionBuilder();
   ExpressionBuilder pastEmployee = new ExpressionBuilder(Employee.class);
   pastEmployee.asOf(pastTime);
   Expression pastAddress = pastEmployee.get("address"); // by default address will also be as of past time.
   Expression selectionCriteria = pastAddress.get("city").equal("Ottawa").and(
       employee.equal(pastEmployee));
 

The advantage of the parallel expression is that you can still read current objects, the as of clause will affect only the where clause / selection criteria.

You may be tempted to rewrite the above as employee.get("address").asOf(pastTime). That is allowed but see below for the finer points involved in this.

Example: Querying on object changes using parallel expressions.

   // Finds all employees who recently received a raise.  Note that current
   // objects are returned, so can be cached normally.
   ExpressionBuilder employee = new ExpressionBuilder();
   Expression pastEmployee = new ExpressionBuilder(Employee.class);
   pastEmployee.asOf(yesterday);
   Expression parallelJoin = employee.equal(pastEmployee);
   Expression selectionCriteria = parallelJoin.and(
       employee.get("salary").greaterThan(pastEmployee.get("salary")));
 

Example: Querying on object changes using custom query keys

   // First define the custom query key and add it to your descriptor.
   ExpressionBuilder builder = new ExpressionBuilder(Employee.class);
   Expression joinCriteria = builder.getField("EMPLOYEE.EMP_ID").equal(builder.getParameter("EMPLOYEE.EMP_ID"));
   OneToOneQueryKey selfReferential = new OneToOneQueryKey();
   selfReferential.setName("this");
   selfReferential.setJoinCriteria(joinCriteria);
   selfReferential.setReferenceClass(Employee.class);
   getSession().getDescriptor(Employee.class).addQueryKey(selfReferential);

   // Now build query as before.
   Expression employee = new ExpessionBuilder();
   Expression pastEmployee = employee.get("this").asOf(yesterday);
   Expression selectionCriteria = employee.get("salary").greaterThan(pastEmployee.get("salary"));
 

Note in general that any parallel expression can be rewritten using a custom query key. EclipseLink will even automatically interpret x.get("this") for you so you do not need to define the above query key first.

Full Reference:

If an object is mapped to multiple tables, then each table will be as of the same time. Two objects mapped to the same table can not have different as of times. Conversely only expressions which have associated tables can have an as of clause.

If an as of clause is not explicitly set an expression will use the clause of its base expression, and so on recursively until one is found or an ExpressionBuilder is reached. Some usage scenarios follow:

• employee.asOf(pastTime).anyOf("projects"): projects as of past time.
• expressionBuilder.asOf(pastTime): entire expression as of past time.
• employee.asOf(pastTime).anyOf("projects").asOf(null): projects as of current time.
• employee.anyOf("projects").asOf(pastTime): projects only as of past time.

Watch out for x.asOf(oneTime).get("y").asOf(anotherTime).

• emp.anyOf("phoneNumbers").asOf(yesterday) = emp.asOf(yesterday).anyOf("phoneNumbers") but:
• emp.get("address").asOf(yesterday) != emp.asOf(yesterday).get("address").

Whether the join is also as of yesterday depends on which table the foreign key field resides on. In an anyOf the foreign key is always on the right, but in a get (1-1) it could be on either side. For this reason employee.get("address").asOf(yesterday) is undefined as it can mean either 'my address as of yesterday', or 'my address, as of yesterday.'

Overrides:

asOf in class Expression

Parameters:

clause - A read only data object used to represent a past time.

Returns:

this

See Also:

AsOfClause, Expression.hasAsOfClause(), Session.acquireHistoricalSession(org.eclipse.persistence.history.AsOfClause), ObjectLevelReadQuery.setAsOfClause(org.eclipse.persistence.history.AsOfClause)

aliasForTable

public DatabaseTable aliasForTable(DatabaseTable table)

INTERNAL: Find the alias for a given table

Overrides:

aliasForTable in class Expression

clearAliases

public void clearAliases()

INTERNAL:

copyCollection

public java.util.List<Expression> copyCollection(java.util.List<Expression> in,
                                                 java.util.Map alreadyDone)

existingDerivedField

public Expression existingDerivedField(DatabaseField field)

INTERNAL:

existingDerivedTable

public Expression existingDerivedTable(DatabaseTable table)

INTERNAL:

getAliasedField

public DatabaseField getAliasedField()

INTERNAL: Return the field appropriately aliased

getAsOfClause

public AsOfClause getAsOfClause()

Description copied from class: Expression

Answers the past time the expression is explicitly as of.

Overrides:

getAsOfClause in class Expression

Returns:

An immutable object representation of the past time. null if no clause set, AsOfClause.NO_CLAUSE if clause explicitly set to null.

See Also:

Expression.asOf(org.eclipse.persistence.history.AsOfClause), Expression.hasAsOfClause()

getDescriptor

public ClassDescriptor getDescriptor()

getField

public DatabaseField getField()

INTERNAL:

getField

public Expression getField(java.lang.String fieldName)

Description copied from class: Expression

ADVANCED: Return an expression representing a field in a data-level query. This is used internally in EclipseLink, or to construct queries involving fields and/or tables that are not mapped.

Example:

  builder.getField("ADDR_ID").greaterThan(100);
  builder.getTable("PROJ_EMP").getField("TYPE").equal("S");
 

Overrides:

getField in class Expression

getField

public Expression getField(DatabaseField field)

Description copied from class: Expression

ADVANCED: Return an expression representing a field in a data-level query. This is used internally in EclipseLink, or to construct queries involving fields and/or tables that are not mapped.

Example:

  builder.getField(aField).greaterThan(100);
 

Overrides:

getField in class Expression

getContainingDescriptor

public ClassDescriptor getContainingDescriptor()

INTERNAL: Return the descriptor which contains this query key.

getMapping

public DatabaseMapping getMapping()

getQueryKeyOrNull

public QueryKey getQueryKeyOrNull()

getTable

public Expression getTable(java.lang.String tableName)

Description copied from class: Expression

ADVANCED: Return an expression representing a table in a data-level query. This is used internally in EclipseLink, or to construct queries involving fields and/or tables that are not mapped.

Example:

  builder.getTable("PROJ_EMP").getField("TYPE").equal("S");
 

Overrides:

getTable in class Expression

getTable

public Expression getTable(DatabaseTable table)

Description copied from class: Expression

ADVANCED: Return an expression representing a table in a data-level query. This is used internally in EclipseLink, or to construct queries involving fields and/or tables that are not mapped.

Example:

  builder.getTable(linkTable).getField("TYPE").equal("S");
 

Overrides:

getTable in class Expression

getTableAliases

public TableAliasLookup getTableAliases()

INTERNAL: Return the aliases used. For CR#2456 must never lazily initialize as also used for Expression identity.

Overrides:

getTableAliases in class Expression

hasBeenNormalized

public boolean hasBeenNormalized()

INTERNAL: Did the normalizer already add additional joins to the where clause due to this query key representing a foreign reference mapping? This insures that join criteria (for any query key expression) is not added twice.

New meaning: DataExpressions are often iterated on multiple times during normalize, but Function/Relation expressions only once. Adding a has been normalized flag improves performance and is required in some applications, such as have temporal query criteria been added.

hasAsOfClause

public boolean hasAsOfClause()

Description copied from class: Expression

ADVANCED: Answers true if this is to be queried as of a past time.

Overrides:

hasAsOfClause in class Expression

Returns:

false from asOf(null); hasAsOfClause().

See Also:

Expression.getAsOfClause()

hasBeenAliased

public boolean hasBeenAliased()

Description copied from class: Expression

INTERNAL: Answers if the database tables associated with this expression have been aliased. This insures the same tables are not aliased twice.

Overrides:

hasBeenAliased in class Expression

isAttribute

public boolean isAttribute()

INTERNAL:

isDataExpression

public boolean isDataExpression()

Description copied from class: Expression

INTERNAL:

Overrides:

isDataExpression in class Expression

iterateOn

public void iterateOn(ExpressionIterator iterator)

INTERNAL: For iterating using an inner class

Overrides:

iterateOn in class Expression

newDerivedField

public Expression newDerivedField(DatabaseField field)

INTERNAL:

newDerivedTable

public Expression newDerivedTable(DatabaseTable table)

INTERNAL:

getAlias

public Expression getAlias(Expression subSelect)

ADVANCED: Return an expression representing a sub-select in the from clause.

Example:

  builder.getAlias(builder.subQuery(reportQuery)).get("type").equal("S");
 

Overrides:

getAlias in class Expression

normalize

public Expression normalize(ExpressionNormalizer normalizer)

INTERNAL: Normalize the expression into a printable structure. Any joins must be added to form a new root.

Overrides:

normalize in class Expression

printSQL

public void printSQL(ExpressionSQLPrinter printer)

INTERNAL: Print SQL onto the stream, using the ExpressionPrinter for context

Specified by:

printSQL in class Expression

setHasBeenNormalized

public void setHasBeenNormalized(boolean value)

setTableAliases

public void setTableAliases(TableAliasLookup tableAliases)

INTERNAL: For CR#2456, Table identity involves having two tables sharing the same aliasing table.

tableAliasesDescription

public java.lang.String tableAliasesDescription()

writeSubexpressionsTo

public void writeSubexpressionsTo(java.io.BufferedWriter writer,
                                  int indent)
                           throws java.io.IOException

Print the base for debuggin purposes.

Overrides:

writeSubexpressionsTo in class Expression

Throws:

java.io.IOException