org.apache.openjpa.jdbc.meta.FieldStrategy Maven / Gradle / Ivy

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.    
 */
package org.apache.openjpa.jdbc.meta;

import java.sql.SQLException;

import org.apache.openjpa.jdbc.kernel.JDBCFetchConfiguration;
import org.apache.openjpa.jdbc.kernel.JDBCStore;
import org.apache.openjpa.jdbc.sql.Joins;
import org.apache.openjpa.jdbc.sql.Result;
import org.apache.openjpa.jdbc.sql.RowManager;
import org.apache.openjpa.jdbc.sql.SQLBuffer;
import org.apache.openjpa.jdbc.sql.Select;
import org.apache.openjpa.jdbc.sql.SelectExecutor;
import org.apache.openjpa.kernel.OpenJPAStateManager;

/**
 * Maps a persistent field to the relational schema.
 *
 * @author Abe White
 * @since 0.4.0
 */
public interface FieldStrategy
    extends Strategy {

    /**
     * Set the class mapping using this strategy. This will be called before
     * use.
     */
    public void setFieldMapping(FieldMapping owner);

    /**
     * Return whether this mapping can perform the given select type.
     * Return 0 if the given type is not supported. If the given type is an
     * eager parallel type, return the number of UNIONed selects necessary
     * to fetch the data. Otherwise, return any positive number if the type
     * is supported. The given state manager may be null if selecting
     * multiple instances.
     *
     * @see Select
     */
    public int supportsSelect(Select sel, int type, OpenJPAStateManager sm,
        JDBCStore store, JDBCFetchConfiguration fetch);

    /**
     * Fill in parallel eager select for related objects.
     *
     * @see #select
     */
    public void selectEagerParallel(SelectExecutor sel, OpenJPAStateManager sm,
        JDBCStore store, JDBCFetchConfiguration fetch, int eagerMode);

    /**
     * Fill in joined select to related objects.
     *
     * @see #select
     */
    public void selectEagerJoin(Select sel, OpenJPAStateManager sm,
        JDBCStore store, JDBCFetchConfiguration fetch, int eagerMode);

    /**
     * Whether the eager joins or selects used by this field are to-many.
     */
    public boolean isEagerSelectToMany();

    /**
     * Select the virtual row columns of this mapping.
     *
     * @param sel the select to add to
     * @param sm the instance being loaded, or null if not
     * initialized yet or selecting for multiple instances
     * @param store the current store manager
     * @param fetch fetch configuration
     * @param eagerMode the eager fetch mode to use; this may be more
     * restrictive than the mode of the fetch configuration
     * @return > 0 if this mapping requires the selected data
     * (if any), 0 if it selected data but does not
     * require it, or < 0 if no data was selected
     */
    public int select(Select sel, OpenJPAStateManager sm, JDBCStore store,
        JDBCFetchConfiguration fetch, int eagerMode);

    /**
     * Load the batched eager result.
     *
     * @param res originally the {@link Result} to load from, but this
     * method may return a processed result form that will be
     * passed to subsequent calls
     */
    public Object loadEagerParallel(OpenJPAStateManager sm, JDBCStore store,
        JDBCFetchConfiguration fetch, Object res)
        throws SQLException;

    /**
     * Load the joined eager result.
     */
    public void loadEagerJoin(OpenJPAStateManager sm, JDBCStore store,
        JDBCFetchConfiguration fetch, Result res)
        throws SQLException;

    /**
     * Load virtual row data; the given result is not guaranteed to contain
     * data for this field, so the field mapping should make sure the
     * result contains its needed column data before loading.
     */
    public void load(OpenJPAStateManager sm, JDBCStore store,
        JDBCFetchConfiguration fetch, Result res)
        throws SQLException;

    /**
     * Load secondary data using a connection from the store manager.
     */
    public void load(OpenJPAStateManager sm, JDBCStore store,
        JDBCFetchConfiguration fetch)
        throws SQLException;

    ///////////
    // Queries
    ///////////

    /**
     * Translate the given external field value to its datastore equivalent.
     * If the mapping occupies multiple columns in the datastore, return an
     * object array, else return a single object. Simply returns the given
     * object by default.
     */
    public Object toDataStoreValue(Object val, JDBCStore store);

    /**
     * Translate the given key value to its datastore equivalent. If the
     * mapping occupies multiple columns in the datastore, return an object
     * array, else return a single object. Simply returns the given object by
     * default.
     */
    public Object toKeyDataStoreValue(Object val, JDBCStore store);

    /**
     * Append a where clause to the given statement checking if this value
     * is empty. Appends impossible-to-satisfy SQL by default.
     */
    public void appendIsEmpty(SQLBuffer sql, Select sel, Joins joins);

    /**
     * Append a where clause to the given statement checking if this value
     * is not empty. Appends always-satisfied SQL by default.
     */
    public void appendIsNotEmpty(SQLBuffer sql, Select sel, Joins joins);

    /**
     * Append a where clause to the given statement checking if this value
     * is null.
     */
    public void appendIsNull(SQLBuffer sql, Select sel, Joins joins);

    /**
     * Append a where clause to the given statement checking if this value
     * is not null.
     */
    public void appendIsNotNull(SQLBuffer sql, Select sel, Joins joins);

    /**
     * Append a where clause to the given statement checking the size
     * of the value.
     */
    public void appendSize(SQLBuffer sql, Select sel, Joins joins);

    /**
     * Append the ordered column alias to the given statement.
     */
    public void appendIndex(SQLBuffer sql, Select sel, Joins joins);

    /**
     * Append the entity discriminator value to the given statement.
     */
    public void appendType(SQLBuffer sql, Select sel, Joins joins);

    /**
     * Join this value to the class table. Does nothing by default.
     */
    public Joins join(Joins joins, boolean forceOuter);

    /**
     * Join the key value to the class table. Does nothing by default.
     */
    public Joins joinKey(Joins joins, boolean forceOuter);

    /**
     * Join this value's table to the table for the related first class object
     * type, if any. Does nothing by default.
     *
     * @param traverse if true, throw proper exception if it is not
     * possible for this mapping to traverse into the related type
     */
    public Joins joinRelation(Joins joins, boolean forceOuter,
        boolean traverse);

    /**
     * Join this value's table to the table for the related first class object
     * key type, if any. Does nothing by default.
     *
     * @param traverse if true, throw proper exception if it is not
     * possible for this mapping to traverse into the related type
     */
    public Joins joinKeyRelation(Joins joins, boolean forceOuter,
        boolean traverse);

    /**
     * Load this field value using the given result. The result
     * will contain the columns from {@link ValueMapping#getColumns}.
     */
    public Object loadProjection(JDBCStore store, JDBCFetchConfiguration fetch,
        Result res, Joins joins)
        throws SQLException;

    /**
     * Load this field's key value using the given result. The result will
     * contain the columns from {@link ValueMapping#getColumns}.
     */
    public Object loadKeyProjection(JDBCStore store,
        JDBCFetchConfiguration fetch, Result res, Joins joins)
        throws SQLException;

    //////////////
    // Versioning
    //////////////

    /**
     * Return true if this field can be used as part of a state image for
     * optimistic locking.
     */
    public boolean isVersionable();

    /**
     * Add a WHERE condition to the row for this field such that the field's
     * current DB value must equal the given previous value. Only versionable
     * mappings must implement this method meaningfully.
     */
    public void where(OpenJPAStateManager sm, JDBCStore store, RowManager rm,
        Object prevValue)
        throws SQLException;
}