EclipseLink 2.4.2, build 'v20130514-5956486' API Reference

org.eclipse.persistence.jpa.jpql.parser
Class JPQLExpression

java.lang.Object
  extended by org.eclipse.persistence.jpa.jpql.parser.AbstractExpression
      extended by org.eclipse.persistence.jpa.jpql.parser.JPQLExpression
All Implemented Interfaces:
Expression

public final class JPQLExpression
extends AbstractExpression

A JPQLExpression is the root of the parsed tree representation of a JPQL query. The query is parsed based on what was registered in the JPQLGrammar's ExpressionRegistry.

A JPQL statement may be either a SELECT statement, an UPDATE statement, or a DELETE FROM statement.

BNF: QL_statement ::= select_statement | update_statement | delete_statement

It is possible to parse a portion of a JPQL query. The ID of the JPQLQueryBNF is used to parse that portion and getQueryStatement() then returns only the parsed tree representation of that JPQL fragment.

Version:
2.4.2
Author:
Pascal Filion
Since:
2.3

Field Summary
 
Fields inherited from class org.eclipse.persistence.jpa.jpql.parser.AbstractExpression
COMMA, DOT, DOUBLE_QUOTE, LEFT_CURLY_BRACKET, LEFT_PARENTHESIS, NOT_DEFINED, RIGHT_CURLY_BRACKET, RIGHT_PARENTHESIS, SINGLE_QUOTE, SPACE, UNDERSCORE
 
Fields inherited from interface org.eclipse.persistence.jpa.jpql.parser.Expression
ABS, ALL, AND, ANY, AS, ASC, AVG, BETWEEN, BIT_LENGTH, BOTH, CASE, CAST, CHAR_LENGTH, CHARACTER_LENGTH, CLASS, COALESCE, COLUMN, CONCAT, COUNT, CURRENT_DATE, CURRENT_TIME, CURRENT_TIMESTAMP, DELETE, DELETE_FROM, DESC, DIFFERENT, DISTINCT, DIVISION, ELSE, EMPTY, END, ENTRY, EQUAL, ESCAPE, EXCEPT, EXISTS, EXTRACT, FALSE, FETCH, FROM, FUNC, FUNCTION, GREATER_THAN, GREATER_THAN_OR_EQUAL, GROUP_BY, HAVING, IN, INDEX, INNER, INNER_JOIN, INNER_JOIN_FETCH, INTERSECT, IS, IS_EMPTY, IS_NOT_EMPTY, IS_NOT_NULL, IS_NULL, JOIN, JOIN_FETCH, KEY, LEADING, LEFT, LEFT_JOIN, LEFT_JOIN_FETCH, LEFT_OUTER_JOIN, LEFT_OUTER_JOIN_FETCH, LENGTH, LIKE, LOCATE, LOWER, LOWER_THAN, LOWER_THAN_OR_EQUAL, MAX, MEMBER, MEMBER_OF, MIN, MINUS, MOD, MULTIPLICATION, NAMED_PARAMETER, NEW, NOT, NOT_BETWEEN, NOT_EQUAL, NOT_EXISTS, NOT_IN, NOT_LIKE, NOT_MEMBER, NOT_MEMBER_OF, NULL, NULLIF, NULLS_FIRST, NULLS_LAST, OBJECT, OF, ON, OPERATOR, OR, ORDER_BY, OUTER, PLUS, POSITION, POSITIONAL_PARAMETER, QUOTE, REGEXP, SELECT, SET, SIZE, SOME, SQL, SQRT, SUBSTRING, SUM, TABLE, THEN, TRAILING, TREAT, TRIM, TRUE, TYPE, UNION, UNKNOWN, UPDATE, UPPER, VALUE, WHEN, WHERE
 
Constructor Summary
JPQLExpression(java.lang.CharSequence query, JPQLGrammar jpqlGrammar)
          Creates a new JPQLExpression, which is the root of the JPQL parsed tree.
JPQLExpression(java.lang.CharSequence query, JPQLGrammar jpqlGrammar, boolean tolerant)
          Creates a new JPQLExpression, which is the root of the JPQL parsed tree.
JPQLExpression(java.lang.CharSequence jpqlFragment, JPQLGrammar jpqlGrammar, java.lang.String queryBNFId, boolean tolerant)
          Creates a new JPQLExpression that will parse the given fragment of a JPQL query.
 
Method Summary
 void accept(ExpressionVisitor visitor)
          Visits this Expression by the given visitor.
 void acceptChildren(ExpressionVisitor visitor)
          Visits the children of this Expression.
