EclipseLink 2.4.2, build 'v20130514-5956486' API Reference

org.eclipse.persistence.jpa.jpql
Class JPQLQueryContext

java.lang.Object
  extended by org.eclipse.persistence.jpa.jpql.JPQLQueryContext
Direct Known Subclasses:
DefaultJPQLQueryContext, EclipseLinkJPQLQueryContext

public abstract class JPQLQueryContext
extends java.lang.Object

This context is used to store information related to the JPQL query.

 IQuery externalQuery = ...;

 JPQLQueryContext context = new JPQLQueryContext(DefaultJPQLGrammar.instance());
 context.setQuery(query);
If the JPQL query is already parsed, then the context can use it and it needs to be set before setting the IQuery:
 JPQLExpression jpqlExpression = ...;

 JPQLQueryContext context = new JPQLQueryContext(DefaultJPQLGrammar.instance());
 context.setJPQLExpression(jpqlExpression);
 context.setQuery(query);

Provisional API: This interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.

Version:
2.4
Author:
Pascal Filion
Since:
2.3

Nested Class Summary
protected  class JPQLQueryContext.InputParameterVisitor
          This visitor is responsible to find the InputParameters with a certain parameter name.
protected static class JPQLQueryContext.QueryExpressionVisitor
          This visitor is responsible to retrieve the Expression that is the beginning of a query.
 
Field Summary
protected  JPQLQueryContext currentContext
          The current JPQLQueryContext is the context used for the current query or subquery.
protected  JPQLQueryContext parent
          When this context is a sub-context used for a subquery, then this is the context for the parent query.
 
Constructor Summary
  JPQLQueryContext(JPQLGrammar jpqlGrammar)
          Creates a new JPQLQueryContext.
protected JPQLQueryContext(JPQLQueryContext parent, Expression currentQuery)
          Creates a new sub-JPQLQueryContext.
 
Method Summary
protected  DeclarationResolver buildDeclarationResolver()
           
protected  DeclarationResolver buildDeclarationResolver(DeclarationResolver parent)
           
protected  JPQLQueryContext.InputParameterVisitor buildInputParameter()
           
protected abstract  JPQLQueryContext buildJPQLQueryContext(JPQLQueryContext currentContext, Expression currentQuery)
           
protected abstract  LiteralVisitor buildLiteralVisitor()
           
protected  ParameterTypeVisitor buildParameterTypeVisitor()
           
protected  JPQLQueryContext.QueryExpressionVisitor buildQueryExpressionVisitor()
           
protected abstract  ResolverBuilder buildResolverBuilder()
           
 void convertUnqualifiedDeclaration(DeclarationResolver.Declaration declaration)
          Converts the given DeclarationResolver.Declaration from being set as a range variable declaration to a path expression declaration.
 void dispose()
          Disposes the internal data.
 void disposeSubqueryContext()
          Disposes this context, which is the current context being used by a subquery.
 java.util.Collection<InputParameter> findInputParameters(java.lang.String parameterName)
          Retrieves all the InputParameters with the given parameter name.
 Expression getActualCurrentQuery()
          Returns the current Expression being manipulated, which is either the top-level query or a subquery.
 DeclarationResolver getActualDeclarationResolver()
          Returns the DeclarationResolver of this context and not from the current query's declaration.
 JPQLQueryContext getCurrentContext()
          Returns the current JPQLQueryContext, i.e. the context of the query being manipulated, which can either be the top-level query or a subquery.
 Expression getCurrentQuery()
          Returns the current Expression being manipulated, which is either the top-level query or a subquery.
 DeclarationResolver getDeclarationResolver()
          Returns the DeclarationResolver of the current query's declaration.
 DeclarationResolver getDeclarationResolver(Expression expression)
          Returns the DeclarationResolver of the current query's declaration.
protected  DeclarationResolver getDeclarationResolverImp()
          Returns the DeclarationResolver of the current query's declaration.
 java.util.List<DeclarationResolver.Declaration> getDeclarations()
          Returns the ordered list of Declarations.
 IType getEnumType(java.lang.String enumTypeName)
          Returns the IType representing the possible given enum type.
 ExpressionRegistry getExpressionRegistry()
          Returns the registry containing the JPQLQueryBNFs and the ExpressionFactories that are used to properly parse a JPQL query.
 JPQLGrammar getGrammar()
          Returns the JPQL grammar that will be used to define how to parse a JPQL query.
