Class ExpressionRegistry
- java.lang.Object
-
- org.eclipse.persistence.jpa.jpql.parser.ExpressionRegistry
-
public class ExpressionRegistry extends java.lang.ObjectThis registry contains the necessary information used by Hermes parser. When parsing a JPQL query, theJPQLGrammargiven toJPQLExpressionwill 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.
- Version:
- 2.5
- See Also:
JPQLGrammar,ExpressionFactory,JPQLQueryBNF- Author:
- Pascal Filion
- Since:
- 2.4
-
-
Constructor Summary
Constructors Constructor Description ExpressionRegistry()Creates the only instance ofExpressionRegistry.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description voidaddChildBNF(java.lang.String queryBNFId, java.lang.String childQueryBNFId)Adds to the given query BNF a child BNF.voidaddChildFactory(java.lang.String queryBNFId, java.lang.String childExpressionFactoryId)Adds to the given unique identifier of anExpressionFactoryto the given query BNF.voidaddIdentifier(java.lang.String expressionFactoryId, java.lang.String identifier)Adds the given JPQL identifier to this factory.voidaddIdentifiers(java.lang.String expressionFactoryId, java.lang.String... identifiers)Adds the given JPQL identifiers to this factory.ExpressionFactoryexpressionFactoryForIdentifier(java.lang.String identifier)Retrieves theExpressionFactorythat is responsible for creating theExpressionobject that represents the given JPQL identifier.ExpressionFactorygetExpressionFactory(java.lang.String expressionFactoryId)Retrieves the registeredExpressionFactorythat was registered for the given unique identifier.IdentifierRolegetIdentifierRole(java.lang.String identifier)Retrieves theIdentifierRoleof the given JPQL identifier.java.util.Set<java.lang.String>getIdentifiers()Returns the JPQL identifiers that are supported by theJPQL grammar.java.lang.Iterable<java.lang.String>getIdentifiers(java.lang.String queryBNFId)Retrieves the JPQL identifiers that are supported by the BNF rule with the given unique identifier.JPAVersiongetIdentifierVersion(java.lang.String identifier)Retrieves the JPA version in which the identifier was first introduced.JPQLQueryBNFgetQueryBNF(java.lang.String queryBNFId)Retrieves the BNF object that was registered for the given unique identifier.protected voidinitialize()Instantiates the only instance of various API used by the parser.booleanisIdentifier(java.lang.String text)Determines if the given word is a JPQL identifier.voidregisterBNF(JPQLQueryBNF queryBNF)Registers the givenJPQLQueryBNF.voidregisterFactory(ExpressionFactory expressionFactory)Registers the givenExpressionFactoryby storing it for all its identifiers.voidregisterIdentifierRole(java.lang.String identifier, IdentifierRole role)Registers theIdentifierRolefor the given JPQL identifier.voidregisterIdentifierVersion(java.lang.String identifier, JPAVersion version)Registers theJPAVersionfor which the given JPQL identifier was defined.voidsetFallbackBNFId(java.lang.String queryBNFId, java.lang.String fallbackBNFId)When parsing the query and noJPQLQueryBNFscan help to parse the query, then it will fall back on the given one.voidsetFallbackExpressionFactoryId(java.lang.String queryBNFId, java.lang.String fallbackExpressionFactoryId)Sets the unique identifier of theExpressionFactoryto use when the fall back BNF ID is notnull.voidsetHandleCollection(java.lang.String queryBNFId, boolean handleCollection)Determines whether theExpressionhandles a collection of sub-expressions that are separated by commas.voidsetHandleNestedArray(java.lang.String queryBNFId, boolean handleNestedArray)Sets whether the BNF with the given ID supports nested array or not.voidsetHandleSubExpression(java.lang.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.voidunregisterBNF(JPQLQueryBNF queryBNF)Unregisters the givenJPQLQueryBNF.
-
-
-
Method Detail
-
addChildBNF
public void addChildBNF(java.lang.String queryBNFId, java.lang.String childQueryBNFId)Adds to the given query BNF a child BNF.- Parameters:
queryBNFId- The unique identifier of the parent BNF to add a child BNFchildQueryBNFId- The unique identifier of the child to add to the parent BNF- Throws:
java.lang.NullPointerException- TheJPQLQueryBNFidentified by the given ID does not exist
-
addChildFactory
public void addChildFactory(java.lang.String queryBNFId, java.lang.String childExpressionFactoryId)Adds to the given unique identifier of anExpressionFactoryto the given query BNF.- Parameters:
queryBNFId- The unique identifier of the parent BNFchildExpressionFactoryId- The unique identifier of theExpressionFactoryto add to the given query BNF- Throws:
java.lang.NullPointerException- TheJPQLQueryBNFidentified by the given ID does not exist
-
addIdentifier
public void addIdentifier(java.lang.String expressionFactoryId, java.lang.String identifier)Adds the given JPQL identifier to this factory.- Parameters:
expressionFactoryId- The unique identifier of theExpressionFactoryto add more JPQL identifiersidentifier- The JPQL identifier this factory will parse
-
addIdentifiers
public void addIdentifiers(java.lang.String expressionFactoryId, java.lang.String... identifiers)Adds the given JPQL identifiers to this factory.- Parameters:
expressionFactoryId- The unique identifier of theExpressionFactoryto add more JPQL identifiersidentifiers- The JPQL identifiers this factory will parse
-
expressionFactoryForIdentifier
public ExpressionFactory expressionFactoryForIdentifier(java.lang.String identifier)
Retrieves theExpressionFactorythat is responsible for creating theExpressionobject that represents the given JPQL identifier.- Parameters:
identifier- The JPQL identifier for which its factory is searched- Returns:
- Either the
ExpressionFactorythat creates theExpressionornullif none was found
-
getExpressionFactory
public ExpressionFactory getExpressionFactory(java.lang.String expressionFactoryId)
Retrieves the registeredExpressionFactorythat was registered for the given unique identifier.- Parameters:
expressionFactoryId- The unique identifier of theExpressionFactoryto retrieve- Returns:
- The
ExpressionFactorymapped with the given unique identifier
-
getIdentifierRole
public IdentifierRole getIdentifierRole(java.lang.String identifier)
Retrieves theIdentifierRoleof the given JPQL identifier. A role helps to describe the purpose of the identifier in a JPQL query.- Parameters:
identifier- The JPQL identifier for which its role is returned- Returns:
- The
IdentifierRoleof the given JPQL identifier
-
getIdentifiers
public java.util.Set<java.lang.String> getIdentifiers()
Returns the JPQL identifiers that are supported by theJPQL grammar.- Returns:
- The supported JPQL identifiers
-
getIdentifiers
public java.lang.Iterable<java.lang.String> getIdentifiers(java.lang.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 theExpressionFactoryregistered with the BNF rule and its child BNF rules.- Returns:
- The list of JPQL identifiers that are supported by a BNF rule
-
getIdentifierVersion
public JPAVersion getIdentifierVersion(java.lang.String identifier)
Retrieves the JPA version in which the identifier was first introduced.- Returns:
- The version in which the identifier was introduced
-
getQueryBNF
public JPQLQueryBNF getQueryBNF(java.lang.String queryBNFId)
Retrieves the BNF object that was registered for the given unique identifier.- Parameters:
queryBNFId- The unique identifier of theJPQLQueryBNFto retrieve- Returns:
- The
JPQLQueryBNFrepresenting a section of the grammar
-
initialize
protected void initialize()
Instantiates the only instance of various API used by the parser.
-
isIdentifier
public boolean isIdentifier(java.lang.String text)
Determines if the given word is a JPQL identifier. The check is case insensitive.- Parameters:
text- The string value to test if it's a JPQL identifier based on what is registered with thisExpressionRegistry- Returns:
trueif the word is an identifier,falseotherwise
-
registerBNF
public void registerBNF(JPQLQueryBNF queryBNF)
Registers the givenJPQLQueryBNF. The BNF will be registered using its unique identifier.- Parameters:
queryBNF- TheJPQLQueryBNFto store- Throws:
java.lang.NullPointerException- TheJPQLQueryBNFcannot benull
-
registerFactory
public void registerFactory(ExpressionFactory expressionFactory)
Registers the givenExpressionFactoryby storing it for all its identifiers.- Parameters:
expressionFactory- TheExpressionFactoryto store- Throws:
java.lang.NullPointerException- TheExpressionFactorycannot benull
-
registerIdentifierRole
public void registerIdentifierRole(java.lang.String identifier, IdentifierRole role)Registers theIdentifierRolefor the given JPQL identifier.- Parameters:
identifier- The JPQL identifier to register its role within a JPQL queryrole- The role of the given JPQL identifier- Throws:
java.lang.NullPointerException- The JPQL identifier and theIdentifierRolecannot benull
-
registerIdentifierVersion
public void registerIdentifierVersion(java.lang.String identifier, JPAVersion version)Registers theJPAVersionfor which the given JPQL identifier was defined.- Parameters:
identifier- The JPQL identifier to register in which version it was added to the grammarversion- The version when the JPQL identifier was added to the grammar- Throws:
java.lang.NullPointerException- The JPQL identifier and theJPAVersioncannot benull
-
setFallbackBNFId
public void setFallbackBNFId(java.lang.String queryBNFId, java.lang.String fallbackBNFId)When parsing the query and noJPQLQueryBNFscan help to parse the query, then it will fall back on the given one.- Parameters:
queryBNFId- The unique identifier of the BNF to modify its fallback BNF unique identifierfallbackBNFId- The unique identifier of theJPQLQueryBNFto use in the last resort- Throws:
java.lang.NullPointerException- TheJPQLQueryBNFidentified by the given ID does not exist
-
setFallbackExpressionFactoryId
public void setFallbackExpressionFactoryId(java.lang.String queryBNFId, java.lang.String fallbackExpressionFactoryId)Sets the unique identifier of theExpressionFactoryto use when the fall back BNF ID is notnull. This will be used to parse a portion of the query when the registeredexpression factoriescannot parse it.Note: This method is only called if
JPQLQueryBNF. getFallbackBNFId()does not returnnull.- Parameters:
queryBNFId- The unique identifier of the BNF to modify its fallback expression factory unique identifier- Throws:
java.lang.NullPointerException- TheJPQLQueryBNFidentified by the given ID does not exist
-
setHandleCollection
public void setHandleCollection(java.lang.String queryBNFId, boolean handleCollection)Determines whether theExpressionhandles a collection of sub-expressions that are separated by commas.- Parameters:
queryBNFId- The unique identifier of theJPQLQueryBNFhandleCollection-trueif the sub-expression to parse might have several sub-expressions separated by commas;falseotherwise
-
setHandleNestedArray
public void setHandleNestedArray(java.lang.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- The unique identifier of theJPQLQueryBNFhandleNestedArray-trueif the expression represented by this BNF can be a nested array;falseotherwise- Since:
- 2.5
-
setHandleSubExpression
public void setHandleSubExpression(java.lang.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 fallbackExpressionFactory. The default behavior is to not handle it.A good example for using this option is when an
Expressioncannot use anyExpressionFactoryfor creating a child object, parsing will use the fallbackExpressionFactory, if one was specified. So when this is set totrue, the fallbackExpressionFactorywill be immediately invoked.Let's say we want to parse "SELECT e FROM (SELECT a FROM Address a) e",
FromClausecannot use a factory for parsing the entity name (that's what usually theFROMclause has) so it uses the fallback factory to createIdentificationVariableDeclaration. ThenIdentificationVariableDeclarationalso cannot use any factory to create its child object so it uses the fallback factory to createRangeVariableDeclaration. By changing the status of for handling the sub-expression for the BNFs for those objects, then a subquery can be created byRangeVariableDeclaration.
In order to get this working, the following would have to be done into the grammar:FromClause |- IdentificationVariableDeclaration |- RangeVariableDeclaration |- SubExpression(subquery)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- The unique identifier of theJPQLQueryBNFhandleSubExpression-trueto let the creation of a sub-expression be created by the fallbackExpressionFactoryregistered with this BNF;falseotherwise (which is the default value)
-
unregisterBNF
public void unregisterBNF(JPQLQueryBNF queryBNF)
Unregisters the givenJPQLQueryBNF.- Parameters:
queryBNF- TheJPQLQueryBNFto unregister- Throws:
java.lang.NullPointerException- TheJPQLQueryBNFcannot benull
-
-