com.pugwoo.dbhelper.DBHelper Maven / Gradle / Ivy

Go to download
package com.pugwoo.dbhelper;

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

import org.springframework.transaction.annotation.Transactional;

import com.pugwoo.dbhelper.exception.MustProvideConstructorException;
import com.pugwoo.dbhelper.exception.NullKeyValueException;
import com.pugwoo.dbhelper.model.PageData;

/**
 * 2015年8月17日 18:18:57
 * @author pugwoo
 */
public interface DBHelper {
	
	/**
	 * 手动回滚@Transactional的事务。
	 * 对于已知需要回滚的动作，我更推荐主动调用让其回滚，而非抛出RuntimeException。
	 * 当前如果没有事务而调用该方法，将抛出org.springframework.transaction.NoTransactionException
	 */
	void rollback();
	
	/**
	 * 当前事务提交后执行
	 * @param runnable
	 * @return 当提交成功返回true，提交失败返回false；如果当前不在事务中时，返回false
	 */
	boolean executeAfterCommit(Runnable runnable);
	
	/**
	 * 设置SQL执行超时的WARN log，超时时间为1秒
	 * @param timeMS 毫秒
	 */
	void setTimeoutWarningValve(long timeMS);
	
	/**
	 * 数据库拦截器
	 * @param interceptors
	 */
	void setInterceptors(List interceptors);

	// ===============Query methods START ==================================
	
	/**
	 * 通过T的主键，将数据查出来并设置到T中

	 * 【会自动处理软删除记录】
	 * 
	 * @param t 值设置在t中
	 * @return 存在返回true，否则返回false
	 */
	 boolean getByKey(T t) throws NullKeyValueException;
	
	/**
	 * 适合于只有一个Key的情况

	 * 【会自动处理软删除记录】
	 * @param clazz
	 * @param keyValue
	 * @return 如果不存在则返回null
	 */
     T getByKey(Class clazz, Object keyValue) throws NullKeyValueException;
    
    /**
     * 通过多个key查询对象

     * 【会自动处理软删除记录】
     * @param clazz
     * @param keyValues
     * @return 返回的值是LinkedHashMap对象，按照keyValues的顺序来，但如果key不存在，那么不会再返回值的map key中
     */
     Map getByKeyList(Class clazz, List keyValues);
	
	/**
	 * 查询列表，没有查询条件

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @param page 从1开始
	 * @param pageSize
	 * @return 返回的data不会是null
	 */
	 PageData getPage(Class clazz, int page, int pageSize);

	/**
	 * 查询列表，postSql可以带查询条件

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @param page 从1开始
	 * @param pageSize
	 * @param postSql 包含where关键字起的后续SQL语句，【不能】包含limit子句
	 * @return 返回的data不会是null
	 */
	 PageData getPage(Class clazz, int page, int pageSize,
			String postSql, Object... args);

	/**
	 * 计算总数

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @return
	 */
	 int getCount(Class clazz);
	
	/**
	 * 计算总数

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @param postSql
	 * @param args
	 * @return
	 */
	 int getCount(Class clazz, String postSql, Object... args);
	
	/**
	 * 查询列表，没有查询条件；不查询总数

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @param page 从1开始
	 * @param pageSize
	 * @return 返回的data不会是null
	 */
	 PageData getPageWithoutCount(Class clazz, int page, int pageSize);
	
	/**
	 * 查询列表，postSql可以带查询条件；不查询总数

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @param page 从1开始
	 * @param pageSize
	 * @param postSql 包含where关键字起的后续SQL语句
	 * @return 返回的data不会是null
	 */
	 PageData getPageWithoutCount(Class clazz, int page, int pageSize,
			String postSql, Object... args);
	
	/**
	 * 查询列表，查询所有记录，如果数据量大请慎用

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @return 返回不会是null
	 */
	 List getAll(Class clazz);
	
	/**
	 * 查询列表，查询所有记录，如果数据量大请慎用

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @return 返回不会是null
	 */
	 List getAll(Class clazz, String postSql, Object... args);

	/**
	 * 查询一条记录，如果有多条，也只返回第一条。该方法适合于知道返回值只有一条记录的情况。

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @return 如果不存在则返回null
	 */
	 T getOne(Class clazz);
	
	/**
	 * 查询一条记录，如果有多条，也只返回第一条。该方法适合于知道返回值只有一条记录的情况。

	 * 【会自动处理软删除记录】
	 * @param clazz 【-支持@JoinTable-】
	 * @param postSql
	 * @param args
	 * @return 如果不存在则返回null
	 */
	 T getOne(Class clazz, String postSql, Object... args);
	
	/**
	 * 是否出现至少一条记录
	 * @param clazz
	 * @param postSql 不能有limit子句
	 * @param args
	 * @return
	 */
	 boolean isExist(Class clazz, String postSql, Object... args);
	
