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

public Class ExpressionRegistry

extends Object
Class Inheritance
Annotations
@SuppressWarnings:nls
Imports
java.util.Arrays, .Collections, .HashMap, .Locale, .Map, .Set, org.eclipse.persistence.jpa.jpql.Assert, .JPAVersion
This registry contains the necessary information used by Hermes parser. When parsing a JPQL query, the JPQLGrammar given to JPQLExpression will give access to this registry.

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.4
Version
2.5
See Also
JPQLGrammar, ExpressionFactory, JPQLQueryBNF

Field Summary

Modifier and TypeField and Description
private Map<String, ExpressionFactory>
expressionFactories

The map of ExpressionFactories that have been registered and required for parsing a JPQL query, they are mapped with their unique identifier.

private Map<String, IdentifierRole>
identifiers

The set of the JPQL identifiers defined by the grammar.

private Map<String, JPAVersion>
identifierVersions

This table specify in which JPA version the identifiers was introduced.

private Map<String, JPQLQueryBNF>
queryBNFs

The JPQLQueryBNF unique identifiers mapped to the only instance of the BNF rule.

Constructor Summary

AccessConstructor and Description
public
ExpressionRegistry()

Creates the only instance of ExpressionRegistry.

Method Summary

Modifier and TypeMethod and Description
public void
addChildBNF(String
The unique identifier of the parent BNF to add a child BNF
queryBNFId, String
The unique identifier of the child to add to the parent BNF
childQueryBNFId)

Adds to the given query BNF a child BNF.

public void
addChildFactory(String
The unique identifier of the parent BNF
queryBNFId, String
The unique identifier of the ExpressionFactory to add to the given query BNF
childExpressionFactoryId)

Adds to the given unique identifier of an ExpressionFactory to the given query BNF.

public void
addIdentifier(String
The unique identifier of the ExpressionFactory to add more JPQL identifiers
expressionFactoryId, String
The JPQL identifier this factory will parse
identifier)

Adds the given JPQL identifier to this factory.

public void
addIdentifiers(String
The unique identifier of the ExpressionFactory to add more JPQL identifiers
expressionFactoryId, String...
The JPQL identifiers this factory will parse
identifiers)

Adds the given JPQL identifiers to this factory.

public ExpressionFactory

Returns:

Either the ExpressionFactory that creates the Expression or null if none was found
expressionFactoryForIdentifier(String
The JPQL identifier for which its factory is searched
identifier)

Retrieves the ExpressionFactory that is responsible for creating the Expression object that represents the given JPQL identifier.

public ExpressionFactory

Returns:

The ExpressionFactory mapped with the given unique identifier
getExpressionFactory(String
The unique identifier of the ExpressionFactory to retrieve
expressionFactoryId)

Retrieves the registered ExpressionFactory that was registered for the given unique identifier.

public IdentifierRole

Returns:

The IdentifierRole of the given JPQL identifier
getIdentifierRole(String
The JPQL identifier for which its role is returned
identifier)

Retrieves the IdentifierRole of the given JPQL identifier.

public Set<String>

Returns:

The supported JPQL identifiers
getIdentifiers()

Returns the JPQL identifiers that are supported by the JPQL grammar.

public Iterable<String>

Returns:

The list of JPQL identifiers that are supported by a BNF rule
getIdentifiers(String queryBNFId)

Retrieves the JPQL identifiers that are supported by the BNF rule with the given unique identifier.

public JPAVersion

Returns:

The version in which the identifier was introduced
getIdentifierVersion(String identifier)

Retrieves the JPA version in which the identifier was first introduced.

public JPQLQueryBNF

Returns:

The JPQLQueryBNF representing a section of the grammar
getQueryBNF(String
The unique identifier of the JPQLQueryBNF to retrieve
queryBNFId)

Retrieves the BNF object that was registered for the given unique identifier.

protected void
initialize()

Instantiates the only instance of various API used by the parser.

public boolean

Returns:

true if the word is an identifier, false otherwise
isIdentifier(String
The string value to test if it's a JPQL identifier based on what is registered with this ExpressionRegistry
text)

Determines if the given word is a JPQL identifier.

public void
registerBNF(JPQLQueryBNF
The JPQLQueryBNF to store
queryBNF)

Registers the given JPQLQueryBNF.

