* Copyright (c) 2006, 2013 Oracle and/or its affiliates. All rights reserved.

* This program and the accompanying materials are made available under the

* terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0

* which accompanies this distribution.

* The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html

* and the Eclipse Distribution License is available at

* http://www.eclipse.org/org/documents/edl-v10.php.

*

* Contributors:

*     Oracle - initial API and implementation

*

******************************************************************************/

* The base validator responsible to gather the problems found in a JPQL query by validating the

* content to make sure it is semantically valid, i.e. based on the information contained in the

* JPA application. The grammar is not validated by this visitor.

* <p>

* 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.

*

* @see AbstractGrammarValidator

*

* @version 2.5.1

* @since 2.4

* @author Pascal Filion

*/

  /**

   * This visitor is responsible to retrieve the visited {@link Expression} if it is a

   * {@link CollectionValuedPathExpression}.

   */

  protected CollectionValuedPathExpressionVisitor collectionValuedPathExpressionVisitor;

  /**

   * This visitor is responsible to check if the entity type literal (parsed as an identification

   * variable) is part of a comparison expression.

   */

  private ComparingEntityTypeLiteralVisitor comparingEntityTypeLiteralVisitor;

  /**

   * This visitor visits the left and right expressions of a {@link ComparisonExpressionVisitor}

   * and gather information that is used by {@link #validateComparisonExpression(ComparisonExpression)}.

   */

  private ComparisonExpressionVisitor comparisonExpressionVisitor;

  /**

   * The given helper allows this validator to access the JPA artifacts without using Hermes SPI.

   */

  protected final SemanticValidatorHelper helper;

  /**

   * This visitor makes sure the path expressions are properly validated.

   */

  private InItemsVisitor inItemsVisitor;

  /**

   * This flag is used to register the {@link IdentificationVariable IdentificationVariables} that

   * are used throughout the query (top-level query and subqueries), except the identification

   * variables defining an abstract schema name or a collection-valued path expression.

   */

  protected boolean registerIdentificationVariable;

  /**

   * This visitor is responsible to retrieve the visited {@link Expression} if it is a

   * {@link StateFieldPathExpression}.

   */

  protected StateFieldPathExpressionVisitor stateFieldPathExpressionVisitor;

  /**

   *

   */

  private SubqueryFirstDeclarationVisitor subqueryFirstDeclarationVisitor;

  /**

   *

   */

  private TopLevelFirstDeclarationVisitor topLevelFirstDeclarationVisitor;

  /**

   * The {@link IdentificationVariable IdentificationVariables} that are used throughout the query

   * (top-level query and subqueries), except the identification variables defining an abstract

   * schema name or a collection-valued path expression.

   */

  protected List<IdentificationVariable> usedIdentificationVariables;

  /**

   * This finder is responsible to retrieve the virtual identification variable from the

   * <b>UPDATE</b> range declaration since it is optional.

   */

  protected BaseDeclarationIdentificationVariableFinder virtualIdentificationVariableFinder;

  /**

   * Creates a new <code>AbstractSemanticValidator</code>.

   *

   * @param helper The given helper allows this validator to access the JPA artifacts without using

   * Hermes SPI

   * @exception NullPointerException The given {@link SemanticValidatorHelper} cannot be <code>null</code>

   */

  protected AbstractSemanticValidator(SemanticValidatorHelper helper) {

    super();

    Assert.isNotNull(helper, "The helper cannot be null");

    this.helper = helper;

  }

  protected ComparingEntityTypeLiteralVisitor buildComparingEntityTypeLiteralVisitor() {

    return new ComparingEntityTypeLiteralVisitor();

  }

  protected InItemsVisitor buildInItemsVisitor() {

    return new InItemsVisitor();

  }

  protected SubqueryFirstDeclarationVisitor buildSubqueryFirstDeclarationVisitor() {

    return new SubqueryFirstDeclarationVisitor();

  }

  protected TopLevelFirstDeclarationVisitor buildTopLevelFirstDeclarationVisitor() {

    return new TopLevelFirstDeclarationVisitor();

  }

  /**

   * {@inheritDoc}

   */

  @Override

  public void dispose() {

    super.dispose();

    usedIdentificationVariables.clear();

  }

  /**

   * Returns the {@link IdentificationVariable} that defines the identification variable for either

   * a <code><b>DELETE</b></code> or an <code><b>UPDATE</b></code> query.

   *

   * @param expression The {@link AbstractSchemaName} that is being validated and that most likely

   * representing an associated path expression and not an entity name

   * @return The {@link IdentificationVariable} defining either the identification variable or the

   * virtual identification variable for the <code><b>DELETE</b></code> or for the

   * <code><b>UPDATE</b></code> query

   */

  protected IdentificationVariable findVirtualIdentificationVariable(AbstractSchemaName expression) {

    BaseDeclarationIdentificationVariableFinder visitor = getVirtualIdentificationVariableFinder();

    try {

      expression.accept(visitor);

      return visitor.expression;

    }

    finally {

      visitor.expression = null;

    }

  }

  protected CollectionValuedPathExpression getCollectionValuedPathExpression(Expression expression) {

    CollectionValuedPathExpressionVisitor visitor = getCollectionValuedPathExpressionVisitor();

    try {

      expression.accept(visitor);

      return visitor.expression;

    }

    finally {

      visitor.expression = null;

    }

  }

  protected CollectionValuedPathExpressionVisitor getCollectionValuedPathExpressionVisitor() {

    if (collectionValuedPathExpressionVisitor == null) {

      collectionValuedPathExpressionVisitor = new CollectionValuedPathExpressionVisitor();

    }

    return collectionValuedPathExpressionVisitor;

  }

  protected ComparingEntityTypeLiteralVisitor getComparingEntityTypeLiteralVisitor() {

    if (comparingEntityTypeLiteralVisitor == null) {

      comparingEntityTypeLiteralVisitor = buildComparingEntityTypeLiteralVisitor();

    }

    return comparingEntityTypeLiteralVisitor;

  }

  protected ComparisonExpressionVisitor getComparisonExpressionVisitor() {

    if (comparisonExpressionVisitor == null) {

      comparisonExpressionVisitor = new ComparisonExpressionVisitor();

    }

    return comparisonExpressionVisitor;

  }

  /**

   * {@inheritDoc}

   */

  @Override

  protected JPQLGrammar getGrammar() {

    return helper.getGrammar();

  }

  protected InItemsVisitor getInItemsVisitor() {

    if (inItemsVisitor == null) {

      inItemsVisitor = buildInItemsVisitor();

    }

    return inItemsVisitor;

  }

  protected StateFieldPathExpression getStateFieldPathExpression(Expression expression) {

    StateFieldPathExpressionVisitor visitor = getStateFieldPathExpressionVisitor();

    try {

      expression.accept(visitor);

      return visitor.expression;

    }

    finally {