Package org.eclipse.persistence.jpa.jpql.parser

Class AbstractExpression

    • Constructor Detail

      • AbstractExpression

        protected AbstractExpression​(AbstractExpression parent)
        Creates a new AbstractExpression.
        Parameters:
        parent - The parent of this expression

      • AbstractExpression

        protected AbstractExpression​(AbstractExpression parent,
                             java.lang.String text)
        Creates a new AbstractExpression.
        Parameters:
        parent - The parent of this expression
        text - The text to be stored in this expression, null cannot be passed

    • Method Detail

      • acceptUnknownVisitor

        protected boolean acceptUnknownVisitor​(ExpressionVisitor visitor)
        The given ExpressionVisitor needs to visit this class but it is defined by a third- party provider. This method will programmatically invoke the visit method defined on the visitor. The method signature should be:
        {public|protected|private} void visit(ThirdPartyExpression expression)

        or

        {public|protected|private} void visit(Expression expression)

        Note: The package protected visibility (default) should be used with care, if the code is running inside OSGi, then the method will not be accessible, even through reflection.

        Parameters:
        visitor - The ExpressionVisitor to visit this Expression programmatically
        Returns:
        true if the call was successfully executed; false otherwise
        Since:
        2.4

      • acceptUnknownVisitor

        protected void acceptUnknownVisitor​(ExpressionVisitor visitor,
                                    java.lang.Class<?> type,
                                    java.lang.Class<?> parameterType)
                             throws java.lang.NoSuchMethodException,
                                    java.lang.IllegalAccessException,
                                    java.lang.reflect.InvocationTargetException
        The given ExpressionVisitor needs to visit this class but it is defined by a third- party provider. This method will programmatically invoke the visit method defined on the visitor. The method signature should be:
        {public|protected|private} void visit(ThirdPartyExpression expression)

        or

        {public|protected|private} void visit(Expression expression)

        Parameters:
        visitor - The ExpressionVisitor to visit this Expression programmatically
        type - The type found in the hierarchy of the given ExpressionVisitor that will be used to retrieve the visit method
        parameterType - The parameter type of the visit method
        Throws:
        java.lang.NoSuchMethodException
        java.lang.IllegalAccessException
        java.lang.reflect.InvocationTargetException
        See Also:
        acceptUnknownVisitor(ExpressionVisitor)
        Since:
        2.4

      • addChildrenTo

        protected void addChildrenTo​(java.util.Collection<Expression> children)
        Adds the children of this AbstractExpression to the given collection.
        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.
        Parameters:
        children - The list used to store the string representation of this AbstractExpression

      • buildExpressionFromFallingBack

        protected final AbstractExpression buildExpressionFromFallingBack​(WordParser wordParser,
                                                                  java.lang.String word,
                                                                  JPQLQueryBNF queryBNF,
                                                                  AbstractExpression expression,
                                                                  boolean tolerant)
        No factories were found to create an Expression with the content of WordParser, this method will retrieve the fallback ExpressionFactory defined in the given BNF.
        Parameters:
        wordParser - The text to parse based on the current position of the cursor
        word - The word that was retrieved from the given text, which is the first word in the text
        queryBNF - The JPQLQueryBNF used to determine how to parse from the current position of the cursor within the JPQL query
        expression - The Expression that has just been parsed or null
        tolerant - Determines whether the parsing system should be tolerant, meaning if it should try to parse invalid or incomplete queries
        Returns:
        The Expression representing the given sub-query

      • buildStringExpression

        protected final Expression buildStringExpression​(char value)
        Creates a new Expression wrapping the given character value.
        Parameters:
        value - The character to wrap as a Expression
        Returns:
        The Expression representation of the given identifier where the owning Expression is this one

      • buildStringExpression

        protected final Expression buildStringExpression​(java.lang.String value)
        Creates a new Expression wrapping the given string value.
        Parameters:
        value - The string to wrap as a Expression
        Returns:
        The Expression representation of the given identifier where the owning Expression is this one

      • buildUnknownExpression

        protected final AbstractExpression buildUnknownExpression​(java.lang.String text)
        Creates an Expression that contains a malformed expression.
        Parameters:
        text - The text causing the expression to be malformed
        Returns:
        A new Expression where toActualText() returns the given text

      • calculatePosition

        protected final int calculatePosition​(Expression expression,
                                      int length)
        Calculates the position of the given Expression by calculating the length of what is before.
        Parameters:
        expression - The Expression for which its position within the parsed tree needs to be determined
        length - The current cursor position within the JPQL query while digging into the tree until the search reaches the expression
        Returns:
        The length of the string representation for what is coming before the given Expression
        Since:
        2.4

      • getExpressionRegistry

        protected final 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

      • 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

      • getJPAVersion

        protected JPAVersion getJPAVersion()
        Returns the version of the Java Persistence to support.
        Returns:
        The JPA version supported by the grammar
        See Also:
        JPQLGrammar

      • getOffset

        public final int getOffset()
        Returns the position of this Expression within its parent hierarchy.
        Specified by:
        getOffset in interface Expression
        Returns:
        The length of the string representation of what is coming before this object

      • 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 the JPQLQueryBNF to retrieve
        Returns:
        The JPQLQueryBNF representing a section of the grammar

      • getText

        protected java.lang.String getText()
        Returns the encapsulated text of this AbstractExpression, which can be used in various ways, it can be a keyword, a literal, etc.
        Returns:
        Either the JPQL identifier for this AbstractExpression, the literal it encapsulates or an empty string

      • handleAggregate

        protected boolean handleAggregate​(JPQLQueryBNF queryBNF)
        Determines whether the given JPQLQueryBNF handles aggregate expressions.
        Parameters:
        queryBNF - The JPQLQueryBNF used to determine if the parsing should handle aggregate expressions
        Returns:
        true if the given BNF handles aggregate expressions; false otherwise

      • handleCollection

        protected boolean handleCollection​(JPQLQueryBNF queryBNF)
        Determines whether the given JPQLQueryBNF handles a collection of sub-expressions that are separated by commas.
        Parameters:
        queryBNF - The JPQLQueryBNF used to determine if the parsing should handle collection of sub-expressions
        Returns:
        true if the sub-expression to parse might have several sub-expressions separated by commas; false otherwise

      • isIdentifier

        protected final boolean isIdentifier​(java.lang.String word)
        Determines if the given word is a JPQL identifier. The check is case insensitive.
        Parameters:
        word - The word to test if it is a JPQL identifier
        Returns:
        true if the word is an identifier, false otherwise
        See Also:
        ExpressionRegistry.isIdentifier(String)

      • isNull

        protected boolean isNull()
        Determines whether this expression is a null Expression or any other subclass.
        Returns:
        false by default

      • isParsingComplete

        protected boolean isParsingComplete​(WordParser wordParser,
                                    java.lang.String word,
                                    Expression expression)
        Determines whether the parsing is complete based on what is left in the given text. The text is never empty.
        Parameters:
        wordParser - The text to parse based on the current position of the cursor
        word - The word that was retrieved from the given text, which is the first word in the text
        expression - The Expression that has already been parsed
        Returns:
        true if the text no longer can't be parsed by the current expression; false if more can be parsed

      • 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.
        Returns:
        true if the parsing system should parse invalid or incomplete queries; false when the query is well-formed and valid

      • isUnknown

        protected boolean isUnknown()
        Determines whether this expression is an unknown Expression or any other subclass.
        Returns:
        false by default

      • isVirtual

        protected boolean isVirtual()
        Determines whether this AbstractExpression is virtual, meaning it's not part of the query but is required for proper navigability.
        Returns:
        true if this AbstractExpression was virtually created to fully qualify path expression; false if it was parsed

      • parse

        protected abstract void parse​(WordParser wordParser,
                              boolean tolerant)
        Parses the query by starting at the current position, which is part of the given WordParser.
        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

      • parse

        protected AbstractExpression parse​(WordParser wordParser,
                                   java.lang.String queryBNFId,
                                   boolean tolerant)
        Parses the given text by using the specified BNF.
        Parameters:
        wordParser - The text to parse based on the current position of the cursor
        queryBNFId - The unique identifier of the JPQLQueryBNF that is used to determine how to parse the text at the current cursor position within the JPQL query
        tolerant - Determines whether the parsing system should be tolerant, meaning if it should try to parse invalid or incomplete queries
        Returns:
        The Expression representing the given sub-query

      • parseUsingExpressionFactory

        protected AbstractExpression parseUsingExpressionFactory​(WordParser wordParser,
                                                         java.lang.String queryBNFId,
                                                         boolean tolerant)
        Right away parses the text by retrieving the ExpressionFactory for the first word that is extracted from WordParser at the current location.
        Parameters:
        wordParser - The text to parse based on the current position of the cursor
        queryBNFId - The unique identifier of the JPQLQueryBNF that is used to determine how to parse the text at the current cursor position within the JPQL query
        tolerant - Determines whether the parsing system should be tolerant, meaning if it should try to parse invalid or incomplete queries
        Returns:
        The Expression representing the given sub-query

      • populatePosition

        public void populatePosition​(QueryPosition queryPosition,
                             int position)
        Retrieves the Expression located at the given position using the actual query, which may have extra whitespace.
        Specified by:
        populatePosition in interface Expression
        position - The array has one element and is the position of the Expression to retrieve

      • rebuildActualText

        protected final void rebuildActualText()
        Rebuilds the actual parsed text if it has been cached.

      • rebuildParsedText

        protected final void rebuildParsedText()
        Rebuilds the parsed parsed text if it has been cached.

      • setParent

        protected final void setParent​(AbstractExpression parent)
        Re-parents this Expression to be a child of the given Expression.
        Parameters:
        parent - The new parent of this object

      • setText

        protected final void setText​(java.lang.String text)
        Sets the text of this Expression.
        Parameters:
        text - The immutable text wrapped by this Expression, which cannot be null

      • shouldParseWithFactoryFirst

        protected boolean shouldParseWithFactoryFirst()
        Determines whether the parsing of the query should be performed using the factories first or it should automatically fallback to the fallback factory.
        Returns:
        true is returned by default so the factories are used before falling back

      • shouldSkipLiteral

        protected boolean shouldSkipLiteral​(AbstractExpression expression)
        When parsing an invalid or incomplete query, it is possible two literals would be parsed but in some cases, a CollectionExpression should not be created and the parsing should actually stop here. Example: BETWEEN 10 20, when parsing 20, it should not be parsed as part of the lower bound expression.
        Parameters:
        expression - The Expression that has just been parsed or null
        Returns:
        true

      • toActualText

        public java.lang.String toActualText()
        Generates a string representation of this Expression, which needs to include any characters that are considered virtual, i.e. that was parsed when the query is incomplete and is needed for functionality like content assist.
        Specified by:
        toActualText in interface Expression
        Returns:
        The string representation of this Expression

      • toParsedText

        public java.lang.String toParsedText()
        Returns a string representation of this Expression and its children. The expression should contain whitespace even if the beautified version would not have any. For instance, "SELECT e " should be returned where Expression.toParsedText() would return "SELECT e".
        Specified by:
        toParsedText in interface Expression
        Returns:
        The string representation of this Expression

      • toParsedText

        protected abstract void toParsedText​(java.lang.StringBuilder writer,
                                     boolean actual)
        Generates a string representation of this Expression, including its children, if it has any.
        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

      • toString

        public final java.lang.String toString()
        Overrides:
        toString in class java.lang.Object