protected  JPQLQueryContext.InputParameterVisitor getInputParameterVisitor()
           
 java.util.Collection<Join> getJoins(java.lang.String variableName)
          Returns the parsed representation of a JOIN and JOIN FETCH that were defined in the same declaration than the given range identification variable name.
 JPAVersion getJPAVersion()
          Returns the version of the Java Persistence to support, which dictates which version of the JPQL grammar to support.
 JPQLExpression getJPQLExpression()
          Returns the parsed tree representation of the JPQL query.
 java.lang.String getJPQLQuery()
          Returns the string representation of the JPQL query.
protected  LiteralVisitor getLiteralVisitor()
           
 IMapping getMapping(Expression expression)
          Returns the IMapping for the field represented by the given Expression.
 IType getParameterType(InputParameter inputParameter)
          Retrieves, if it can be determined, the type of the given InputParameter.
protected  ParameterTypeVisitor getParameterTypeVisitor()
           
 JPQLQueryContext getParent()
          Returns the parent context if the current context is not the root context.
 IManagedTypeProvider getProvider()
          Retrieves the provider of managed types.
 IQuery getQuery()
          Returns the external form of the JPQL query.
 Expression getQueryExpression(Expression expression)
          Retrieves the Expression representing the query statement (either the top-level query JPQLExpression or the subquery SimpleSelectStatement) owning the given Expression.
protected  JPQLQueryContext.QueryExpressionVisitor getQueryExpressionVisitor()
           
 Resolver getResolver(Expression expression)
          Creates or retrieved the cached Resolver for the given Expression.
 Resolver getResolver(java.lang.String variableName)
          Retrieves the Resolver mapped with the given identification variable.
protected  ResolverBuilder getResolverBuilder()
           
 java.util.Set<java.lang.String> getResultVariables()
          Returns the variables that got defined in the select expression.
 IType getType(java.lang.Class<?> type)
          Retrieves the external type for the given Java type.
 IType getType(Expression expression)
          Returns the IType of the given Expression.
 IType getType(java.lang.String typeName)
          Retrieves the external class with the given fully qualified class name.
 ITypeDeclaration getTypeDeclaration(Expression expression)
          Returns the ITypeDeclaration of the field handled by this Resolver.
 TypeHelper getTypeHelper()
          Returns a helper that gives access to the most common types.
 ITypeRepository getTypeRepository()
          Returns the type repository for the application.
 boolean hasJoins()
          Determines whether the JPQL expression has JOIN expressions.
protected  void initialize(JPQLGrammar jpqlGrammar)
          Initializes this JPQLQueryContext.
protected  void initializeRoot()
           
 boolean isCollectionIdentificationVariable(java.lang.String variableName)
          Determines whether the given identification variable is defining a join or a collection member declaration expressions.
 boolean isRangeIdentificationVariable(java.lang.String variableName)
          Determines whether the given variable name is an identification variable name used to define an abstract schema name.
 boolean isResultVariable(java.lang.String variable)
          Determines if the given variable is a result variable.
 boolean isSubquery()
          Determines whether this JPQLQueryContext currently holds the information of a subquery or for the top-level query.
 java.lang.String literal(Expression expression, LiteralType type)
          Retrieves the "literal" from the given Expression.
 void newSubqueryContext(Expression currentQuery)
          Changes the state of this context to use the given subquery.
 void setJPQLExpression(JPQLExpression jpqlExpression)
          Sets the parsed tree representation of the JPQL query.
 void setQuery(IQuery query)
          Sets the external form of the JPQL query, which will be parsed and information will be extracted for later access.
protected  void store(JPQLQueryContext parent, Expression currentQuery)
          Stores the information contained in the given parent into this one.
 java.lang.String toString()
          
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

currentContext

protected JPQLQueryContext currentContext
The current JPQLQueryContext is the context used for the current query or subquery. If the current context is not the global context, then its parent is non null.


parent

protected JPQLQueryContext parent
When this context is a sub-context used for a subquery, then this is the context for the parent query.

Constructor Detail

JPQLQueryContext

public JPQLQueryContext(JPQLGrammar jpqlGrammar)
Creates a new JPQLQueryContext.

Parameters:
jpqlGrammar - The JPQLGrammar defines how to parse a JPQL query

JPQLQueryContext

protected JPQLQueryContext(JPQLQueryContext parent,
                           Expression currentQuery)