public void
registerFactory(ExpressionFactory
The ExpressionFactory to store
expressionFactory)

Registers the given ExpressionFactory by storing it for all its identifiers.

public void
registerIdentifierRole(String
The JPQL identifier to register its role within a JPQL query
identifier, IdentifierRole
The role of the given JPQL identifier
role)

Registers the IdentifierRole for the given JPQL identifier.

public void
registerIdentifierVersion(String
The JPQL identifier to register in which version it was added to the grammar
identifier, JPAVersion
The version when the JPQL identifier was added to the grammar
version)

Registers the JPAVersion for which the given JPQL identifier was defined.

public void
setFallbackBNFId(String
The unique identifier of the BNF to modify its fallback BNF unique identifier
queryBNFId, String
The unique identifier of the JPQLQueryBNF to use in the last resort
fallbackBNFId)

When parsing the query and no JPQLQueryBNFs can help to parse the query, then it will fall back on the given one.

public void
setFallbackExpressionFactoryId(String
The unique identifier of the BNF to modify its fallback expression factory unique identifier
queryBNFId, String fallbackExpressionFactoryId)

Sets the unique identifier of the ExpressionFactory to use when the fall back BNF ID is not null.

public void
setHandleCollection(String
The unique identifier of the JPQLQueryBNF
queryBNFId, boolean
true if the sub-expression to parse might have several sub-expressions separated by commas; false otherwise
handleCollection)

Determines whether the Expression handles a collection of sub-expressions that are separated by commas.

public void
setHandleNestedArray(String
The unique identifier of the JPQLQueryBNF
queryBNFId, boolean
true if the expression represented by this BNF can be a nested array; false otherwise
handleNestedArray)

Sets whether the BNF with the given ID supports nested array or not.

public void
setHandleSubExpression(String
The unique identifier of the JPQLQueryBNF
queryBNFId, boolean
true to let the creation of a sub-expression be created by the fallback ExpressionFactory registered with this BNF; false otherwise (which is the default value)
handleSubExpression)

Sets whether the query BNF with the given ID handles parsing a sub-expression, i.e. parsing an expression encapsulated by parenthesis.

public void
unregisterBNF(JPQLQueryBNF
The JPQLQueryBNF to unregister
queryBNF)

Unregisters the given JPQLQueryBNF.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

expressionFactoriesback to summary
private Map<String, ExpressionFactory> expressionFactories

The map of ExpressionFactories that have been registered and required for parsing a JPQL query, they are mapped with their unique identifier.

identifiersback to summary
private Map<String, IdentifierRole> identifiers

The set of the JPQL identifiers defined by the grammar.

identifierVersionsback to summary
private Map<String, JPAVersion> identifierVersions

This table specify in which JPA version the identifiers was introduced.

queryBNFsback to summary
private Map<String, JPQLQueryBNF> queryBNFs

The JPQLQueryBNF unique identifiers mapped to the only instance of the BNF rule.

Constructor Detail

ExpressionRegistryback to summary
public ExpressionRegistry()

Creates the only instance of ExpressionRegistry.

Method Detail

addChildBNFback to summary
public void addChildBNF(String queryBNFId, String childQueryBNFId)

Adds to the given query BNF a child BNF.

Parameters
queryBNFId:String

The unique identifier of the parent BNF to add a child BNF

childQueryBNFId:String

The unique identifier of the child to add to the parent BNF

Exceptions
NullPointerException:
The JPQLQueryBNF identified by the given ID does not exist
addChildFactoryback to summary
public void addChildFactory(String queryBNFId, String childExpressionFactoryId)

Adds to the given unique identifier of an ExpressionFactory to the given query BNF.

Parameters
queryBNFId:String

The unique identifier of the parent BNF

childExpressionFactoryId:String

The unique identifier of the ExpressionFactory to add to the given query BNF

Exceptions
NullPointerException:
The JPQLQueryBNF identified by the given ID does not exist
addIdentifierback to summary
public void addIdentifier(String expressionFactoryId, String identifier)

Adds the given JPQL identifier to this factory.

Parameters
expressionFactoryId:String

The unique identifier of the ExpressionFactory to add more JPQL identifiers

identifier:String

The JPQL identifier this factory will parse

addIdentifiersback to summary
public void addIdentifiers(String expressionFactoryId, String... identifiers)

