数据库访问接口。

 

import java.util.List;
import java.util.Map;

import com.huawei.widget.commons.dao.impl.DBOperationDefault;

/**
 * <p>
 * 数据库访问接口。采用Template方式设计，屏蔽了底层JDBC的操作细节，向客户端提供友好的面向业务的访问接口。
 * 该类的所有方法都为静态的，默认由DBOperation的实现做处理，同时DBUtil屏蔽底层数据库差异（针对不同数据库为统一的访问接口）。
 * </p>
 * <p>
 * 该类的主要使用方法：
 * </p>
 * <p>
 * 1、直接执行SQL语句的能力。
 * </p>
 * <p>
 * 2、通过命名SQL配置文件执行（命名SQL配置文件/WEB-INF/conf/widbeans.*.naming-sql.xml）。
 * </p>
 * <p>
 * 3、提供灵活的行处理回调接口RowMapper实现对业务层的实体封装。
 * </p>
 * <p>
 * 4、带有ByNaming的方法都是采用命名SQL配置方式实现，否则都是直接执行SQL语句的实现。
 * </p>
 * <p>
 * <b>回调方式:</b>
 * </p>
 * <p>
 * <hr>
 * <blockquote>
 *
 * <pre>
 * DBUtil.queryByNaming(SQL_QUERYALLENTITYINFO_NAME,
 *                    new RowMapper&lt;EntityInfo&gt;
 *                    {
 *                      public T mapRow(ResultSet rs, int rowNum) throws SQLException
 *                       {
 *                           EntityInfo info = new EntityInfo();
 *                           info.setId(rs.getInt(ENTITY_ID));
 *                           info.setName(rs.getString(ENTITY_NAME));
 *                           info.setDesc(rs.getString(ENTITY_DESC));
 *                           return (T)info;
 *                      }
 *                     }
 *                    )；
 * </pre>
 *
 * </blockquote>
 * <hr>
 * SQL_QUERYALLENTITYINFO_NAME为命名SQL的配置ID，匿名类RowMapper的实现为回调处理方式。
 * <p>
 * <b>SQL参数设置：</b>
 * <p>
 * <blockquote>
 *
 * <pre>
 * SqlParameterSource为客户端设置SQL语句参数的接口。
 * &lt;p/&gt;
 *       SqlParameterSource sps = new SqlParameterSourceDefault();
 *       sps.addSqlParameter(ENTITY_ID, Types.INTEGER,entity.getId());
 *       sps.addSqlParameter(ENTITY_NAME, Types.VARCHAR, entity.getName());
 *       sps.addSqlParameter(ENTITY_DESC, Types.VARCHAR, entity.getDesc());
 * &lt;/blockquote&gt;
 * </pre>
 *
 * <p/> SqlParameterSource可以设置参数的名称、类型和值。
 * <p>
 * 执行带参数的命名SQL： DBUtil.updateByNaming(SQL_SAVEENTITY_NAME, sps);
 *
 * @author g00106664
 * @version C02 2009-4-27
 * @since OpenEye WIDGET_SRV V100R001C02
 */
@SuppressWarnings("unchecked")
public class DBHelper
{
    /**
     * 持久层的底层访问接口，默认为BME DAS实现。
     */
    private static DBOperation dbOperation = new DBOperationDefault();

    /**
     * 此方法用于设置底层数据访问接口。
     *
     * @param dbOperation
     *            数据操作接口。
     */
    public static void setDbOperation(DBOperation dbOperation)
    {
        DBHelper.dbOperation = dbOperation;
    }

    /**
     * 此方法根据SQL查询并返回int类型的值。DBUtil将自动将查询结果进行int型转换，失败则抛出异常。
     *
     * @param sql
     *            SQL语句，
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return int型。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#queryForInt(String, SqlParameterSource...)
     */
    public static int queryForInt(String sql, SqlParameterSource... args)
            throws DBException
    {
        return dbOperation.queryForInt(sql, args);
    }

    /**
     * 此方法根据SQL查询并返回long类型的值。DBUtil将自动将查询结果进行long型转换，失败则抛出异常。
     *
     * @param sql
     *            SQL语句。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return long型。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#queryForLong(String, SqlParameterSource...)
     */
    public static long queryForLong(String sql, SqlParameterSource... args)
            throws DBException
    {
        return dbOperation.queryForLong(sql, args);
    }

    /**
     * 此方法根据SQL查询并返回Object类型的值。请根据具体Object所指示的具体型别转型处理。
     *
     * @param sql
     *            SQL语句。
     * @param requiredType
     *            实际的转换类型。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return Class<T> requiredType的类型。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#queryForObject(String, Class<T>, SqlParameterSource...)
     */
    public static <T> T queryForObject(String sql, Class<T> requiredType,
            SqlParameterSource... args) throws DBException
    {
        return dbOperation.queryForObject(sql, requiredType, args);
    }

