JPQLQueryBNF (EclipseLink 2.6.9, API Reference)

java.lang.Object
- org.eclipse.persistence.jpa.jpql.parser.JPQLQueryBNF

Direct Known Subclasses:

AbstractSchemaNameBNF, AggregateExpressionBNF, AllOrAnyExpressionBNF, ArithmeticExpressionBNF, ArithmeticFactorBNF, ArithmeticPrimaryBNF, ArithmeticTermBNF, AsOfClauseBNF, BadExpressionBNF, BetweenExpressionBNF, BooleanExpressionBNF, BooleanLiteralBNF, BooleanPrimaryBNF, CaseExpressionBNF, CaseOperandBNF, CastExpressionBNF, CoalesceExpressionBNF, CollectionMemberDeclarationBNF, CollectionMemberExpressionBNF, CollectionValuedPathExpressionBNF, ComparisonExpressionBNF, ConditionalExpressionBNF, ConditionalFactorBNF, ConditionalPrimaryBNF, ConditionalTermBNF, ConnectByClauseBNF, ConstructorExpressionBNF, ConstructorItemBNF, DatabaseTypeQueryBNF, DatetimeExpressionBNF, DateTimePrimaryBNF, DateTimeTimestampLiteralBNF, DeleteClauseBNF, DeleteClauseRangeVariableDeclarationBNF, DeleteStatementBNF, DerivedCollectionMemberDeclarationBNF, ElseExpressionBNF, EmptyCollectionComparisonExpressionBNF, EntityExpressionBNF, EntityOrValueExpressionBNF, EntityTypeExpressionBNF, EntityTypeLiteralBNF, EnumExpressionBNF, EnumLiteralBNF, EnumPrimaryBNF, ExistsExpressionBNF, ExtractExpressionBNF, FromClauseBNF, FunctionExpressionBNF, FunctionItemBNF, FunctionsReturningDatetimeBNF, FunctionsReturningNumericsBNF, FunctionsReturningStringsBNF, GeneralCaseExpressionBNF, GeneralIdentificationVariableBNF, GenericQueryBNF, GroupByClauseBNF, GroupByItemBNF, HavingClauseBNF, HierarchicalQueryClauseBNF, IdentificationVariableBNF, IdentificationVariableDeclarationBNF, InExpressionBNF, InExpressionExpressionBNF, InExpressionItemBNF, InputParameterBNF, InternalAggregateFunctionBNF, InternalBetweenExpressionBNF, InternalCoalesceExpressionBNF, InternalColumnExpressionBNF, InternalConcatExpressionBNF, InternalConnectByClauseBNF, InternalCountBNF, InternalEntityTypeExpressionBNF, InternalFromClauseBNF, InternalJoinBNF, InternalLengthExpressionBNF, InternalLocateStringExpressionBNF, InternalLocateThirdExpressionBNF, InternalLowerExpressionBNF, InternalModExpressionBNF, InternalOrderByClauseBNF, InternalOrderByItemBNF, InternalSelectExpressionBNF, InternalSimpleFromClauseBNF, InternalSimpleSelectExpressionBNF, InternalSqrtExpressionBNF, InternalSubstringPositionExpressionBNF, InternalSubstringStringExpressionBNF, InternalUpdateClauseBNF, InternalUpperExpressionBNF, InternalWhenClauseBNF, JoinAssociationPathExpressionBNF, JoinBNF, JoinFetchBNF, JPQLStatementBNF, LikeExpressionBNF, LikeExpressionEscapeCharacterBNF, LiteralBNF, NewValueBNF, NullComparisonExpressionBNF, NullIfExpressionBNF, NumericLiteralBNF, ObjectExpressionBNF, OnClauseBNF, OrderByClauseBNF, OrderByItemBNF, OrderSiblingsByClauseBNF, PatternValueBNF, QualifiedIdentificationVariableBNF, RangeDeclarationBNF, RangeVariableDeclarationBNF, RegexpExpressionBNF, ResultVariableBNF, ScalarExpressionBNF, SelectClauseBNF, SelectExpressionBNF, SelectStatementBNF, SimpleArithmeticExpressionBNF, SimpleCaseExpressionBNF, SimpleConditionalExpressionBNF, SimpleEntityExpressionBNF, SimpleEntityOrValueExpressionBNF, SimpleResultVariableBNF, SimpleSelectClauseBNF, SimpleSelectExpressionBNF, SingleValuedObjectPathExpressionBNF, SingleValuedPathExpressionBNF, StartWithClauseBNF, StateFieldPathExpressionBNF, StringExpressionBNF, StringLiteralBNF, StringPrimaryBNF, SubqueryBNF, SubqueryFromClauseBNF, SubSelectIdentificationVariableDeclarationBNF, TableExpressionBNF, TableVariableDeclarationBNF, TreatExpressionBNF, TypeExpressionBNF, UnionClauseBNF, UpdateClauseBNF, UpdateItemBNF, UpdateItemStateFieldPathExpressionBNF, UpdateStatementBNF, VirtualJPQLQueryBNF, WhenClauseBNF, WhereClauseBNF
```
public abstract class JPQLQueryBNF
extends java.lang.Object
```
This defines a single Backus-Naur Form (BNF) of the JPQL grammar. The Java Persistence functional specifications are:
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.1