Adds the given JPQL identifiers to this factory.

Parameters
expressionFactoryId:String

The unique identifier of the ExpressionFactory to add more JPQL identifiers

identifiers:String[]

The JPQL identifiers this factory will parse

expressionFactoryForIdentifierback to summary
public ExpressionFactory expressionFactoryForIdentifier(String identifier)

Retrieves the ExpressionFactory that is responsible for creating the Expression object that represents the given JPQL identifier.

Parameters
identifier:String

The JPQL identifier for which its factory is searched

Returns:ExpressionFactory

Either the ExpressionFactory that creates the Expression or null if none was found

getExpressionFactoryback to summary
public ExpressionFactory getExpressionFactory(String expressionFactoryId)

Retrieves the registered ExpressionFactory that was registered for the given unique identifier.

Parameters
expressionFactoryId:String

The unique identifier of the ExpressionFactory to retrieve

Returns:ExpressionFactory

The ExpressionFactory mapped with the given unique identifier

getIdentifierRoleback to summary
public IdentifierRole getIdentifierRole(String identifier)

Retrieves the IdentifierRole of the given JPQL identifier. A role helps to describe the purpose of the identifier in a JPQL query.

Parameters
identifier:String

The JPQL identifier for which its role is returned

Returns:IdentifierRole

The IdentifierRole of the given JPQL identifier

getIdentifiersback to summary
public Set<String> getIdentifiers()

Returns the JPQL identifiers that are supported by the JPQL grammar.

Returns:Set<String>

The supported JPQL identifiers

getIdentifiersback to summary
public Iterable<String> getIdentifiers(String queryBNFId)

Retrieves the JPQL identifiers that are supported by the BNF rule with the given unique identifier. The JPQL identifiers are retrieved by scanning the ExpressionFactory registered with the BNF rule and its child BNF rules.

Returns:Iterable<String>

The list of JPQL identifiers that are supported by a BNF rule

getIdentifierVersionback to summary
public JPAVersion getIdentifierVersion(String identifier)

Retrieves the JPA version in which the identifier was first introduced.

Returns:JPAVersion

The version in which the identifier was introduced

getQueryBNFback to summary
public JPQLQueryBNF getQueryBNF(String queryBNFId)

Retrieves the BNF object that was registered for the given unique identifier.

Parameters
queryBNFId:String

The unique identifier of the JPQLQueryBNF to retrieve

Returns:JPQLQueryBNF

The JPQLQueryBNF representing a section of the grammar

initializeback to summary
protected void initialize()

Instantiates the only instance of various API used by the parser.

isIdentifierback to summary
public boolean isIdentifier(String text)

Determines if the given word is a JPQL identifier. The check is case insensitive.

Parameters
text:String

The string value to test if it's a JPQL identifier based on what is registered with this ExpressionRegistry

Returns:boolean

true if the word is an identifier, false otherwise

registerBNFback to summary
public void registerBNF(JPQLQueryBNF queryBNF)

Registers the given JPQLQueryBNF. The BNF will be registered using its unique identifier.

Parameters
queryBNF:JPQLQueryBNF

The JPQLQueryBNF to store

Exceptions
NullPointerException:
The JPQLQueryBNF cannot be null
registerFactoryback to summary
public void registerFactory(ExpressionFactory expressionFactory)

Registers the given ExpressionFactory by storing it for all its identifiers.

Parameters
expressionFactory:ExpressionFactory

The ExpressionFactory to store

Exceptions
NullPointerException:
The ExpressionFactory cannot be null
registerIdentifierRoleback to summary
public void registerIdentifierRole(String identifier, IdentifierRole role)

Registers the IdentifierRole for the given JPQL identifier.

Parameters
identifier:String

The JPQL identifier to register its role within a JPQL query

role:IdentifierRole

The role of the given JPQL identifier

Exceptions
NullPointerException:
The JPQL identifier and the IdentifierRole cannot be null
registerIdentifierVersionback to summary
public void registerIdentifierVersion(String identifier, JPAVersion version)

Registers the JPAVersion for which the given JPQL identifier was defined.

Parameters
identifier:String

The JPQL identifier to register in which version it was added to the grammar

version:JPAVersion

The version when the JPQL identifier was added to the grammar

