jpa/org.eclipse.persistence.jpa.jpql/src/main/java/org/eclipse/persistence/jpa/jpql/tools/model/IJPQLQueryBuilder.java

/*
 * Copyright (c) 2011, 2020 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 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.tools.model;

import org.eclipse.persistence.jpa.jpql.parser.JPQLGrammar;
import org.eclipse.persistence.jpa.jpql.tools.model.query.AbstractConditionalClauseStateObject;
import org.eclipse.persistence.jpa.jpql.tools.model.query.JPQLQueryStateObject;
import org.eclipse.persistence.jpa.jpql.tools.model.query.SelectClauseStateObject;
import org.eclipse.persistence.jpa.jpql.tools.model.query.SimpleSelectClauseStateObject;
import org.eclipse.persistence.jpa.jpql.tools.model.query.StateObject;
import org.eclipse.persistence.jpa.jpql.tools.model.query.UpdateItemStateObject;
import org.eclipse.persistence.jpa.jpql.tools.spi.IManagedTypeProvider;

/**
 * This builder is responsible to create an editable {@link StateObject} representation of a JPQL
 * query.
 * <p>
 * Some default implementations are available:
 * <ul>
 * <li>Generic JPA 1.0: {@link JPQLQueryBuilder1_0}</li>
 * <li>Generic JPA 2.0: {@link JPQLQueryBuilder2_0}</li>
 * <li>EclipseLink: {@link EclipseLinkJPQLQueryBuilder}</li>
 * </ul>
 *
 * @see IManagedTypeProvider
 * @see StateObject
 *
 * @version 2.4
 * @since 2.4
 * @author Pascal Filion
 */
public interface IJPQLQueryBuilder {

    /**
     * Creates a builder that can create a <code><b>CASE</b></code> expression programmatically. Once
     * the expression is complete, {@link ICaseExpressionStateObjectBuilder#buildStateObject()} will
     * return the result.
     *
     * @param parent The {@link StateObject} that will be the parent of the newly created model
     * @return The builder of a <code><b>CASE</b></code> expression
     */
    ICaseExpressionStateObjectBuilder buildCaseExpressionStateObjectBuilder(StateObject parent);

    /**
     * Creates a state model representation of a JPQL query that can be edited.
     *
     * @param provider The provider of managed types
     * @param jpqlQuery The JPQL query to parse into a {@link StateObject} model
     * @param tolerant Determines if the parsing system should be tolerant, meaning if it should try
     * to parse invalid or incomplete queries
     * @return The root of the {@link StateObject} model that represents the edited form of the JPQL query
     */
    JPQLQueryStateObject buildStateObject(IManagedTypeProvider provider,
                                          CharSequence jpqlQuery,
                                          boolean tolerant);

    /**
     * Creates a state model representation of a JPQL query that can be edited.
     *
     * @param provider The provider of managed types
     * @param jpqlQuery The JPQL query to parse into a {@link StateObject} model
     * @param queryBNFId The unique identifier of the query BNF that will be used to parse the fragment
     * @param tolerant Determines if the parsing system should be tolerant, meaning if it should try
     * to parse invalid or incomplete queries
     * @return The root of the {@link StateObject} model that represents the edited form of the JPQL query
     */
    JPQLQueryStateObject buildStateObject(IManagedTypeProvider provider,
                                          CharSequence jpqlQuery,
                                          String queryBNFId,
                                          boolean tolerant);

    /**
     * Creates a {@link StateObject} representation of the given JPQL fragment. In order to properly
     * parse the fragment, the given unique identifier of the
     * {@link org.eclipse.persistence.jpa.jpql.parser.JPQLQueryBNF JPQLQueryBNF} will determine how to parse it.
     * <p>
     * It is possible the given JPQL fragment has more than one expression, in this case, parsing
     * should stop at the first comma (x, y) or space (x y) where x and y are two separate expressions.
     *
     * @param parent The {@link StateObject} that will be the parent of the newly created model
     * @param jpqlFragment A portion of a JPQL query that will be parsed and the {@link StateObject}
     * representation will be created
     * @param queryBNFId The unique identifier of the query BNF that will be used to parse the fragment
     * @return The {@link StateObject} representation of the given JPQL fragment
     */
    StateObject buildStateObject(StateObject parent, CharSequence jpqlFragment, String queryBNFId);

    /**
     * Creates a builder that can create a conditional expression programmatically. Once the
     * expression is complete, {@link IConditionalExpressionStateObjectBuilder#commit()} will push
     * the result onto the given state object.
     *
     * @param stateObject The clause for which a conditional expression can be created
     * @return The builder of a conditional expression
     */
    IConditionalExpressionStateObjectBuilder buildStateObjectBuilder(AbstractConditionalClauseStateObject stateObject);

    /**
     * Creates a builder that can create a select expression programmatically. Once the expression is
     * complete, {@link ISelectExpressionStateObjectBuilder#commit()} will push the result onto the
     * given state object.
     *
     * @param stateObject The clause for which one or many select expressions can be created
     * @return The builder of a conditional expression
     */
    ISelectExpressionStateObjectBuilder buildStateObjectBuilder(SelectClauseStateObject stateObject);

    /**
     * Creates a builder that can create a single select expression programmatically. Once the
     * expression is complete, {@link ISimpleSelectExpressionStateObjectBuilder#commit()} will push
     * the result onto the given state object.
     *
     * @param stateObject The clause for which a select expression can be created
     * @return The builder of a conditional expression
     */
    ISimpleSelectExpressionStateObjectBuilder buildStateObjectBuilder(SimpleSelectClauseStateObject stateObject);

    /**
     * Creates a builder that can create a new value expression programmatically. Once the
     * expression is complete, {@link INewValueStateObjectBuilder#commit()} will push the result
     * onto the given state object.
     *
     * @param stateObject The parent for which a new value expression can be created
     * @return The builder of a new value expression
     */
    INewValueStateObjectBuilder buildStateObjectBuilder(UpdateItemStateObject stateObject);

    /**
     * Returns the {@link JPQLGrammar} that is associated with this builder.
     *
     * @return The {@link JPQLGrammar} that was used to parse the JPQL query or JPQL fragments
     */
    JPQLGrammar getGrammar();
}