Top Description Fields Constructors Methods
org.eclipse.persistence.jpa.jpql.tools

public abstract Class AbstractJPQLQueryHelper

extends Object
Class Inheritance
Known Direct Subclasses
org.eclipse.persistence.jpa.jpql.tools.DefaultJPQLQueryHelper, org.eclipse.persistence.jpa.jpql.tools.EclipseLinkJPQLQueryHelper
Annotations
@SuppressWarnings:nls
Imports
java.util.Collection, .Comparator, .LinkedList, .List, .TreeSet, org.eclipse.persistence.jpa.jpql.AbstractGrammarValidator, .AbstractSemanticValidator, .Assert, .JPQLQueryProblem, org.eclipse.persistence.jpa.jpql.parser.Expression, .InputParameter, .JPQLExpression, .JPQLGrammar, org.eclipse.persistence.jpa.jpql.tools.spi.IManagedTypeProvider, .IQuery, .IType, .ITypeRepository

This helper can perform the following operations over a JPQL 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.

Author
Pascal Filion
Since
2.3
Version
2.5

Field Summary

Modifier and TypeField and Description
private AbstractContentAssistVisitor
contentAssistVisitor

This visitor is responsible to gather the possible proposals based on the position of the caret within the JPQL query.

private AbstractGrammarValidator
grammarValidator

This visitor is responsible to visit the entire parsed tree representation of the JPQL query and to validate its content based on the JPQL grammar.

private JPQLGrammar
jpqlGrammar

The JPQLGrammar that will determine how to parse JPQL queries.

private JPQLQueryContext
queryContext

The context used to query information about the JPQL query.

private AbstractSemanticValidator
semanticValidator

This visitor is responsible to visit the entire parsed tree representation of the JPQL query and to validate the semantic of the information.

Constructor Summary

AccessConstructor and Description
public
AbstractJPQLQueryHelper(JPQLGrammar
The JPQLGrammar that will determine how to parse JPQL queries
jpqlGrammar
)

Creates a new AbstractJPQLQueryHelper.

protected
AbstractJPQLQueryHelper(JPQLQueryContext
The context used to query information about the JPQL query
queryContext
)

Creates a new AbstractJPQLQueryHelper.

Method Summary

Modifier and TypeMethod and Description
public abstract BasicRefactoringTool

Returns:

The concrete instance of RefactoringTool
buildBasicRefactoringTool
()

Creates the concrete instance of the tool that can refactor the content of a JPQL query.

public ContentAssistProposals

Returns:

The list of valid proposals regrouped by categories
buildContentAssistProposals
(int
The position within the query for which a list of possible choices are created for completing the query
position
)

Retrieves the possibles choices that can complete the query from the given position within the query.

public ContentAssistProposals

Returns:

The list of valid proposals regrouped by categories
buildContentAssistProposals
(int
The position within the query for which a list of possible choices are created for completing the query
position
,
ContentAssistExtension
This extension can be used to provide additional information that is outside the scope of simply providing JPA metadata information, such as table names, column names, class names
extension
)

Retrieves the possibles choices that can complete the query from the given position within the query.

protected abstract AbstractContentAssistVisitor

Returns:

A new concrete instance of AbstractContentAssistVisitor
buildContentAssistVisitor
(JPQLQueryContext
The context used to query information about the JPQL query
queryContext
)

Creates the concrete instance of the content assist visitor that will give the possible choices based on the position of the cursor within the JPQL query.

protected abstract AbstractGrammarValidator

Returns:

A new concrete instance of AbstractGrammarValidator
buildGrammarValidator
(JPQLGrammar
The context used to query information about the JPQL query
jpqlGrammar
)

Creates the concrete instance of the validator that will grammatically validate the JPQL query.

protected abstract JPQLQueryContext

Returns:

A new JPQLQueryContext
buildJPQLQueryContext
(JPQLGrammar
The JPQL grammar that is required for dictating how the JPQL query will be parsed. It is also used by validation and by the content assist
jpqlGrammar
)

Creates a context that will be used to store and retrieve information about the JPQL query.

protected Comparator<IType>
buildNumericTypeComparator()

Creates the Comparator that can sort ITypes based on the numerical priority.

public abstract RefactoringTool

Returns:

The concrete instance of RefactoringTool
buildRefactoringTool
()

Creates the concrete instance of the tool that can refactor the content of a JPQL query.

protected abstract AbstractSemanticValidator

Returns:

A new concrete instance of AbstractSemanticValidator
buildSemanticValidator
(JPQLQueryContext
The context used to query information about the JPQL query
queryContext
)