protected  void addChildrenTo(java.util.Collection<Expression> children)
          Adds the children of this AbstractExpression to the given collection.
protected  void addOrderedChildrenTo(java.util.List<Expression> children)
          Adds the children of this AbstractExpression to the given list.
 QueryPosition buildPosition(java.lang.String actualQuery, int position)
          Creates an object where the Expression is the leaf at the given position.
 Expression getExpression(java.lang.String actualQuery, int position)
          Returns the deepest Expression for the given position.
 JPQLGrammar getGrammar()
          Returns the JPQLGrammar that defines how the JPQL query was parsed.
 JPAVersion getJPAVersion()
          Returns the version of the Java Persistence to support.
 JPQLQueryBNF getQueryBNF()
          Returns the BNF of this Expression.
 Expression getQueryStatement()
          Returns the Expression representing the query, which is either a SELECT, a DELETE or an UPDATE clause.
 Expression getUnknownEndingStatement()
          Returns the Expression that may contain a portion of the query that could not be parsed, this happens when the query is either incomplete or malformed.
 boolean hasQueryStatement()
          Determines whether a query was parsed.
 boolean hasUnknownEndingStatement()
          Determines whether the query that got parsed had some malformed or unknown information.
protected  boolean isTolerant()
          Determines if the parser is in tolerant mode or is in fast mode.
protected  void parse(WordParser wordParser, boolean tolerant)
          Parses the query by starting at the current position, which is part of the given WordParser.
protected  void toParsedText(java.lang.StringBuilder writer, boolean actual)
          Generates a string representation of this Expression, including its children, if it has any.
 
Methods inherited from class org.eclipse.persistence.jpa.jpql.parser.AbstractExpression
acceptUnknownVisitor, acceptUnknownVisitor, buildExpressionFromFallingBack, buildNullExpression, buildStringExpression, buildStringExpression, buildUnknownExpression, calculatePosition, children, findFallBackExpressionFactory, findQueryBNF, getExpressionFactory, getExpressionRegistry, getIdentifierVersion, getLength, getOffset, getParent, getQueryBNF, getRoot, getText, handleAggregate, handleCollection, isAncestor, isIdentifier, isNull, isParsingComplete, isUnknown, isVirtual, orderedChildren, parse, parseUsingExpressionFactory, populatePosition, rebuildActualText, rebuildParsedText, setParent, setText, shouldParseWithFactoryFirst, shouldSkipLiteral, toActualText, toParsedText, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

JPQLExpression

public JPQLExpression(java.lang.CharSequence query,
                      JPQLGrammar jpqlGrammar)
Creates a new JPQLExpression, which is the root of the JPQL parsed tree.

Parameters:
query - The string representation of the JPQL query to parse
jpqlGrammar - The JPQL grammar that defines how to parse a JPQL query

JPQLExpression

public JPQLExpression(java.lang.CharSequence query,
                      JPQLGrammar jpqlGrammar,
                      boolean tolerant)
Creates a new JPQLExpression, which is the root of the JPQL parsed tree.

Parameters:
query - The string representation of the JPQL query to parse
jpqlGrammar - The JPQL grammar that defines how to parse a JPQL query
tolerant - Determines if the parsing system should be tolerant, meaning if it should try to parse invalid or incomplete queries

JPQLExpression

public JPQLExpression(java.lang.CharSequence jpqlFragment,
                      JPQLGrammar jpqlGrammar,
                      java.lang.String queryBNFId,
                      boolean tolerant)
Creates a new JPQLExpression that will parse the given fragment of a JPQL query. This means getQueryStatement() will not return a query statement (select, delete or update) but only the parsed tree representation of the fragment if the query BNF can pare it. If the fragment of the JPQL query could not be parsed using the given JPQLQueryBNF, then getUnknownEndingStatement() will contain the non-parsable fragment.

Parameters:
jpqlFragment - A fragment of a JPQL query, which is a portion of a complete JPQL query
jpqlGrammar - The JPQL grammar that defines how to parse a JPQL query
queryBNFId - The unique identifier of the JPQLQueryBNF JPQLQueryBNF
tolerant - Determines if the parsing system should be tolerant, meaning if it should try to parse invalid or incomplete queries
Since:
2.4
Method Detail

accept

public void accept(ExpressionVisitor visitor)
Visits this Expression by the given visitor.

Parameters:
visitor - The ExpressionVisitor to visit this object

acceptChildren