	/**
	 * 是否出现至少N条记录(含N条)
	 * @param atLeastCounts 至少有N条记录（isExist方法等级于atLeastCounts=1）
	 * @param clazz
	 * @param postSql 不能有limit子句
	 * @param args
	 * @return
	 */
	 boolean isExistAtLeast(int atLeastCounts, Class clazz,
			String postSql, Object... args);
	
	/**
	 * 单独抽离出处理RelatedColumn的类，参数t不需要@Table的注解了
	 * @param t
	 */
	 void handleRelatedColumn(T t);
	
	/**
	 * 单独抽离出处理RelatedColumn的类，参数list的元素不需要@Table的注解了。但要求list都同一class类型的对象。
	 * @param list
	 */
	 void handleRelatedColumn(List list);
	
	/**
	 * 单独抽离出处理RelatedColumn的类，参数t不需要@Table的注解了
	 * @param t
	 * @param relatedColumnProperties 只处理制定的这些RelatedColumn注解的成员变量，这个的值是成员变量的名称
	 */
	 void handleRelatedColumn(T t, String... relatedColumnProperties);
	
	/**
	 * 单独抽离出处理RelatedColumn的类，参数list的元素不需要@Table的注解了。但要求list都同一class类型的对象。
	 * @param list
	 * @param relatedColumnProperties 只处理制定的这些RelatedColumn注解的成员变量，这个的值是成员变量的名称
	 */
	 void handleRelatedColumn(List list, String... relatedColumnProperties);
	
	// ===============Query methods END ==================================
	
	/**
	 * 插入一条记录，返回数据库实际修改条数。

	 * 如果包含了自增id，则自增Id会被设置。

	 * 【注】只插入非null的值，如要需要插入null值，则用insertWithNull。
	 * @param t
	 * @return
	 */
	 int insert(T t);
	
	/**
	 * 插入多条记录，返回数据库实际修改的条数。

	 * 实际上，这个是int insert(T t)的循环遍历而已。插入性能并不会因多条而提升。

	 * 【注】只插入非null的值。该方法为一个事务，要么全部插入成功，要么全部插入失败。
	 * @param list
	 * @return
	 */
	@Transactional
	int insert(List list);
	
	/**
	 * 插入一条记录，返回数据库实际修改条数。

	 * 如果包含了自增id，则自增Id会被设置。

	 * 【注】只插入非null的值，如要需要插入null值，则用insertWithNullWhereNotExist。
	 * whereSql是判断条件，当条件成立时，不插入；当条件不成立时，插入。
	 * @param t
	 * @param whereSql 只能是where语句（可含可不含where关键字），【不能】包含order/group/limit等后续语句
	 * @param args
	 * @return
	 */
	 int insertWhereNotExist(T t, String whereSql, Object... args);
	
	/**
	 * 插入一条记录，返回数据库实际修改条数。

	 * 如果包含了自增id，则自增Id会被设置。
	 * @param t
	 * @return
	 */
	 int insertWithNull(T t);
	
	/**
	 * 插入一条记录，返回数据库实际修改条数。

	 * 如果包含了自增id，则自增Id会被设置。

	 * whereSql是判断条件，当条件成立时，不插入；当条件不成立时，插入。
	 * @param t
	 * @param whereSql 只能是where语句（可含可不含where关键字），不能包含order/group/limit等后续语句
	 * @param args
	 * @return
	 */
	 int insertWithNullWhereNotExist(T t, String whereSql, Object... args);
	
	/**
	 * 插入几条数据，通过拼凑成一条sql插入
	 *【重要】批量插入不支持回设自增id。批量插入会把所有属性都插入，不支持只插入非null的值。
	 * (说明:这个方法之前叫insertInOneSQL)
	 * @param list
	 * @return 返回影响的行数
	 */
	 int insertWithNullInOneSQL(List list);
	
	/**
	 * 如果t有主键，则更新值；否则插入记录。只有非null的值会更新或插入。
	 * @param t
	 * @return 返回数据库实际修改的条数
	 */
	 int insertOrUpdate(T t);
	
	/**
	 * 如果t有主键，则更新值；否则插入记录。包括null的值会更新或插入。
	 * @param t
	 * @return 返回数据库实际修改的条数
	 */
	 int insertOrUpdateWithNull(T t);
	
	/**
	 * 如果t有主键，则更新值；否则插入记录。只有非null的值会更新或插入。
	 * @param list
	 * @return 返回数据库实际修改的条数
	 */
	@Transactional
	 int insertOrUpdate(List list);
	
	/**
	 * 如果t有主键，则更新值；否则插入记录。包括null的值会更新或插入。
	 * @param list
	 * @return 返回数据库实际修改的条数
	 */
	@Transactional
	 int insertOrUpdateWithNull(List list);
	
