View source for EclipseLink/DesignDocs/374771

<div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>
= Design Specification: TREAT expression support =

[http://bugs.eclipse.org/374771 ER 374771]

== Document History ==
{|{{BMTableStyle}}
|-{{BMTHStyle}}
! Date
! Author
! Version Description & Notes
|- 
| 20 March 2012
| Gordon Yorke
| Initial Document created
|}

== Project overview ==

JPA 2.1 will add support for a TREAT function within JPQL and criteria.  Support will be required for both JPQL and Criteria queries.

== Concepts ==
When creating a JOIN in a JPQL statement or Criteria API expression the type of the join is that of the corresponding attribute type.  Should the query writer wish to reference an attribute of a subclass of that JOIN type the query writer would use the TREAT function to effectively join to a subclass of the JOIN type and JOIN is treated as the specified subtype.  

  Select e from Employee e, JOIN TREAT(e.projects as LargeProject) l WHERE l.budget > 25000 

In the case of this example the type of Employee.projects is Project.  Because the query writer wants to access an attribute of the subclass LargeProject TREAT is used.

== Requirements ==

Support use of the TREAT keyword in JPQL and Criteria API for FROM, WHERE and SELECT clauses.
Ensure proper validation exceptions occur.
Of the 3 inheritance strategies, single table inheritance (STI), joined-table inheritance (JTI), and table per class (TPC), TREAT will only be required to work with the first 2 (STI and JTI).  Treat with Table per class inheritance maybe left as a seperate issue


== Design Constraints ==
1) In the case of joins, the referenced object does not participate in the result.  Type filtering will need to be added to the query and inner joins to subclasses for JTI.
2) In the case of a restriction, the associated predicate is false.  Type filtering will need to be added to the predicate for STI, and use outer joins/parallel expressions for subclasses with JTI.

== Design / Functionality ==
EclipseLink native expressions will allow treat to be called on ObjectExpression subtypes, specifically ExpressionBuilder and QueryKeyExpressions.  This will create a wrapper expression subclass that will be used in expressions instead of the underlying join it is based off of.  Potentially this allows treat to be called multiple times on the same join, so that the expression 
  (project as LargeProject).budget >1000000 OR (project as SmallProject).priority = "IMPORTANT" 
can return all Large and Small projects meeting the individual constraints.  

An early POC (see attachment uploaded to ER 374771) has this treat expression subclass QueryKeyExpression directly and sets the QueryKeyExpression.shouldUseOuterJoinForMultitableInheritance flag to true.  This joins all subclasses using an outerjoin.  In the future the treat subExpression will be responsble for joining the subclasses to the query as required when the classes involved use Joined Table Inheritance (JTI).  

The treat subexpression will also include selection criteria pulled from the cast descriptor's InheritancePolicy, withAllSubclassesExpression if not null; this should check if the type field is in the list of child class indicators.  If it is null then either inheritance uses a class extractor and an error is required because we cannot support this, or shouldReadSubclasses is false.  The POF is using typeExpressionBase.type().equal(this.getDescriptor().getJavaClass()) when withAllSubclassesExpression is null.  This expression is being included with the ON clause so that it can be added to the statement and normalized correctly.  This allows the the type and joining to be included in the where clause, but unfortunately outside of the current predicate so that the example given above returns no results - (budget>100000 or priority = "IMPORTANT" ) AND ( type=LargeProject and type=SmallProject).  The type expression will need to be normalized and added to the statement similar to how the On clause is currently supported, but independently.

== Testing ==

== API ==

== GUI ==

== Config files ==

== Documentation ==

==Work Required==
# Implement expression framework support for WHERE clause
#: approx 3 days
# Implement JPQL support
#: approx 2 day
# Implement Criteria support
#: approx 2 days
# Testing
#: approx 2 days

== Open Issues ==

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.

{|{{BMTableStyle}}
|-{{BMTHStyle}}
! Issue #
! Owner
! Description / Notes
|- 
|1
|
|Deciding if the shouldReadSubclasses inheritance flag should affect this feature.  For instance, if false, should treat(person as Employee) only include employees, or should it include Employee subclasses as well.  
|}

== Decisions ==

This section lists decisions made. These are intended to document the resolution of open issues or constraints added to the project that are important.

{|{{BMTableStyle}}
|-{{BMTHStyle}}
! Issue #
! Description / Notes
! Decision
|- 
|
|
|
|}

== Future Considerations ==

During the research for this project the following items were identified as out of scope but are captured here as potential future enhancements. If agreed upon during the review process these should be logged in the bug system.
1) support for Treat with table per class inheritance.