TypeHandler.java :  » Database-ORM » ODAL » com » completex » objective » components » persistency » type » Java Open Source

/**
 *  Objective Database Abstraction Layer (ODAL)
 *  Copyright (c) 2004, The ODAL Development Group
 *  All rights reserved.
 *  For definition of the ODAL Development Group please refer to LICENCE.txt file
 *
 *  Distributable under LGPL license.
 *  See terms of license at gnu.org.
 */
package com.completex.objective.components.persistency.type;

import com.completex.objective.components.persistency.PersistentObject;
import com.completex.objective.components.persistency.ColumnType;
import com.completex.objective.components.persistency.OdalPersistencyException;
import com.completex.objective.components.persistency.core.DatabasePolicy;

import java.sql.CallableStatement;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

/**
 * Class to handle database reads and binds
 *
 * @author Gennady Krizhevsky
 */
public interface TypeHandler {

    final static int DEFAULT_CHUNK_SIZE = 2048;

    final static byte[] MINIMAL_BYTE_ARRAY = new byte[1];
    final static String MINIMAL_CLOB_STRING = " ";

    /**
     * Defines how to extract value from ResultSet by column index
     *
     * @param resultSet      ResultSet
     * @param jdbcColIndex   1-based ResultSet column index
     * @param databasePolicy database policy
     * @return a <code>java.lang.Object</code> holding the column value
     * @throws SQLException
     * @see DatabasePolicy
     */
    Object handleRead(ResultSet resultSet, int jdbcColIndex, DatabasePolicy databasePolicy) throws SQLException;

    /**
     * Defines how to extract value from ResultSet by column name
     *
     * @param resultSet
     * @param columnName     ResultSet column name
     * @param databasePolicy database policy
     * @return a <code>java.lang.Object</code> holding the column value
     * @throws SQLException
     * @see DatabasePolicy
     */
    Object handleRead(ResultSet resultSet, String columnName, DatabasePolicy databasePolicy) throws SQLException;

    /**
     * Defines how to bind values for column of specific type. It is used for not null values only
     *
     * @param statement      PreparedStatement
     * @param parameterIndex 1-based binding index
     * @param value          value to bind
     * @throws SQLException
     */
    void handleBind(PreparedStatement statement, int parameterIndex, Object value) throws SQLException;

    /**
     * Defines how to bind values of PersistentObject in update/insert operations. It is used for not null values only
     *
     * @param statement        PreparedStatement
     * @param jdbcColIndex     1-based binding index
     * @param value            value to bind
     * @param databasePolicy   database policy
     * @param postProcessings  post processings used for LOBs for example
     * @param persistentObject object being persisted
     * @param columnIndex      column index in persistentObject
     * @throws SQLException
     * @see CallableStatement
     * @see DatabasePolicy
     * @see LobPostProcessings
     */
    void handleBind(PreparedStatement statement,
                    int jdbcColIndex,
                    Object value,
                    DatabasePolicy databasePolicy,
                    LobPostProcessings postProcessings,
                    PersistentObject persistentObject,
                    int columnIndex) throws SQLException;


    /**
     * Defines how to extract OUT parameter from CallableStatement by parameter index
     *
     * @param statement      CallableStatement
     * @param parameterIndex 1-based out parameter index
     * @param databasePolicy database policy
     * @return out parameter value
     * @throws SQLException
     */
    Object handleOutParamRead(CallableStatement statement, int parameterIndex, DatabasePolicy databasePolicy) throws SQLException;

    /**
     * Defines how to extract OUT parameter from CallableStatement by parameter name
     *
     * @param statement      CallableStatement
     * @param parameterName  the name of the parameter
     * @param databasePolicy database policy
     * @return out parameter value
     * @throws SQLException
     * @see CallableStatement
     * @see DatabasePolicy
     */
    Object handleOutParamRead(CallableStatement statement, String parameterName, DatabasePolicy databasePolicy) throws SQLException;

    /**
     * Used for binding null values in PreparedStatement
     *
     * @param statement        PreparedStatement
     * @param parameterIndex   1-based binding index
     * @param columnType       column type
     * @param columnIdentifier string identifying the column. It is used in error message if bind fails
     */
    void handleBindNull(PreparedStatement statement,
                        int parameterIndex,
                        ColumnType columnType,
                        String columnIdentifier) throws OdalPersistencyException;

    /**
     * Returns true if update has to be done as 2-step bynary update:
     * 1st step - saving a minimal size byte array,
     * 2nd step - retrieving the binary object and update it through its stream
     *
     * @param databasePolicy
     * @return true if update has to be done as 2-step bynary update:
     *         1st step - saving a minimal size byte array,
     *         2nd step - retrieving the binary object and update it through its stream
     */
    boolean useTwoStepBinaryUpdate(DatabasePolicy databasePolicy);
}