Exceptions
NullPointerException:
The JPQL identifier and the JPAVersion cannot be null
setFallbackBNFIdback to summary
public void setFallbackBNFId(String queryBNFId, String fallbackBNFId)

When parsing the query and no JPQLQueryBNFs can help to parse the query, then it will fall back on the given one.

Parameters
queryBNFId:String

The unique identifier of the BNF to modify its fallback BNF unique identifier

fallbackBNFId:String

The unique identifier of the JPQLQueryBNF to use in the last resort

Exceptions
NullPointerException:
The JPQLQueryBNF identified by the given ID does not exist
setFallbackExpressionFactoryIdback to summary
public void setFallbackExpressionFactoryId(String queryBNFId, String fallbackExpressionFactoryId)

Sets the unique identifier of the ExpressionFactory to use when the fall back BNF ID is not null. This will be used to parse a portion of the query when the registered expression factories cannot parse it.

Note

This method is only called if JPQLQueryBNF. getFallbackBNFId() does not return null.

Parameters
queryBNFId:String

The unique identifier of the BNF to modify its fallback expression factory unique identifier

Exceptions
NullPointerException:
The JPQLQueryBNF identified by the given ID does not exist
setHandleCollectionback to summary
public void setHandleCollection(String queryBNFId, boolean handleCollection)

Determines whether the Expression handles a collection of sub-expressions that are separated by commas.

Parameters
queryBNFId:String

The unique identifier of the JPQLQueryBNF

handleCollection:boolean

true if the sub-expression to parse might have several sub-expressions separated by commas; false otherwise

setHandleNestedArrayback to summary
public void setHandleNestedArray(String queryBNFId, boolean handleNestedArray)

Sets whether the BNF with the given ID supports nested array or not. A nested array is a sub- expression with its child being a collection expression: (item_1, item_2, ..., item_n).

Parameters
queryBNFId:String

The unique identifier of the JPQLQueryBNF

handleNestedArray:boolean

true if the expression represented by this BNF can be a nested array; false otherwise

Since
2.5
setHandleSubExpressionback to summary
public void setHandleSubExpression(String queryBNFId, boolean handleSubExpression)

Sets whether the query BNF with the given ID handles parsing a sub-expression, i.e. parsing an expression encapsulated by parenthesis. Which in fact would be handled by the fallback ExpressionFactory. The default behavior is to not handle it.

A good example for using this option is when an Expression cannot use any ExpressionFactory for creating a child object, parsing will use the fallback ExpressionFactory, if one was specified. So when this is set to true, the fallback ExpressionFactory will be immediately invoked.

Let's say we want to parse "SELECT e FROM (SELECT a FROM Address a) e", FromClause cannot use a factory for parsing the entity name (that's what usually the FROM clause has) so it uses the fallback factory to create IdentificationVariableDeclaration. Then IdentificationVariableDeclaration also cannot use any factory to create its child object so it uses the fallback factory to create RangeVariableDeclaration. By changing the status of for handling the sub-expression for the BNFs for those objects, then a subquery can be created by RangeVariableDeclaration. 

FromClause
 |- IdentificationVariableDeclaration
      |- RangeVariableDeclaration
           |- SubExpression(subquery)
In order to get this working, the following would have to be done into the grammar: 
 public class MyJPQLGrammar extends AbstractJPQLGrammar {
  @Override
  protected void initializeBNFs() {
     setHandleSubExpression(InternalFromClauseBNF.ID,                true);
     setHandleSubExpression(InternalSimpleFromClauseBNF.ID,          true);
     setHandleSubExpression(IdentificationVariableDeclarationBNF.ID, true);
     setHandleSubExpression(RangeVariableDeclarationBNF.ID,          true);
  }
}
Parameters
queryBNFId:String

The unique identifier of the JPQLQueryBNF

handleSubExpression:boolean

true to let the creation of a sub-expression be created by the fallback ExpressionFactory registered with this BNF; false otherwise (which is the default value)

unregisterBNFback to summary
public void unregisterBNF(JPQLQueryBNF queryBNF)

Unregisters the given JPQLQueryBNF.

Parameters
queryBNF:JPQLQueryBNF

The JPQLQueryBNF to unregister

Exceptions
NullPointerException:
The JPQLQueryBNF cannot be null