Author:

Pascal Filion

Since:

2.3

Constructor Summary

Constructors
Modifier Constructor and Description

protected JPQLQueryBNF(java.lang.String id)
Creates a new JPQLQueryBNF.

Constructors
Modifier	Constructor and Description
`protected`	`JPQLQueryBNF(java.lang.String id)` Creates a new `JPQLQueryBNF`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.lang.Iterable<JPQLQueryBNF>`	`children()` Returns the set of all the query BNFs that are part of this BNF.
`ExpressionFactory`	`getExpressionFactory(java.lang.String identifier)` Retrieves the `ExpressionFactory` that is associated with the given identifier, if the given string is indeed a JPQL identifier.
`java.lang.Iterable<java.lang.String>`	`getExpressionFactoryIds()` Returns the unique identifiers of the `ExpressionFactory` handled by this BNF rule, which includes those from the children as well.
`ExpressionRegistry`	`getExpressionRegistry()` Returns the registry containing the `JPQLQueryBNFs` and the `ExpressionFactories` that are used to properly parse a JPQL query.
`java.lang.String`	`getFallbackBNFId()` When parsing the query and no `JPQLQueryBNFs` can help to parse the query, then it will fall back on this one.
`java.lang.String`	`getFallbackExpressionFactoryId()` Returns the unique identifier of the `ExpressionFactory` to use when the fall back BNF ID is not `null`.
`java.lang.String`	`getId()` Returns the unique identifier of this `JPQLQueryBNF`.
`java.lang.Iterable<java.lang.String>`	`getIdentifiers()` Retrieves the JPQL identifiers that are supported by this BNF rule.
`boolean`	`handleAggregate()` Determines whether the `Expression` handles a collection of sub-expressions that are aggregated by logical or arithmetic operators.
`boolean`	`handleCollection()` Determines whether the `Expression` handles a collection of sub-expressions that are separated by commas.
`boolean`	`handlesNestedArray()`
`boolean`	`handleSubExpression()` Determines whether this BNF handles parsing a sub-expression, i.e. parsing an expression encapsulated by parenthesis.
`boolean`	`hasChild(java.lang.String queryBNFId)` Determines whether the BNF with the given ID is part of this BNF or not.
`boolean`	`hasIdentifier(java.lang.String word)` Determines if this query BNF support the given word, which can be an identifier.
`protected void`	`initialize()` Initializes this BNF by registering child `JPQLQueryBNFs` and `ExpressionFactories`.
`boolean`	`isCompound()` Determines whether this BNF has child BNFs registered only to properly parse a query or if the child BNFs are part of the BNF.
`java.lang.Iterable<JPQLQueryBNF>`	`nonCompoundChildren()` Returns the set of all the query BNFs that are part of this BNF.
`protected void`	`registerChild(java.lang.String queryBNFId)` Registers the unique identifier of the BNF rule as a child of this BNF rule.
`protected void`	`registerExpressionFactory(java.lang.String expressionFactoryId)` Registers a unique identifier of the `ExpressionFactory` to register with this BNF rule.
`void`	`setCompound(boolean compound)` Determines whether this BNF has child BNFs registered only to properly parse a query or if the child BNFs are part of the BNF.
`void`	`setFallbackBNFId(java.lang.String fallbackBNFId)` When parsing the query and no `JPQLQueryBNFs` can help to parse the query, then it will fall back on the given one.
`void`	`setFallbackExpressionFactoryId(java.lang.String fallbackExpressionFactoryId)` Sets the unique identifier of the `ExpressionFactory` to use when the fall back BNF ID is not `null`.
`void`	`setHandleAggregate(boolean handleAggregate)` Sets whether the `Expression` handles a collection of sub-expressions that are aggregated by logical or arithmetic operators.
`void`	`setHandleCollection(boolean handleCollection)` Sets whether the `Expression` handles a collection of sub-expressions that are separated by commas.
`void`	`setHandleNestedArray(boolean handleNestedArray)` Sets whether this BNF supports nested array or not.
`void`	`setHandleSubExpression(boolean handleSubExpression)` Sets whether this BNF handles parsing a sub-expression, i.e. parsing an expression encapsulated by parenthesis.
`java.lang.String`	`toString()`
`protected void`	`toString(java.lang.StringBuilder sb)` Adds to the given builder more information about this `JPQLQueryBNF`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - JPQLQueryBNF
```
protected JPQLQueryBNF(java.lang.String id)
```
    Creates a new JPQLQueryBNF.
    
    Parameters:
    
    id - The unique identifier of this BNF rule
    
    Throws:
    
    java.lang.NullPointerException - The given unique identifier cannot be null
- Method Detail
  - children
```
public java.lang.Iterable<JPQLQueryBNF> children()
```
    Returns the set of all the query BNFs that are part of this BNF. The set always include this BNF as well.
    
    Returns:
    
    The children BNFs describing this BNF rule
  - getExpressionFactory
```
public ExpressionFactory getExpressionFactory(java.lang.String identifier)
```
    Retrieves the ExpressionFactory that is associated with the given identifier, if the given string is indeed a JPQL identifier.
    
    Parameters:
    
    identifier - The JPQL identifier (in theory) that is used to retrieve the factory responsible to parse a portion of the query starting with that identifier
    
    Returns:
    
    The ExpressionFactory responsible to parse a portion of the query starting with the given identifier; null if nothing was registered for it
  - getExpressionFactoryIds
```
public java.lang.Iterable<java.lang.String> getExpressionFactoryIds()
```
    Returns the unique identifiers of the ExpressionFactory handled by this BNF rule, which includes those from the children as well.
    
    Returns:
    
    The list of unique identifiers of the ExpressionFactory registered with this BNF rule and with its children
  - 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
  - getFallbackBNFId
```
public java.lang.String getFallbackBNFId()
```
    When parsing the query and no JPQLQueryBNFs can help to parse the query, then it will fall back on this one.
    
    Returns:
    
    The unique identifier of the JPQLQueryBNF to use in the last resort
  - getFallbackExpressionFactoryId
```
public java.lang.String getFallbackExpressionFactoryId()
```
    Returns 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 getFallbackBNFId() does not return null.
    
    Returns:
    
    The unique identifier of the ExpressionFactory
  - getId
```
public java.lang.String getId()
```
    Returns the unique identifier of this JPQLQueryBNF.
    
    Returns:
    
    The identifier used to register this JPQLQueryBNF with AbstractExpression
  - getIdentifiers
```
public java.lang.Iterable<java.lang.String> getIdentifiers()
```
    Retrieves the JPQL identifiers that are supported by this BNF rule. The JPQL identifiers are retrieved by scanning the ExpressionFactory registered with this BNF rule and the child BNF rules.
    
    Returns:
    
    The list of JPQL identifiers that are supported by this BNF
  - handleAggregate
```
public boolean handleAggregate()
```
    Determines whether the Expression handles a collection of sub-expressions that are aggregated by logical or arithmetic operators.
    
    Returns:
    
    true if the sub-expression to parse might have several logical and/or arithmetic expressions; false otherwise
  - handleCollection
```
public boolean handleCollection()
```
    Determines whether the Expression handles a collection of sub-expressions that are separated by commas.
    
    Returns:
    
    true if the sub-expression to parse might have several sub-expressions separated by commas; false otherwise
  - handlesNestedArray
```
public boolean handlesNestedArray()
```
    Since:
    
    2.5
  - handleSubExpression
```
public boolean handleSubExpression()
```
    Determines whether this BNF handles parsing a sub-expression, i.e. parsing an expression encapsulated by parenthesis. See setHandleSubExpression(boolean) for more details.
    
    Returns:
    
    true if this BNF handles parsing a sub-expression; false otherwise
  - hasChild
```
public boolean hasChild(java.lang.String queryBNFId)
```
    Determines whether the BNF with the given ID is part of this BNF or not.
    
    Parameters:
    
    queryBNFId - The unique identifier of the BNF rule to check if it's a child of this one
    
    Returns:
    
    true if the BNF with the given ID is
    
    Since:
    
    2.5.1
  - hasIdentifier
```
public boolean hasIdentifier(java.lang.String word)
```
    Determines if this query BNF support the given word, which can be an identifier.
    
    Parameters:
    
    word - A word that could be a JPQL identifier or anything else
    
    Returns:
    
    true if the given word is a JPQL identifier and it is supported by this BNF; false otherwise
  - initialize
```
protected void initialize()
```
    Initializes this BNF by registering child JPQLQueryBNFs and ExpressionFactories.
  - isCompound
```
public boolean isCompound()
```
    Determines whether this BNF has child BNFs registered only to properly parse a query or if the child BNFs are part of the BNF. An example if a compound BNF is BetweenExpressionBNF, it registers a series of children BNFs but they shouldn't be used to determine if they are part of that BNF since the comparator identifiers are.
    
    Returns:
    
    false by default
  - nonCompoundChildren
```
public java.lang.Iterable<JPQLQueryBNF> nonCompoundChildren()
```
    Returns the set of all the query BNFs that are part of this BNF. The set always include this BNF as well.
    
    Returns:
    
    The children BNFs describing this BNF rule. The set excludes BNF rules that are used to complete a BNF, such as the BNF rules defined for BETWEEN since they are required to properly parse the query
  - registerChild
```
protected final void registerChild(java.lang.String queryBNFId)
```
    Registers the unique identifier of the BNF rule as a child of this BNF rule.
    
    Parameters:
    
    queryBNFId - The unique identifier of the BNF rule to add as a child
    
    Throws:
    
    java.lang.NullPointerException - The queryBNFId cannot be null
  - registerExpressionFactory
```
protected final void registerExpressionFactory(java.lang.String expressionFactoryId)
```
    Registers a unique identifier of the ExpressionFactory to register with this BNF rule.
    
    Parameters:
    
    expressionFactoryId - The unique identifier of the ExpressionFactory
    
    Throws:
    
    java.lang.NullPointerException - The expressionFactoryId cannot be null
  - setCompound
```
public void setCompound(boolean compound)
```
    Determines whether this BNF has child BNFs registered only to properly parse a query or if the child BNFs are part of the BNF. An example if a compound BNF is BetweenExpressionBNF, it registers a series of children BNFs but they shouldn't be used to determine if they are part of that BNF since the comparator identifiers are.
    
    Parameters:
    
    compound - true if this BNF represents a compound BNF and its children are not part of this BNF but only to support compound expression; false otherwise
  - setFallbackBNFId
```
public void setFallbackBNFId(java.lang.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:
    
    fallbackBNFId - The unique identifier of the JPQLQueryBNF to use in the last resort
  - setFallbackExpressionFactoryId
```
public void setFallbackExpressionFactoryId(java.lang.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 getFallbackBNFId() does not return null.
    
    Parameters:
    
    fallbackExpressionFactoryId - The unique identifier of the ExpressionFactory
  - setHandleAggregate
```
public void setHandleAggregate(boolean handleAggregate)
```
    Sets whether the Expression handles a collection of sub-expressions that are aggregated by logical or arithmetic operators.
    
    Parameters:
    
    handleAggregate - true if the sub-expression to parse might have several logical and/or arithmetic expressions; false otherwise
  - setHandleCollection
```
public void setHandleCollection(boolean handleCollection)
```
    Sets whether the Expression handles a collection of sub-expressions that are separated by commas.
    
    Parameters:
    
    handleCollection - true if the sub-expression to parse might have several sub-expressions separated by commas; false otherwise
  - setHandleNestedArray
```
public void setHandleNestedArray(boolean handleNestedArray)
```
    Sets whether this BNF 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:
    
    handleNestedArray - true if the expression represented by this BNF can be a nested array; false otherwise
    
    Since:
    
    2.5
  - setHandleSubExpression
```
public void setHandleSubExpression(boolean handleSubExpression)
```
    Sets whether this BNF 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:
    
    handleSubExpression - 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)
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - toString
```
protected void toString(java.lang.StringBuilder sb)
```
    Adds to the given builder more information about this JPQLQueryBNF.
    
    Parameters:
    
    sb - The builder used to add information about this class

Class JPQLQueryBNF

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

JPQLQueryBNF

Method Detail

children

getExpressionFactory

getExpressionFactoryIds

getExpressionRegistry

getFallbackBNFId

getFallbackExpressionFactoryId

getId

getIdentifiers

handleAggregate

handleCollection

handlesNestedArray

handleSubExpression

hasChild

hasIdentifier

initialize

isCompound

nonCompoundChildren

registerChild

registerExpressionFactory

setCompound

setFallbackBNFId

setFallbackExpressionFactoryId

setHandleAggregate

setHandleCollection

setHandleNestedArray

setHandleSubExpression

toString

toString