Creates a new sub-JPQLQueryContext.

Parameters:
parent - The parent context
currentQuery - The parsed tree representation of the subquery
Method Detail

buildDeclarationResolver

protected DeclarationResolver buildDeclarationResolver()

buildDeclarationResolver

protected DeclarationResolver buildDeclarationResolver(DeclarationResolver parent)

buildInputParameter

protected JPQLQueryContext.InputParameterVisitor buildInputParameter()

buildJPQLQueryContext

protected abstract JPQLQueryContext buildJPQLQueryContext(JPQLQueryContext currentContext,
                                                          Expression currentQuery)

buildLiteralVisitor

protected abstract LiteralVisitor buildLiteralVisitor()

buildParameterTypeVisitor

protected ParameterTypeVisitor buildParameterTypeVisitor()

buildQueryExpressionVisitor

protected JPQLQueryContext.QueryExpressionVisitor buildQueryExpressionVisitor()

buildResolverBuilder

protected abstract ResolverBuilder buildResolverBuilder()

convertUnqualifiedDeclaration

public void convertUnqualifiedDeclaration(DeclarationResolver.Declaration declaration)
Converts the given DeclarationResolver.Declaration from being set as a range variable declaration to a path expression declaration.

In this query "UPDATE Employee SET firstName = 'MODIFIED' WHERE (SELECT COUNT(m) FROM managedEmployees m) > 0" managedEmployees is an unqualified collection-valued path expression (employee.managedEmployees).

Parameters:
declaration - The DeclarationResolver.Declaration that was parsed to range over an abstract schema name but is actually ranging over a path expression

dispose

public void dispose()
Disposes the internal data.


disposeSubqueryContext

public void disposeSubqueryContext()
Disposes this context, which is the current context being used by a subquery. Once it is disposed, any information retrieved will be for the subquery's parent query.


findInputParameters

public java.util.Collection<InputParameter> findInputParameters(java.lang.String parameterName)
Retrieves all the InputParameters with the given parameter name.

Parameters:
parameterName - The parameter used to find the InputParameters with the same value
Returns:
Either the InputParameters that has the given parameter or an empty collection

getActualCurrentQuery

public Expression getActualCurrentQuery()
Returns the current Expression being manipulated, which is either the top-level query or a subquery.

Returns:
Either the top-level query or a subquery

getActualDeclarationResolver

public DeclarationResolver getActualDeclarationResolver()
Returns the DeclarationResolver of this context and not from the current query's declaration.

Returns:
The DeclarationResolver for this context

getCurrentContext

public JPQLQueryContext getCurrentContext()
Returns the current JPQLQueryContext, i.e. the context of the query being manipulated, which can either be the top-level query or a subquery.

Returns:
The active context

getCurrentQuery

public Expression getCurrentQuery()
Returns the current Expression being manipulated, which is either the top-level query or a subquery.

Returns:
Either the top-level query or a subquery

getDeclarationResolver

public DeclarationResolver getDeclarationResolver()
Returns the DeclarationResolver of the current query's declaration. For a SELECT query, it contains the information defined in the FROM clause. For DELETE and UPDATE queries, it contains a single range declaration variable. If the current query is a subquery, then it contains the information defined in the FROM clause.

Returns:
The DeclarationResolver for the current query being visited

getDeclarationResolver

public DeclarationResolver getDeclarationResolver(Expression expression)
Returns the DeclarationResolver of the current query's declaration. For a SELECT query, it contains the information defined in the FROM clause. For DELETE and UPDATE queries, it contains a single range variable declaration. If the current query is a subquery, then it contains the information defined in the subquery FROM clause.

Parameters:
expression - The Expression that will be used to retrieve its query expression, i.e. either JPQLExpression or SimpleSelectStatement
Returns:
The DeclarationResolver for the current query being visited

getDeclarationResolverImp

protected DeclarationResolver getDeclarationResolverImp()
Returns the DeclarationResolver of the current query's declaration.

Returns:
The DeclarationResolver for the current query being visited

getDeclarations

public java.util.List<DeclarationResolver.Declaration> getDeclarations()
Returns the ordered list of Declarations.

Returns:
The Declarations of the current query that was parsed

getEnumType

public IType getEnumType(java.lang.String enumTypeName)
Returns the IType representing the possible given enum type. If the type name

