/*
 * Copyright (c) 2012, 2021 Oracle and/or its affiliates. All rights reserved.
 * Copyright (c) 2021 IBM Corporation. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0,
 * or the Eclipse Distribution License v. 1.0 which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
 */

// Contributors:
//     Oracle - initial API and implementation
//
package org.eclipse.persistence.jpa.jpql;

import java.util.List;
import java.util.Map;
import org.eclipse.persistence.jpa.jpql.parser.Expression;
import org.eclipse.persistence.jpa.jpql.parser.IdentificationVariable;
import org.eclipse.persistence.jpa.jpql.parser.JPQLGrammar;
import org.eclipse.persistence.jpa.jpql.parser.SimpleSelectStatement;

/**
 * This helper is used by {@link AbstractSemanticValidator} in order to retrieve JPA information.
 * This helper allows third party adopter to write an instance of this helper that directly access
 * the JPA information without having to implement Hermes SPI, which can improve performance.
 * <p>
 * {@link org.eclipse.persistence.jpa.jpql.tools.GenericSemanticValidatorHelper
 * GenericSemanticValidatorHelper} is a default implementation that uses Hermes SPI.
 * <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.
 *
 * @version 2.5
 * @since 2.4
 * @author Pascal Filion
 */
public interface SemanticValidatorHelper {

    /**
     * Collects the identification variables that are defined in the <code>FROM</code> clause of the
     * current query and from the parent queries.
     *
     * @param identificationVariables The {@link Map} used to store the variables
     */
    void collectAllDeclarationIdentificationVariables(Map<String, List<IdentificationVariable>> identificationVariables);

    /**
     * Collects the identification variables that are defined in the <code>FROM</code> clause of the
     * current query.
     *
     * @param identificationVariables The {@link Map} used to store the variables
     */
    void collectLocalDeclarationIdentificationVariables(Map<String, List<IdentificationVariable>> identificationVariables);

    /**
     * Disposes this context, which is the current context being used by a subquery. Once it is
     * disposed, any information retrieved will be for the subquery's parent query.
     */
    void disposeSubqueryContext();

    /**
     * Returns the name of the all entities that are present in the context of a persistence unit.
     *
     * @return The list of entity names
     */
    String[] entityNames();

    /**
     * Returns the ordered list of {@link JPQLQueryDeclaration}, which contain the information
     * contained in the query's <code>FROM</code> clause.
     *
     * @return The list of {@link JPQLQueryDeclaration} of the current query that was parsed and from
     * the parent queries
     */
    List<JPQLQueryDeclaration> getAllDeclarations();

    /**
     * Returns the constructors for the given type. All public, protected, default (package) access,
     * and private constructors should be included.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be {@link
     * org.eclipse.persistence.jpa.jpql.tools.spi.IType IType} and the return type would be {@link
     * org.eclipse.persistence.jpa.jpql.tools.spi.IConstructor IConstructor}.
     *
     * @return The declared constructors
     */
    Object[] getConstructors(Object type);

    /**
     * Returns the ordered list of {@link JPQLQueryDeclaration}, which contain the information
     * contained in the query's <code>FROM</code> clause.
     *
     * @return The list of {@link JPQLQueryDeclaration} of the current query that was parsed
     */
    List<? extends JPQLQueryDeclaration> getDeclarations();

    /**
     * Retrieves the embeddable with the given type.
     *
     * @param type The Java type of the embeddable to retrieve
     * @return The embeddable for the given type if it's representing an embeddable; <code>null</code>
     * otherwise
     */
    Object getEmbeddable(Object type);

    /**
     * Retrieves the entity with the given entity name.
     *
     * @param entityName The abstract schema name of the entity to retrieve
     * @return The entity with the given name; <code>null</code> otherwise
     */
    Object getEntityNamed(String entityName);

    /**
     * Returns the constant names for the given {@link Enum} type.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IType IType}.
     *
     * @param type The {@link Enum} type
     * @return The list of constant names
     */
    String[] getEnumConstants(Object type);

    /**
     * Returns the {@link JPQLGrammar} that defines how the JPQL query was parsed.
     *
     * @return The {@link JPQLGrammar} that was used to parse the JPQL query
     */
    JPQLGrammar getGrammar();

    /**
     * Returns the managed type by resolving the given {@link Expression}.
     * <p>
     * If it was going through Hermes SPI, the return type would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IManagedType IManagedType}.
     */
    Object getManagedType(Expression expression);