	/**
	 * 全量更新指定的列表，只处理非null字段。dbList表示原来的数据，必须都带上key。

	 * newList表示新的数据，可以带有key也可以没有。

	 * 对于dbList有的key但是newList中没有的key，将被删除。

	 * 对于dbList有的key且newList也有的key，将被更新。

	 * 对于dbList没有的key，但newList中有的key，将被更新。

	 * 对于dbList没有的key，但newList也没有key的对象，将被插入。

	 * @param dbList 可以是null，等同于空list
	 * @param newList 不能是null，否则该方法什么都不执行
	 * @return newList成功的值，不包括dbList中删除的
	 */
	@Transactional
	 int insertOrUpdateFull(List dbList, List newList);
	
	/**
	 * 文档同insertOrUpdateFull，只是会insert or update null值
	 * @param dbList
	 * @param newList
	 * @return
	 */
	@Transactional
	 int insertOrUpdateFullWithNull(List dbList, List newList);
		
	/**
	 * 更新单个实例数据库记录，必须带上object的key，包含更新null值的字段
	 * @param t
	 * @return 返回数据库实际修改条数
	 * @throws NullKeyValueException
	 */
	 int updateWithNull(T t) throws NullKeyValueException;
	
	/**
	 * 带条件的更新单个对象，必须带上object的key，主要用于mysql的update ... where ...这样的CAS修改
	 * 
	 * @param t
	 * @param postSql where及后续的sql，包含where关键字
	 * @param args
	 * @return 返回数据库实际修改条数
	 * @throws NullKeyValueException
	 */
	 int updateWithNull(T t, String postSql, Object... args) throws NullKeyValueException;
	
	/**
	 * 更新单条数据库记录,必须带上object的key。【只更新非null字段】
	 * @param t
	 * @return 返回数据库实际修改条数
	 * @throws NullKeyValueException
	 */
	 int update(T t) throws NullKeyValueException;
	
	/**
	 * 更新单条数据库记录,必须带上object的key，主要用于mysql的update ... where ...这样的CAS修改。
	 * 【只更新非null字段】
	 * 
	 * @param t
	 * @param postSql where及后续的sql，包含where关键字
	 * @param args
	 * @return 返回数据库实际修改条数
	 * @throws NullKeyValueException
	 */
	 int update(T t, String postSql, Object... args) throws NullKeyValueException;
	
	/**
	 * 自定义set字句更新，用于单个sql进行值更新，例如set reads = reads + 1这种情况。因此不提供CAS功能。
	 * @param t 必须提供key
	 * @param setSql 可包含set关键字也可不包含，多个则用逗号隔开，【不能】包含where子句，例如a=a+1,c=b 或 set a=a+1,c=b
	 * @param args set子句的参数
	 * @return
	 * @throws NullKeyValueException 当t没有带上key时，抛出该异常
	 */
	 int updateCustom(T t, String setSql, Object... args) throws NullKeyValueException;
	
	/**
	 * 自定义更新多行记录，会自动去掉已软删除的行
	 * @param clazz
	 * @param setSql update sql中的set sql子句，可以包括set关键字也可以不包括
	 * @param whereSql update sql中的where sql子句，可以包括where关键字也可以不包括
	 * @param args
	 * @return
	 */
	 int updateAll(Class clazz, String setSql, String whereSql, Object... args);
	
	/**
	 * 更新数据库记录，更新包含null的字段，返回数据库实际修改条数。
	 * 【注】批量更新的方法并不会比程序中循环调用int updateNotNull(T t)更快
	 * @param list
	 * @return
	 * @throws NullKeyValueException
	 */
	@Transactional
	 int updateWithNull(List list) throws NullKeyValueException;
	
	/**
	 * 更新数据库记录，返回数据库实际修改条数。
	 * 【注】批量更新的方法并不会比程序中循环调用int update(T t)更快
	 * 【只更新非null字段】
	 * @param list
	 * @return
	 * @throws NullKeyValueException
	 */
	@Transactional
	 int update(List list) throws NullKeyValueException;
	
	/**
	 * 删除数据库记录，返回数据库实际修改条数。
	 * 该操作【会】自动使用软删除进行删除
	 * 
	 * @param t
	 * @return
	 */
	 int deleteByKey(T t) throws NullKeyValueException;
	
	/**
	 * 删除数据库记录，返回实际修改数据库条数，这个接口只支持单个字段是key的情况。
	 * 该操作【会】自动使用软删除进行删除
	 * 
	 * @param clazz 必须有默认构造方法
	 * @param keyValue
	 * @return
	 * @throws NullKeyValueException
	 */
	 int deleteByKey(Class clazz, Object keyValue) throws NullKeyValueException,
	    MustProvideConstructorException;

	/**
	 * 自定义条件删除数据，该操作【会】自动使用软删除标记
	 * @param clazz 必须有默认构造方法
	 * @param postSql 必须提供，必须写where，【不允许】留空
	 * @param args
	 * @return
	 */
	 int delete(Class clazz, String postSql, Object... args);
	
}