Parameters:
enumTypeName - The fully qualified enum type with the constant
Returns:
The external form for the given Enum type

getExpressionRegistry

public ExpressionRegistry getExpressionRegistry()
Returns the registry containing the JPQLQueryBNFs and the ExpressionFactories that are used to properly parse a JPQL query.

Returns:
The registry containing the information related to the JPQL grammar

getGrammar

public JPQLGrammar getGrammar()
Returns the JPQL grammar that will be used to define how to parse a JPQL query.

Returns:
The grammar that was used to parse this Expression

getInputParameterVisitor

protected JPQLQueryContext.InputParameterVisitor getInputParameterVisitor()

getJoins

public java.util.Collection<Join> getJoins(java.lang.String variableName)
Returns the parsed representation of a JOIN and JOIN FETCH that were defined in the same declaration than the given range identification variable name.

Parameters:
variableName - The name of the identification variable that should be used to define an abstract schema name
Returns:
The JOIN and JOIN FETCH expressions used in the same declaration or an empty collection if none was defined

getJPAVersion

public JPAVersion getJPAVersion()
Returns the version of the Java Persistence to support, which dictates which version of the JPQL grammar to support.

Returns:
The version of the supported Java Persistence functional specification

getJPQLExpression

public JPQLExpression getJPQLExpression()
Returns the parsed tree representation of the JPQL query.

Returns:
The parsed tree representation of the JPQL query

getJPQLQuery

public java.lang.String getJPQLQuery()
Returns the string representation of the JPQL query.

Returns:
The string representation of the JPQL query

getLiteralVisitor

protected LiteralVisitor getLiteralVisitor()

getMapping

public IMapping getMapping(Expression expression)
Returns the IMapping for the field represented by the given Expression.

Parameters:
expression - The Expression representing a state field path expression or a collection-valued path expression
Returns:
Either the IMapping or null if none exists

getParameterType

public IType getParameterType(InputParameter inputParameter)
Retrieves, if it can be determined, the type of the given InputParameter. The type will be guessed based on its location within expression.

Note: Both named and positional input parameter can be used.

Parameters:
inputParameter - The InputParameter to retrieve its type
Returns:
Either the closest type of the input parameter or null if the type could not be determined

getParameterTypeVisitor

protected ParameterTypeVisitor getParameterTypeVisitor()

getParent

public JPQLQueryContext getParent()
Returns the parent context if the current context is not the root context.

Returns:
The parent context or null if the current context is the root

getProvider

public IManagedTypeProvider getProvider()
Retrieves the provider of managed types.

Returns:
The object that has access to the application's managed types.

getQuery

public IQuery getQuery()
Returns the external form of the JPQL query.

Returns:
The external form of the JPQL query

getQueryExpression

public Expression getQueryExpression(Expression expression)
Retrieves the Expression representing the query statement (either the top-level query JPQLExpression or the subquery SimpleSelectStatement) owning the given Expression.

Parameters:
expression - A child of the "root" Expression to retrieve
Returns:
The query statement that is the "root" parent of the given Expression

getQueryExpressionVisitor

protected JPQLQueryContext.QueryExpressionVisitor getQueryExpressionVisitor()

getResolver

public Resolver getResolver(Expression expression)
Creates or retrieved the cached Resolver for the given Expression. The Resolver can return the IType and ITypeDeclaration of the Expression and either the IManagedType or the IMapping.

Parameters:
expression - The Expression for which its Resolver will be retrieved
Returns:
Resolver for the given Expression

getResolver

public Resolver getResolver(java.lang.String variableName)
Retrieves the Resolver mapped with the given identification variable. If the identification is not defined in the declaration traversed by this resolver, than the search will traverse the parent hierarchy.

Parameters:
variableName - The identification variable that maps a Resolver
Returns:
The Resolver mapped with the given identification variable

getResolverBuilder

protected ResolverBuilder getResolverBuilder()

getResultVariables

public java.util.Set<java.lang.String> getResultVariables()
Returns the variables that got defined in the select expression. This only applies to JPQL queries built for JPA 2.0.

Returns:
The variables identifying the select expressions, if any was defined or an empty set if none were defined

getType

public IType getType(java.lang.Class<?> type)
Retrieves the external type for the given Java type.

Parameters:
type - The Java type to wrap with an external form
Returns:
The external form of the given type

getType

public IType getType(Expression expression)
Returns the IType of the given Expression.