    /**
     * Returns the mapping with the given name.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IManagedType IManagedType}
     * and the return type would be {@link
     * org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping}.
     *
     * @param managedType The managed type that has a mapping with the given name
     * @param name The name of the mapping to retrieve
     * @return Either the mapping or <code>null</code> if it could not be found
     */
    Object getMappingNamed(Object managedType, String name);

    /**
     * Returns the type of the given mapping object.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be {@link
     * org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping} and the return type
     * would be {@link org.eclipse.persistence.jpa.jpql.tools.spi.IType IType}.
     *
     * @param mapping The mapping object
     * @return The type of the given mapping
     */
    Object getMappingType(Object mapping);

    /**
     * Returns the list of type declarations representing the given constructor's parameter types.
     * If this is the default constructor, then an empty array should be returned.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be {@link
     * org.eclipse.persistence.jpa.jpql.tools.spi.IConstructor IConstructor} and the return type would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.ITypeDeclaration ITypeDeclaration}.
     *
     * @param constructor The constructor to return its parameter types
     * @return The list of parameter types or an empty list
     */
    Object[] getMethodParameterTypeDeclarations(Object constructor);

    /**
     * Returns the reference managed type from the given relationship mapping.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be {@link
     * org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping} and the return type would be {@link
     * org.eclipse.persistence.jpa.jpql.tools.spi.IManagedType IManagedType}.
     *
     * @param relationshipMapping The relationship mapping
     * @return The managed type referenced by the given relationship mapping
     */
    Object getReferenceManagedType(Object relationshipMapping);

    /**
     * Returns the type by resolving the given {@link Expression}.
     * <p>
     * If it was going through Hermes SPI, the return type would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IType IType}.
     *
     * @param expression The {@link Expression} to resolve
     * @return The type of the given {@link Expression} or <code>null</code> if it could not be
     * validated
     */
    Object getType(Expression expression);

    /**
     * Returns the type defined for the Java member.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be {@link
     * org.eclipse.persistence.jpa.jpql.tools.spi.ITypeDeclaration ITypeDeclaration} and the return type would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IType IType}.
     *
     * @return The type defined for the Java member
     */
    Object getType(Object typeDeclaration);

    /**
     * Retrieves the class with the given fully qualified name.
     * <p>
     * If it was going through Hermes SPI, an {@link org.eclipse.persistence.jpa.jpql.tools.spi.IType
     * IType} would be returned.
     *
     * @param typeName The fully qualified  name of the class to retrieve
     * @return The class to retrieve
     */
    Object getType(String typeName);

    /**
     * Returns the type declaration for the given {@link Expression}'s type.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.ITypeDeclaration ITypeDeclaration}.
     *
     * @param expression The {@link Expression} to resolve
     * @return Either the type declaration that was resolved for the given {@link Expression}
     */
    Object getTypeDeclaration(Expression expression);

    /**
     * Returns the helper that gives access to the most common class metadata.
     *
     * @return A helper containing a collection of methods related to class metadata
     */
    ITypeHelper getTypeHelper();

    /**
     * Returns the fully qualified class name of the given type.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IType IType}.
     *
     * @param type The type to retrieve its name
     * @return The name of the class represented by this one
     */
    String getTypeName(Object type);

    /**
     * Determines whether type 1 is an instance of type 2.
     * <p>
     * If it was going through Hermes SPI, the type of the arguments would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IType IType}.
     *
     * @param type1 The type to check if it is an instance of type 2
     * @param type2 The type used to determine if the class represented by type 1 is an instance
     * of with one
     * @return <code>true</code> if type 1 is an instance of the type 2; <code>false</code> otherwise
     */
    boolean isAssignableTo(Object type1, Object type2);

    /**
     * Determines whether the given identification variable is defining a join or a collection member
     * declaration expressions.
     *
     * @param variableName The identification variable to check for what it maps
     * @return <code>true</code> if the given identification variable maps a collection-valued field
     * defined in a <code>JOIN</code> or <code>IN</code> expression; <code>false</code> if it's not
     * defined or it's mapping an abstract schema name
     */
    boolean isCollectionIdentificationVariable(String variableName);

    /**
     * Determines whether the given mapping is a collection type mapping.
     * <p>
     * If it was going through Hermes SPI, the type of the arguments would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping}.
     *
     * @param mapping The mapping object to verify if it represents a collection mapping
     * @return <code>true</code> if the given mapping is a collection mapping; <code>false</code>
     * otherwise
     */
    boolean isCollectionMapping(Object mapping);

    /**
     * Determines whether the given mapping is an embeddable type mapping.
     * <p>
     * If it was going through Hermes SPI, the type of the arguments would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping}.
     *
     * @param mapping The mapping object to verify if it represents an embeddable mapping
     * @return <code>true</code> if the given mapping is an embeddable mapping; <code>false</code>
     * otherwise
     */
    boolean isEmbeddableMapping(Object mapping);