Creates the concrete instance of the validator that will semantically validate the JPQL query.

public void
dispose()

Disposes of the internal data.

protected AbstractContentAssistVisitor

Returns:

A concrete instance of AbstractContentAssistVisitor
getContentAssistVisitor
()

Returns the visitor that can visit a JPQL query and based on the position of the cursor within the JPQL query and determines the valid proposals.

public JPQLGrammar

Returns:

The grammar that was used to parse this Expression
getGrammar
()

Returns the JPQL grammar that will be used to define how to parse a JPQL query.

protected AbstractGrammarValidator
public JPQLExpression

Returns:

The parsed JPQL query
getJPQLExpression
()

Returns the root of the parsed tree representation of the JPQL query.

public IType

Returns:

Either the closest type of the input parameter or null if the type couldn't be determined
getParameterType
(String
The name of the input parameter to retrieve its type, which needs to be prepended by ':' or '?'
parameterName
)

Retrieves, if it can be determined, the type of the given input parameter with the given name.

public String

Returns:

The string created from the parsed tree representation of the original JPQL query
getParsedJPQLQuery
()

Returns the string representation of the parsed tree.

public IManagedTypeProvider

Returns:

The container of managed types
getProvider
()

Returns the provider for managed types (entities, embeddables, mapped superclasses).

public IQuery

Returns:

The external form representing a named query
getQuery
()

Returns the external form representing a named query.

public JPQLQueryContext

Returns:

The JPQLQueryContext that contains information contained in the JPQL query
getQueryContext
()

Returns the JPQLQueryContext that contains information about the JPQL query.

public IType

Returns:

The result type of the JPQL query if it could accurately be calculated or the IType for Object if it could not be calculated
getResultType
()

Calculates the type of the query result of the JPQL query.

protected AbstractSemanticValidator
public IType

Returns:

The external form for the given Java type
getType
(Class<?>
The Java type for which its external form is requested
type
)

Returns the IType representing the given Java type.

public TypeHelper

Returns:

A helper containing a collection of methods related to IType
getTypeHelper
()

Returns a helper that gives access to the most common types.

public ITypeRepository

Returns:

The repository for classes, interfaces, enum types and annotations
getTypeRepository
()

Returns the repository that gives access to the application's types.

public void
setJPQLExpression(JPQLExpression
The parsed representation of the JPQL query to manipulate
jpqlExpression
)

Sets the parsed tree representation of the JPQL query.

public void
setQuery(IQuery
The external form of the JPQL query
query
)

Sets the external form of the JPQL query, which will be parsed and information will be extracted for later access.

public List<JPQLQueryProblem>

Returns:

The non-null list that will be used to store the problems if any was found
validate
()

Validates the query by introspecting it grammatically and semantically.

public void
validate(Expression
The parsed tree representation of the JPQL fragment to validate
expression
,
List<JPQLQueryProblem>
A non-null list that will be used to store the problems if any was found
problems
)

Validates the query by introspecting it grammatically and semantically.

public List<JPQLQueryProblem>

Returns:

The non-null list that will be used to store the problems if any was found
validateGrammar
()

Validates the query by only introspecting it grammatically.

public void
validateGrammar(Expression
The parsed tree representation of the query
expression
,
List<JPQLQueryProblem>
A non-null list that will be used to store the problems if any was found
problems
)

Validates the query by only introspecting it grammatically.

public List<JPQLQueryProblem>

Returns:

The non-null list that will be used to store the problems if any was found
validateSemantic
()

Validates the query by only introspecting it semantically.

public void
validateSemantic(Expression
The parsed tree representation of the query
expression
,
List<JPQLQueryProblem>
A non-null list that will be used to store the problems if any was found
problems
)

Validates the query by only introspecting it semantically.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

contentAssistVisitorback to summary
private AbstractContentAssistVisitor contentAssistVisitor

This visitor is responsible to gather the possible proposals based on the position of the caret within the JPQL query.

grammarValidatorback to summary
private AbstractGrammarValidator grammarValidator

This visitor is responsible to visit the entire parsed tree representation of the JPQL query and to validate its content based on the JPQL grammar.

jpqlGrammarback to summary
private JPQLGrammar jpqlGrammar

The JPQLGrammar that will determine how to parse JPQL queries.

queryContextback to summary
private JPQLQueryContext queryContext

The context used to query information about the JPQL query.

semanticValidatorback to summary
private AbstractSemanticValidator semanticValidator

This visitor is responsible to visit the entire parsed tree representation of the JPQL query and to validate the semantic of the information.

Constructor Detail