Parameters:
expression - The Expression for which its type will be calculated
Returns:
Either the IType that was resolved by this Resolver or the IType for IType.UNRESOLVABLE_TYPE if it could not be resolved

getType

public IType getType(java.lang.String typeName)
Retrieves the external class with the given fully qualified class name.

Parameters:
typeName - The fully qualified class name of the class to retrieve
Returns:
The external form of the class to retrieve

getTypeDeclaration

public ITypeDeclaration getTypeDeclaration(Expression expression)
Returns the ITypeDeclaration of the field handled by this Resolver.

Parameters:
expression - The Expression for which its type declaration will be calculated
Returns:
Either the ITypeDeclaration that was resolved by this Resolver or the ITypeDeclaration for IType.UNRESOLVABLE_TYPE if it could not be resolved

getTypeHelper

public TypeHelper getTypeHelper()
Returns a helper that gives access to the most common types.

Returns:
A helper containing a collection of methods related to IType

getTypeRepository

public ITypeRepository getTypeRepository()
Returns the type repository for the application.

Returns:
The repository of ITypes

hasJoins

public boolean hasJoins()
Determines whether the JPQL expression has JOIN expressions.

Returns:
true if the query or subquery being traversed contains JOIN expressions; false otherwise

initialize

protected void initialize(JPQLGrammar jpqlGrammar)
Initializes this JPQLQueryContext.

Parameters:
jpqlGrammar - The grammar that defines how to parse a JPQL query

initializeRoot

protected void initializeRoot()

isCollectionIdentificationVariable

public boolean isCollectionIdentificationVariable(java.lang.String variableName)
Determines whether the given identification variable is defining a join or a collection member declaration expressions.

Parameters:
variableName - The identification variable to check for what it maps
Returns:
true if the given identification variable maps a collection-valued field defined in a JOIN or IN expression; false if it's not defined or it's mapping an abstract schema name

isRangeIdentificationVariable

public boolean isRangeIdentificationVariable(java.lang.String variableName)
Determines whether the given variable name is an identification variable name used to define an abstract schema name.

Parameters:
variableName - The name of the variable to verify if it's defined in a range variable declaration in the current query or any parent query
Returns:
true if the variable name is mapping an abstract schema name; false if it's defined in a collection member declaration

isResultVariable

public boolean isResultVariable(java.lang.String variable)
Determines if the given variable is a result variable.

Parameters:
variable - The variable to check if it's a result variable
Returns:
true if the given variable is defined as a result variable; false otherwise

isSubquery

public boolean isSubquery()
Determines whether this JPQLQueryContext currently holds the information of a subquery or for the top-level query.

Returns:
true if the current context is for a subquery; false for the top-level query

literal

public java.lang.String literal(Expression expression,
                                LiteralType type)
Retrieves the "literal" from the given Expression. The literal to retrieve depends on the given type. The literal is basically a string value like an identification variable name, an input parameter, a path expression, an abstract schema name, etc.

Parameters:
expression - The Expression to visit
type - The LiteralType helps to determine what to retrieve from the visited Expression
Returns:
A value from the given Expression or an empty string if the given Expression and the LiteralType do not match

newSubqueryContext

public void newSubqueryContext(Expression currentQuery)
Changes the state of this context to use the given subquery.

Parameters:
currentQuery - The parsed tree representation of the subquery that will become the current query
See Also:
disposeSubqueryContext()

setJPQLExpression

public void setJPQLExpression(JPQLExpression jpqlExpression)
Sets the parsed tree representation of the JPQL query. If the expression was parsed outside of the scope of this context, then this method has to be invoked before setQuery(IQuery) because the JPQL query is automatically parsed by that method.

Parameters:
jpqlExpression - The parsed representation of the JPQL query to manipulate
See Also:
setQuery(IQuery)

setQuery

public void setQuery(IQuery query)
Sets the external form of the JPQL query, which will be parsed and information will be extracted for later access.

Parameters:
query - The external form of the JPQL query
See Also:
setJPQLExpression(JPQLExpression)

store

protected void store(JPQLQueryContext parent,
                     Expression currentQuery)
Stores the information contained in the given parent into this one.

Parameters:
parent - The parent context, which is the context of the parent query
currentQuery - The subquery becoming the current query

toString

public java.lang.String toString()

Overrides:
toString in class java.lang.Object

EclipseLink 2.4.2, build 'v20130514-5956486' API Reference