    /**
     * Determines whether the given type represents an {@link Enum}.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IType IType}.
     *
     * @return <code>true</code> if the given type is an {@link Enum}; <code>false</code> otherwise
     */
    boolean isEnumType(Object type);

    /**
     * Determines whether an identification variable can be used in a comparison expression when the
     * operator is either {@literal '<', '<=', '>', '>='}.
     *
     * @param expression The {@link IdentificationVariable} that is mapped to either an entity, a
     * singled-object value field, a collection-valued object field
     * @return <code>true</code> if it can be used in a ordering comparison expression; <code>false</code>
     * if it can't
     */
    boolean isIdentificationVariableValidInComparison(IdentificationVariable expression);

    /**
     * Determines whether the given managed type actually exists.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IManagedType IManagedType}.
     *
     * @return <code>true</code> if the given managed type can be located; <code>false</code> if it
     * could not be found
     */
    boolean isManagedTypeResolvable(Object managedType);

    /**
     * Determines whether the given mapping is a property type mapping.
     * <p>
     * If it was going through Hermes SPI, the type of the arguments would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping}.
     *
     * @param mapping The mapping object to verify if it represents a property mapping
     * @return <code>true</code> if the given mapping is a property mapping; <code>false</code> otherwise
     */
    boolean isPropertyMapping(Object mapping);

    /**
     * Determines whether the given mapping is a relationship type mapping.
     * <p>
     * If it was going through Hermes SPI, the type of the arguments would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping}.
     *
     * @param mapping The mapping object to verify if it represents a relationship mapping
     * @return <code>true</code> if the given mapping is a relationship mapping; <code>false</code> otherwise
     */
    boolean isRelationshipMapping(Object mapping);

    /**
     * Determines if the given variable is a result variable.
     *
     * @param variableName The variable to check if it's a result variable
     * @return <code>true</code> if the given variable is defined as a result variable;
     * <code>false</code> otherwise
     */
    boolean isResultVariable(String variableName);

    /**
     * Determines whether the given mapping is a transient attribute.
     * <p>
     * If it was going through Hermes SPI, the type of the arguments would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping}.
     *
     * @param mapping The mapping object to verify if it represents a transient attribute
     * @return <code>true</code> if the given attribute is a transient mapping; <code>false</code> otherwise
     */
    boolean isTransient(Object mapping);

    /**
     * Determines whether type declaration 1 is an instance of type declaration 2.
     * <p>
     * If it was going through Hermes SPI, the type of the arguments would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.ITypeDeclaration ITypeDeclaration}.
     *
     * @param typeDeclaration1 The type declaration to check if it is an instance of type declaration 2
     * @param typeDeclaration2 The type used to determine if the class represented by type
     * declaration 1 is an instance of with one
     * @return <code>true</code> if type declaration 1 is an instance of the type declaration 2;
     * <code>false</code> otherwise
     */
    boolean isTypeDeclarationAssignableTo(Object typeDeclaration1, Object typeDeclaration2);

    /**
     * Determines whether the given type actually exists.
     * <p>
     * If it was going through Hermes SPI, the type of the argument would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IType IType}.
     *
     * @return <code>true</code> if the actual class exists; <code>false</code> otherwise
     */
    boolean isTypeResolvable(Object type);

    /**
     * Changes the state of this helper to use the given subquery.
     *
     * @param expression The parsed tree representation of the subquery that will become the current query
     * @see #disposeSubqueryContext()
     */
    void newSubqueryContext(SimpleSelectStatement expression);

    /**
     * Returns the mapping for the field represented by the given {@link Expression}.
     * <p>
     * If it was going through Hermes SPI, the return type would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping}.
     *
     * @param expression The {@link Expression} representing a state field path expression or a
     * collection-valued path expression
     * @return Either the mapping or <code>null</code> if none exists
     */
    Object resolveMapping(Expression expression);

    /**
     * Returns the mapping that should be a persistence field from the entity defined by the given
     * identification variable.
     * <p>
     * If it was going through Hermes SPI, the return type would be
     * {@link org.eclipse.persistence.jpa.jpql.tools.spi.IMapping IMapping}.
     *
     * @param identificationVariable The identification variable that is defined in the <code>FROM</code>
     * clause of the query (which can be in the current subquery) or in one of the parent queries.
     * @param name The name of the persistent field to retrieve
     * @return The persistence field with the given name or <code>null</code> if it could not be found
     */
    Object resolveMapping(String identificationVariable, String name);
}