    /**
     * 此方法用于查询并根据RowMapper的具体实现，封装为具体的实体对象返回。
     *
     * @param sql
     *            SQL语句。
     * @param rm
     *            行处理器，实现对结果集单行的封装处理。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return T 行处理器所封装的实体。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#queryForObject(String, RowMapper<T>,
     *      SqlParameterSource...)
     */
    public static <T> T queryForObject(String sql, RowMapper<T> rm,
            SqlParameterSource... args) throws DBException
    {
        return dbOperation.queryForObject(sql, rm, args);
    }

    /**
     * 此方法用于查询并根据RowMapper具体实现封装为具体的实体对象，且将所得的实体对象放置到List中返回。
     *
     * @param sql
     *            SQL语句。
     * @param rm
     *            行处理器，实现对结果集单行的封装处理。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return 实体对象的List。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#query(String, RowMapper<T>, SqlParameterSource...)
     */
    public static <T> List<T> query(String sql, RowMapper<T> rm,
            SqlParameterSource... args) throws DBException
    {
        return dbOperation.query(sql, rm, args);
    }

    /**
     * query(String sql, RowMapper<T> rm, SqlParameterSource... args)方法的分页重载形式。
     *
     * @param sql
     *            SQL语句。
     * @param rm
     *            行处理器，实现对结果集单行的封装处理。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @param pageNo
     *            要查询的页号。
     * @param pageSize
     *            每页要查询的个数。
     * @return 实体对象的List。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#query(String, RowMapper<T>, int, int,
     *      SqlParameterSource...)
     */
    public static <T> List<T> query(String sql, RowMapper<T> rm, int pageNo,
            int pageSize, SqlParameterSource... args) throws DBException
    {
        return dbOperation.query(sql, rm, pageNo, pageSize, args);
    }

    /**
     * 此方法用于查询并根据RowMapper具体实现封装为具体的实体对象，且将所得的实体对象放置到Map中返回。
     *
     * @param sql
     *            SQL语句。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return 实体对象的Map。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#queryForMap(String, SqlParameterSource...)
     */
    public static Map<String, Object> queryForMap(String sql,
            SqlParameterSource... args) throws DBException
    {
        return dbOperation.queryForMap(sql, args);
    }

    /**
     * 此方法通过SQL语句来更新数据库。其中包括insert、update、delete等语句的执行，具体取决于SQL语句的功能。
     *
     * @param sql
     *            SQL语句。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return 返回受SQL语句影响的记录数。
     * @throws DBException
     *             数据层访问异常。详细参考异常错误信息对应表。
     * @see DBOperation#update(String, SqlParameterSource...)
     */
    public static int update(String sql, SqlParameterSource... args)
            throws DBException
    {
        return dbOperation.update(sql, args);
    }

    /**
     * 此方法用于批量更新数据库接口。
     *
     * @param sql
     *            SQL语句。
     * @param batchArgs
     *            待更新SqlParameterSource类型参数。
     * @return the 返回受SQL语句影响的记录数组。
     * @see DBOperation#batchUpdate(String, SqlParameterSource...)
     */
    public static int batchUpdate(String sql, SqlParameterSource... batchArgs)
    {
        return dbOperation.batchUpdate(sql, batchArgs);
    }

    /**
     * 此方法根据命名SQL查询并返回int类型的值。DBUtil将自动将查询结果进行int型转换，失败则抛出异常。
     *
     * @param namingQuery
     *            命名SQL ID，配置在classpath:cmp/das/cmp.naming-sql.xml中。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return int型。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#queryByNamingForInt(String, SqlParameterSource...)
     */
    public static int queryByNamingForInt(String namingQuery,
            SqlParameterSource... args) throws DBException
    {
        return dbOperation.queryByNamingForInt(namingQuery, args);
    }

    /**
     * 此方法根据命名SQL查询并返回long类型的值。DBUtil将自动将查询结果进行long型转换，失败则抛出异常。
     *
     * @param namingQuery
     *            命名SQL ID，配置在classpath:cmp/das/cmp.naming-sql.xml中。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return long型。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#queryByNamingForLong(String, SqlParameterSource...)
     */
    public static long queryByNamingForLong(String namingQuery,
            SqlParameterSource... args) throws DBException
    {
        return dbOperation.queryByNamingForLong(namingQuery, args);
    }

    /**
     * 此方法根据命名SQL查询并返回Object类型的值。请根据具体Object所指示的具体型别转型处理。
     *
     * @param namingQuery
     *            命名SQL语句。
     * @param requiredType
     *            实际的转换类型。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return Class<T> requiredType的类型。
     * @throws DBException
     *             数据层访问异常,详细参考异常错误信息对应表。
     * @see DBOperation#queryForObject(String, Class<T>, SqlParameterSource...)
     */
    public static <T> T queryByNamingForObject(String namingQuery,
            Class<T> requiredType, SqlParameterSource... args)
            throws DBException
    {
        return dbOperation.queryByNamingForObject(namingQuery, requiredType,
                args);
    }