AbstractJPQLQueryHelperback to summary
public AbstractJPQLQueryHelper(JPQLGrammar jpqlGrammar)

Creates a new AbstractJPQLQueryHelper.

Parameters
jpqlGrammar:JPQLGrammar

The JPQLGrammar that will determine how to parse JPQL queries

AbstractJPQLQueryHelperback to summary
protected AbstractJPQLQueryHelper(JPQLQueryContext queryContext)

Creates a new AbstractJPQLQueryHelper.

Parameters
queryContext:JPQLQueryContext

The context used to query information about the JPQL query

Exceptions
NullPointerException:
The JPQLQueryContext cannot be null

Method Detail

buildBasicRefactoringToolback to summary
public abstract BasicRefactoringTool buildBasicRefactoringTool()

Creates the concrete instance of the tool that can refactor the content of a JPQL query. This version simply provides the delta of the refactoring operations.

Returns:BasicRefactoringTool

The concrete instance of RefactoringTool

Since
2.5
See Also
buildRefactoringTool
buildContentAssistProposalsback to summary
public ContentAssistProposals buildContentAssistProposals(int position)

Retrieves the possibles choices that can complete the query from the given position within the query.

Note

Disposing of the internal data is not done automatically.

Parameters
position:int

The position within the query for which a list of possible choices are created for completing the query

Returns:ContentAssistProposals

The list of valid proposals regrouped by categories

buildContentAssistProposalsback to summary
public ContentAssistProposals buildContentAssistProposals(int position, ContentAssistExtension extension)

Retrieves the possibles choices that can complete the query from the given position within the query.

Note

Disposing of the internal data is not done automatically.

Parameters
position:int

The position within the query for which a list of possible choices are created for completing the query

extension:ContentAssistExtension

This extension can be used to provide additional information that is outside the scope of simply providing JPA metadata information, such as table names, column names, class names

Returns:ContentAssistProposals

The list of valid proposals regrouped by categories

Since
2.5
buildContentAssistVisitorback to summary
protected abstract AbstractContentAssistVisitor buildContentAssistVisitor(JPQLQueryContext queryContext)

Creates the concrete instance of the content assist visitor that will give the possible choices based on the position of the cursor within the JPQL query.

Parameters
queryContext:JPQLQueryContext

The context used to query information about the JPQL query

Returns:AbstractContentAssistVisitor

A new concrete instance of AbstractContentAssistVisitor

buildGrammarValidatorback to summary
protected abstract AbstractGrammarValidator buildGrammarValidator(JPQLGrammar jpqlGrammar)

Creates the concrete instance of the validator that will grammatically validate the JPQL query.

Parameters
jpqlGrammar:JPQLGrammar

The context used to query information about the JPQL query

Returns:AbstractGrammarValidator

A new concrete instance of AbstractGrammarValidator

buildJPQLQueryContextback to summary
protected abstract JPQLQueryContext buildJPQLQueryContext(JPQLGrammar jpqlGrammar)

Creates a context that will be used to store and retrieve information about the JPQL query.

Parameters
jpqlGrammar:JPQLGrammar

The JPQL grammar that is required for dictating how the JPQL query will be parsed. It is also used by validation and by the content assist

Returns:JPQLQueryContext

A new JPQLQueryContext

buildNumericTypeComparatorback to summary
protected Comparator<IType> buildNumericTypeComparator()

Creates the Comparator that can sort ITypes based on the numerical priority.

Returns:Comparator<IType>

NumericTypeComparator

buildRefactoringToolback to summary
public abstract RefactoringTool buildRefactoringTool()

Creates the concrete instance of the tool that can refactor the content of a JPQL query. This version provides a way to manipulate the editable version of the JPQL query (StateObject and simply outputs the result of the refactoring operations, i.e. the updated JPQL query).

Returns:RefactoringTool

The concrete instance of RefactoringTool

Since
2.4
See Also
buildBasicRefactoringTool()
buildSemanticValidatorback to summary
protected abstract AbstractSemanticValidator buildSemanticValidator(JPQLQueryContext queryContext)

Creates the concrete instance of the validator that will semantically validate the JPQL query.

Parameters
queryContext:JPQLQueryContext

The context used to query information about the JPQL query

Returns:AbstractSemanticValidator

A new concrete instance of AbstractSemanticValidator

disposeback to summary
public void dispose()

Disposes of the internal data.

getContentAssistVisitorback to summary
protected AbstractContentAssistVisitor getContentAssistVisitor()

Returns the visitor that can visit a JPQL query and based on the position of the cursor within the JPQL query and determines the valid proposals.

