Copyright (c) 2008 Andy Jefferson and others. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");

you may not use this file except in compliance with the License.

You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software

distributed under the License is distributed on an "AS IS" BASIS,

WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

See the License for the specific language governing permissions and

limitations under the License.

Contributors:

    ...

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

* Class which maps a compiled (generic) query to an SQL query for RDBMS datastores.

* Takes in an SQLStatement, and use of compile() will update the SQLStatement to reflect

* the filter, result, grouping, having, ordering etc.

* <p>

* Supports the following extensions currently :-

* <ul>

* <li><b>datanucleus.query.jdoql.{varName}.join</b> defines the join type for that alias. This only currently

* applies if the variable is (finally) bound using the equality operator (e.g var.field == this.field).

* The extension should be set to "LEFTOUTERJOIN", "INNERJOIN"</li>

* </ul>

* </p>

*/

    /** Localiser for messages. */

    protected static final Localiser LOCALISER = Localiser.getInstance(

        "org.datanucleus.Localisation", org.datanucleus.ClassConstants.NUCLEUS_CONTEXT_LOADER);

    /** Localiser for messages. */

    protected static final Localiser LOCALISER_RDBMS = Localiser.getInstance(

        "org.datanucleus.store.rdbms.Localisation", RDBMSStoreManager.class.getClassLoader());

    public static final String OPTION_CASE_INSENSITIVE = "CASE_INSENSITIVE";

    public static final String OPTION_EXPLICIT_JOINS = "EXPLICIT_JOINS";

    public static final String OPTION_BULK_UPDATE_VERSION = "BULK_UPDATE_VERSION";

    final String candidateAlias;

    final AbstractClassMetaData candidateCmd;

    final QueryCompilation compilation;

    /** Input parameter values, keyed by the parameter name. Will be null if compiled pre-execution. */

    final Map parameters;

    /** Work Map for keying parameter value for the name, for case where parameters input as positional. */

    Map<String, Object> parameterValueByName = null;

    Map<Integer, String> paramNameByPosition = null;

    /** Positional parameter that we are up to (-1 implies not being used). */

    int positionalParamNumber = -1;

    /** Map of query extensions defining behaviour on the compilation. */

    Map<String, Object> extensionsByName = null;

    /** SQL statement that we are updating. */

    final SQLStatement stmt;

    /** Definition of mapping for the results of this SQL statement (candidate). */

    final StatementClassMapping resultDefinitionForClass;

    /** Definition of mapping for the results of this SQL statement (result). */

    final StatementResultMapping resultDefinition;

    Map<Object, SQLExpression> expressionForParameter;

    final RDBMSStoreManager storeMgr;

    final FetchPlan fetchPlan;

    final SQLExpressionFactory exprFactory;

    ExecutionContext ec;

    ClassLoaderResolver clr;

    Imports importsDefinition = null;

    Map<String, Object> compileProperties = new HashMap();

    /** State variable for the component being compiled. */

    CompilationComponent compileComponent;

    /** Stack of expressions, used for compilation of the query into SQL. */

    Stack<SQLExpression> stack = new Stack();

    /** Map of SQLTable/mapping keyed by the name of the primary that it relates to. */

    Map<String, SQLTableMapping> sqlTableByPrimary = new HashMap<String, SQLTableMapping>();

    /** Map of the join primary expression string keyed by the join alias (explicit joins only). */

    Map<String, String> explicitJoinPrimaryByAlias = null;

    Map<String, JavaTypeMapping> paramMappingForName = new HashMap();

    /** Options for the SQL generation process. See OPTION_xxx above. */

    Set<String> options = new HashSet<String>();

    /** Parent mapper if we are processing a subquery. */

    public QueryToSQLMapper parentMapper = null;

    org.datanucleus.store.rdbms.sql.SQLJoin.JoinType defaultJoinType = null;

    /**

     * State variable for whether this query is precompilable (hence whether it is cacheable).

     * Or in other words, whether we can compile it without knowing parameter values.

     */

    boolean precompilable = true;

    {

        SQLTable table;

        AbstractClassMetaData cmd;

        JavaTypeMapping mapping;

        public SQLTableMapping(SQLTable tbl, AbstractClassMetaData cmd, JavaTypeMapping m)

        {

            this.table = tbl;

            this.cmd = cmd;

            this.mapping = m;

        }

        public String toString()

        {

            return "SQLTableMapping: tbl=" + table +

                " class=" + (cmd != null ? cmd.getFullClassName() : "null") +

                " mapping=" + mapping;

        }

    }

    /**

     * Constructor.

     * @param stmt SQL Statement to update with the query contents.

     * @param compilation The generic query compilation

     * @param parameters Parameters needed

     * @param resultDefForClass Definition of results for the statement (populated here)

     * @param resultDef Definition of results if we have a result clause (populated here)

     * @param cmd Metadata for the candidate class

     * @param fetchPlan Fetch Plan to apply

     * @param ec execution context

     * @param importsDefinition Import definition to use in class lookups (optional)

     * @param caseInsensitive Whether aliases are case insensitive (like in JPQL)

     * @param explicitJoins Whether joins are defined explicitly (like in JPQL)

     * @param extensions Any query extensions that may define compilation behaviour

     */

    public QueryToSQLMapper(SQLStatement stmt, QueryCompilation compilation, Map parameters,

            StatementClassMapping resultDefForClass, StatementResultMapping resultDef,

            AbstractClassMetaData cmd, FetchPlan fetchPlan, ExecutionContext ec, Imports importsDefinition,

            Set<String> options, Map<String, Object> extensions)

    {

        this.parameters = parameters;

        this.compilation = compilation;

        this.stmt = stmt;

        this.resultDefinitionForClass = resultDefForClass;

        this.resultDefinition = resultDef;

        this.candidateAlias = compilation.getCandidateAlias();

        this.fetchPlan = fetchPlan;

        this.storeMgr = stmt.getRDBMSManager();

        this.exprFactory = stmt.getRDBMSManager().getSQLExpressionFactory();

        this.candidateCmd = cmd;

        this.ec = ec;

        this.clr = ec.getClassLoaderResolver();

        this.importsDefinition = importsDefinition;

        if (options != null)

        {

            this.options.addAll(options);

        }

        this.extensionsByName = extensions;

        this.stmt.setQueryGenerator(this);

        // Register the candidate

        SQLTableMapping tblMapping =

            new SQLTableMapping(stmt.getPrimaryTable(), candidateCmd, stmt.getPrimaryTable().getTable().getIdMapping());

        setSQLTableMappingForAlias(candidateAlias, tblMapping);

    }

    /**

     * Method to set the default join type to be used.

     * By default we use the nullability of the field to define whether to use LEFT OUTER, or INNER.

     * In JPQL if a relation isn't specified explicitly in the FROM clause then it should use INNER

     * hence where this method will be used, to define the default.

     * @param joinType The default join type

     */

    void setDefaultJoinType(org.datanucleus.store.rdbms.sql.SQLJoin.JoinType joinType)

    {

        this.defaultJoinType = joinType;

    }

    void setParentMapper(QueryToSQLMapper parent)

    {

        this.parentMapper = parent;

    }

    /**

     * Accessor for the query language that this query pertains to.

     * Can be used to decide how to handle the input.

     * @return The query language

     */

    public String getQueryLanguage()

    {

        return compilation.getQueryLanguage();

    }