    /**
     * 此方法用于查询并根据RowMapper的具体实现，封装为具体的实体对象返回。
     *
     * @param namingQuery
     *            命名SQL语句。
     * @param rm
     *            行处理器，实现对结果集单行的封装处理。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return 行处理器所封装的实体，RowMapper<T>。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#queryForObject(String, RowMapper<T>,
     *      SqlParameterSource...)
     */
    public static <T> T queryByNamingForObject(String namingQuery,
            RowMapper<T> rm, SqlParameterSource... args) throws DBException
    {
        return dbOperation.queryByNamingForObject(namingQuery, rm, args);
    }

    /**
     * 此方法根据命名SQL查询并根据RowMapper具体实现封装为具体的实体对象，且将所得的实体对象放置到List中返回。
     *
     * @param namingQuery
     *            命名SQL语句。
     * @param rm
     *            行处理器，实现对结果集单行的封装处理。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return 实体对象的List。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#query(String, RowMapper<T>, SqlParameterSource...)
     */
    public static <T> List<T> queryByNaming(String namingQuery,
            RowMapper<T> rm, SqlParameterSource... args) throws DBException
    {
        return dbOperation.queryByNaming(namingQuery, rm, args);
    }

    /**
     * queryByNaming(String namingQuery, RowMapper<T> rm, SqlParameterSource...
     * args)方法的分页重载形式。
     *
     * @param namingQuery
     *            命名SQL语句。
     * @param rm
     *            行处理器，实现对结果集单行的封装处理。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @param pageNo
     *            要查询的页号。
     * @param pageSize
     *            每页要查询的个数。
     * @return 实体对象的List。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#query(String, RowMapper<T>, int, int,
     *      SqlParameterSource...)
     */
    public static <T> List<T> queryByNaming(String namingQuery,
            RowMapper<T> rm, int pageNo, int pageSize,
            SqlParameterSource... args) throws DBException
    {
        return dbOperation.queryByNaming(namingQuery, rm, pageNo, pageSize,
                args);
    }

    /**
     * 此方法根据命名SQL查询并根据RowMapper具体实现封装为具体的实体对象，且将所得的实体对象放置到Map中返回。
     *
     * @param namingQuery
     *            命名SQL语句。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return 实体对象的Map。
     * @throws DBException
     *             数据层访问异常。详细参考异常错误信息对应表。
     * @see DBOperation#queryForMap(String, SqlParameterSource...)
     */
    public static Map<String, Object> queryByNamingForMap(String namingQuery,
            SqlParameterSource... args) throws DBException
    {
        return dbOperation.queryByNamingForMap(namingQuery, args);
    }

    /**
     * 此方法根据命名SQL语句来更新数据库。其中包括insert、update、delete等语句的执行，具体取决于命名SQL的功能。
     *
     * @param namingQuery
     *            命名SQL。
     * @param args
     *            SQL参数，SqlParameterSource类型。
     * @return 返回受SQL语句影响的记录数。
     * @throws DBException
     *             数据层访问异常，详细参考异常错误信息对应表。
     * @see DBOperation#update(String, SqlParameterSource...)
     */
    public static int updateByNaming(String namingQuery,
            SqlParameterSource... args) throws DBException
    {
        return dbOperation.updateByNaming(namingQuery, args);
    }

    /**
     * 此方法根据命名SQL批量更新数据库接口。
     *
     * @param namingQuery
     *            命名SQL语句。
     * @param batchArgs
     *            待更新SqlParameterSource类型参数。
     * @return the 返回受SQL语句影响的记录数组。
     * @see DBOperation#batchUpdate(String, SqlParameterSource...)
     */
    public static int batchUpdateByNaming(String namingQuery,
            SqlParameterSource... batchArgs)
    {
        return dbOperation.batchUpdateByNaming(namingQuery, batchArgs);
    }

    /**
     * 此方法根据SQL查询并返回列表，列表中的每个对象为MAP，其主键与查询中的字段名相对应。
     *
     * @param namingQuery
     *            命名SQL。
     * @param args
     *            the args
     * @return the list<Map>
     * @throws DBException
     *             the DB exception
     */
    public static List<Map> queryByNamingForList(String namingQuery,
            SqlParameterSource... args)
    {
        return dbOperation.queryByNamingForList(namingQuery, args);
    }

    /**
     * 此方法根据SQL查询并返回列表，列表中的每个对象为MAP，其主键与查询中的字段名相对应。
     *
     * @param sql
     *            SQL
     * @param args
     *            the args
     * @return the list<Map>
     * @throws DBException
     *             the DB exception
     */
    public static List<Map> queryForList(String sql, SqlParameterSource... args)
    {
        return dbOperation.queryForList(sql, args);
    }
}