public void acceptChildren(ExpressionVisitor visitor)
Visits the children of this Expression. This method can be used to optimize traversing the children since a new list is not created every time Expression.children() is called.

This does not traverse the Expression sub-hierarchy, use a subclass of AbstractTraverseChildrenVisitor in order to traverse the entire sub-hierarchy.

Parameters:
visitor - The visitor to visit the children of this object.

addChildrenTo

protected void addChildrenTo(java.util.Collection<Expression> children)
Adds the children of this AbstractExpression to the given collection.

Overrides:
addChildrenTo in class AbstractExpression
Parameters:
children - The collection used to store the children

addOrderedChildrenTo

protected void addOrderedChildrenTo(java.util.List<Expression> children)
Adds the children of this AbstractExpression to the given list.

Overrides:
addOrderedChildrenTo in class AbstractExpression
Parameters:
children - The list used to store the string representation of this AbstractExpression

buildPosition

public QueryPosition buildPosition(java.lang.String actualQuery,
                                   int position)
Creates an object where the Expression is the leaf at the given position.

Parameters:
actualQuery - The actual query is a string representation of the query that may contain extra whitespace
position - The position of the cursor in the actual query, which is used to retrieve the deepest Expression. The position will be adjusted to fit into the beautified version of the query
Returns:
A new QueryPosition

getExpression

public Expression getExpression(java.lang.String actualQuery,
                                int position)
Returns the deepest Expression for the given position.

Parameters:
actualQuery - The actual query is the text version of the query that may contain extra whitespace and different formatting than the trim down version generated by the parsed tree
position - The position in the actual query used to retrieve the Expression
Returns:
The Expression located at the given position in the given query

getGrammar

public JPQLGrammar getGrammar()
Returns the JPQLGrammar that defines how the JPQL query was parsed.

Specified by:
getGrammar in interface Expression
Overrides:
getGrammar in class AbstractExpression
Returns:
The JPQLGrammar that was used to parse this Expression

getJPAVersion

public JPAVersion getJPAVersion()
Returns the version of the Java Persistence to support.

Overrides:
getJPAVersion in class AbstractExpression
Returns:
The JPA version supported by the grammar
See Also:
JPQLGrammar

getQueryBNF

public JPQLQueryBNF getQueryBNF()
Returns the BNF of this Expression.

Returns:
The JPQLQueryBNF, which represents the grammar of this Expression

getQueryStatement

public Expression getQueryStatement()
Returns the Expression representing the query, which is either a SELECT, a DELETE or an UPDATE clause.

Returns:
The expression representing the Java Persistence query

getUnknownEndingStatement

public Expression getUnknownEndingStatement()
Returns the Expression that may contain a portion of the query that could not be parsed, this happens when the query is either incomplete or malformed.

Returns:
The expression used when the ending of the query is unknown or malformed

hasQueryStatement

public boolean hasQueryStatement()
Determines whether a query was parsed. The query may be incomplete but it started with one of the three clauses (SELECT, DELETE FROM, or UPDATE).

Returns:
true the query was parsed; false otherwise

hasUnknownEndingStatement

public boolean hasUnknownEndingStatement()
Determines whether the query that got parsed had some malformed or unknown information.

Returns:
true if the query could not be parsed correctly because it is either incomplete or malformed

isTolerant

protected boolean isTolerant()
Determines if the parser is in tolerant mode or is in fast mode. When the tolerant is turned on, it means the parser will attempt to parse incomplete or invalid queries.

Overrides:
isTolerant in class AbstractExpression
Returns:
true if the parsing system should parse invalid or incomplete queries; false when the query is well-formed and valid

parse

protected void parse(WordParser wordParser,
                     boolean tolerant)
Parses the query by starting at the current position, which is part of the given WordParser.

Specified by:
parse in class AbstractExpression
Parameters:
wordParser - The text to parse based on the current position of the cursor
tolerant - Determines whether the parsing system should be tolerant, meaning if it should try to parse invalid or incomplete queries

toParsedText

protected void toParsedText(java.lang.StringBuilder writer,
                            boolean actual)
Generates a string representation of this Expression, including its children, if it has any.

Specified by:
toParsedText in class AbstractExpression
Parameters:
writer - The buffer used to append this Expression's string representation
actual - Determines whether the string representation should represent what was parsed, i.e. include any "virtual" whitespace (such as ending whitespace) and the actual case of the JPQL identifiers

EclipseLink 2.4.2, build 'v20130514-5956486' API Reference