Returns:AbstractContentAssistVisitor

A concrete instance of AbstractContentAssistVisitor

See Also
buildContentAssistVisitor(JPQLQueryContext)
getGrammarback to summary
public JPQLGrammar getGrammar()

Returns the JPQL grammar that will be used to define how to parse a JPQL query.

Returns:JPQLGrammar

The grammar that was used to parse this Expression

Since
2.4
getGrammarValidatorback to summary
protected AbstractGrammarValidator getGrammarValidator()
getJPQLExpressionback to summary
public JPQLExpression getJPQLExpression()

Returns the root of the parsed tree representation of the JPQL query.

Returns:JPQLExpression

The parsed JPQL query

getParameterTypeback to summary
public IType getParameterType(String parameterName)

Retrieves, if it can be determined, the type of the given input parameter with the given name. The type will be guessed based on its location within expression.

Note

Both named and positional input parameter can be used.

Parameters
parameterName:String

The name of the input parameter to retrieve its type, which needs to be prepended by ':' or '?'

Returns:IType

Either the closest type of the input parameter or null if the type couldn't be determined

getParsedJPQLQueryback to summary
public String getParsedJPQLQuery()

Returns the string representation of the parsed tree.

Returns:String

The string created from the parsed tree representation of the original JPQL query

getProviderback to summary
public IManagedTypeProvider getProvider()

Returns the provider for managed types (entities, embeddables, mapped superclasses).

Returns:IManagedTypeProvider

The container of managed types

getQueryback to summary
public IQuery getQuery()

Returns the external form representing a named query.

Returns:IQuery

The external form representing a named query

getQueryContextback to summary
public JPQLQueryContext getQueryContext()

Returns the JPQLQueryContext that contains information about the JPQL query.

Returns:JPQLQueryContext

The JPQLQueryContext that contains information contained in the JPQL query

getResultTypeback to summary
public IType getResultType()

Calculates the type of the query result of the JPQL query.

See Resolver to understand how the type is calculated.

Returns:IType

The result type of the JPQL query if it could accurately be calculated or the IType for Object if it could not be calculated

getSemanticValidatorback to summary
protected AbstractSemanticValidator getSemanticValidator()
getTypeback to summary
public IType getType(Class<?> type)

Returns the IType representing the given Java type.

Parameters
type:Class<?>

The Java type for which its external form is requested

Returns:IType

The external form for the given Java type

getTypeHelperback to summary
public TypeHelper getTypeHelper()

Returns a helper that gives access to the most common types.

Returns:TypeHelper

A helper containing a collection of methods related to IType

getTypeRepositoryback to summary
public ITypeRepository getTypeRepository()

Returns the repository that gives access to the application's types.

Returns:ITypeRepository

The repository for classes, interfaces, enum types and annotations

setJPQLExpressionback to summary
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:JPQLExpression

The parsed representation of the JPQL query to manipulate

See Also
setQuery(IQuery)
setQueryback to summary
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:IQuery

The external form of the JPQL query

validateback to summary
public List<JPQLQueryProblem> validate()

Validates the query by introspecting it grammatically and semantically.

Returns:List<JPQLQueryProblem>

The non-null list that will be used to store the problems if any was found

validateback to summary
public void validate(Expression expression, List<JPQLQueryProblem> problems)

Validates the query by introspecting it grammatically and semantically.

Parameters
expression:Expression

The parsed tree representation of the JPQL fragment to validate

problems:List<JPQLQueryProblem>

A non-null list that will be used to store the problems if any was found

validateGrammarback to summary
public List<JPQLQueryProblem> validateGrammar()

Validates the query by only introspecting it grammatically.

Returns:List<JPQLQueryProblem>

The non-null list that will be used to store the problems if any was found

validateGrammarback to summary
public void validateGrammar(Expression expression, List<JPQLQueryProblem> problems)

Validates the query by only introspecting it grammatically.

Parameters
expression:Expression

The parsed tree representation of the query

problems:List<JPQLQueryProblem>

A non-null list that will be used to store the problems if any was found

validateSemanticback to summary
public List<JPQLQueryProblem> validateSemantic()

Validates the query by only introspecting it semantically.

Returns:List<JPQLQueryProblem>

The non-null list that will be used to store the problems if any was found

validateSemanticback to summary
public void validateSemantic(Expression expression, List<JPQLQueryProblem> problems)

Validates the query by only introspecting it semantically.

Parameters
expression:Expression

The parsed tree representation of the query

problems:List<JPQLQueryProblem>

A non-null list that will be used to store the problems if any was found