<commit_before>package org.nutz.dao;

import java.sql.ResultSet;
import java.util.List;

import org.nutz.dao.entity.Entity;
import org.nutz.dao.entity.Record;
import org.nutz.dao.pager.Pager;
import org.nutz.dao.sql.Sql;

/**
 * Nutz.Dao 核心接口。 封装了所有的数据库操作
 * 
 * @author zozoh(<EMAIL>)
 */
public interface Dao {

	/**
	 * @return 数据源的元数据
	 */
	DatabaseMeta meta();

	/**
	 * @return 一个 Sql 管理接口，你可以通过这个接口管理你自定义的 SQL
	 * 
	 * @see org.nutz.dao.SqlManager
	 */
	SqlManager sqls();

	/**
	 * 执行一组 Sql，这些 Sql 将会一起被提交
	 * 
	 * @param sqls
	 *            要被执行的 Sql 数组
	 */
	void execute(Sql... sqls);

	/**
	 * 这个方法试图给你最大的灵活性，因为你的 ConnCallback 实现类将得到一个 Connection 接口
	 * 的实例。请注意，你不需要关闭这个连接，这个函数在退出时会替你关闭连接。
	 * <p>
	 * 如果你从当前连接对象中创建了ResultSet对象或者 Statement对象，请自行关闭。Nutz.Dao 的原则是：
	 * <ul>
	 * <li>Nutz.Dao 创建维护的东西 Nutz.Dao 来维护其生命周期
	 * <li>你创建的东西 （比如 ResultSet） 你来维护其生命周期
	 * </ul>
	 * 
	 * @param callback
	 */
	void run(ConnCallback callback);

	/**
	 * 从一个 ResultSet 中获取一个对象。
	 * <p>
	 * 因为 Dao 接口可以知道一个 POJO 的映射细节，这个函数可以帮你节省一点体力。
	 * 
	 * @param classOfT
	 * @param rs
	 * @param fm
	 * @return 对象
	 */
	<T> T getObject(Class<T> classOfT, ResultSet rs, FieldMatcher fm);

	/**
	 * 将一个对象插入到一个数据源。
	 * <p>
	 * 声明了 '@Id'，的字段会在插入数据库时被忽略，因为数据库会自动为其设值。如果想手动 设置，请设置 '@Id(auto=false)'
	 * <p>
	 * <b>插入之前</b>，会检查声明了 '@Default(@SQL("SELECT ..."))' 的字段，预先执行 SQL 为字段设置。
	 * <p>
	 * <b>插入之后</b>，会检查声明了 '@Next(@SQL("SELECT ..."))' 的字段，通过执行 SQL 将值取回
	 * <p>
	 * 如果你的字段仅仅声明了 '@Id(auto=true)'，没有声明 '@Next'，则认为你还是想取回插入后最新的 ID 值，因为
	 * 自动为你添加类似 @Next(@SQL("SELECT MAX(id) FROM tableName")) 的设置
	 * 
	 * 
	 * 
	 * @param obj
	 *            要被插入的对象
	 *            <p>
	 *            它可以是：
	 *            <ul>
	 *            <li>普通 POJO
	 *            <li>集合
	 *            <li>数组
	 *            <li>Map
	 *            </ul>
	 *            <b style=color:red>注意：</b> 如果是集合，数组或者 Map，所有的对象必须类型相同，否则可能会出错
	 * 
	 * @return 插入后的对象
	 * 
	 * @see org.nutz.dao.entity.annotation.Id
	 * @see org.nutz.dao.entity.annotation.Default
	 * @see org.nutz.dao.entity.annotation.Next
	 */
	<T> T insert(T obj);

	/**
	 * 自由的向一个数据表插入一条数据。数据用名值链描述
	 * 
	 * @param tableName
	 *            数据表名
	 * @param chain
	 *            数据名值链
	 */
	void insert(String tableName, Chain chain);

	/**
	 * 与 insert(String tableName, Chain chain) 一样，不过，数据表名，将取自 POJO 的数据表声明，请参看
	 * '@Table' 注解的详细说明
	 * 
	 * @param classOfT
	 *            实体类型
	 * @param chain
	 *            数据名值链
	 * 
	 * @see org.nutz.dao.entity.annotation.Table
	 */
	void insert(Class<?> classOfT, Chain chain);

	/**
	 * 快速插入一个对象。 对象的 '@Default' 以及 '@Next' 在这个函数里不起作用。
	 * <p>
	 * 即，它不会为你预先获取值，也不会为你在插入后获得自增的主键值。
	 * 
	 * @param obj<commit_msg>修改一下注释，顺便帮助 r1694 彻底删除文件夹 <commit_after>package org.nutz.dao;

import java.sql.ResultSet;
import java.util.List;

import org.nutz.dao.entity.Entity;
import org.nutz.dao.entity.Record;
import org.nutz.dao.pager.Pager;
import org.nutz.dao.sql.Sql;

/**
 * Nutz.Dao 核心接口。 封装了所有的数据库操作
 * 
 * @author zozoh(<EMAIL>)
 */
public interface Dao {

	/**
	 * @return 数据源的元数据
	 */
	DatabaseMeta meta();

	/**
	 * @return 一个 Sql 管理接口，你可以通过这个接口管理你自定义的 SQL
	 * 
	 * @see org.nutz.dao.SqlManager
	 */
	SqlManager sqls();

	/**
	 * 执行一组 Sql，这些 Sql 将会一起被提交
	 * 
	 * @param sqls
	 *            要被执行的 Sql 数组
	 */
	void execute(Sql... sqls);

	/**
	 * 这个方法试图给你最大的灵活性，因为你的 ConnCallback 实现类将得到一个 Connection 接口
	 * 的实例。请注意，你不需要关闭这个连接，这个函数在退出时会替你关闭连接。
	 * <p>
	 * 如果你从当前连接对象中创建了ResultSet对象或者 Statement对象，请自行关闭。Nutz.Dao 的原则是：
	 * <ul>
	 * <li>Nutz.Dao 创建维护的东西 Nutz.Dao 来维护其生命周期
	 * <li>你创建的东西 （比如 ResultSet） 你来维护其生命周期
	 * </ul>
	 * 
	 * @param callback
	 */
	void run(ConnCallback callback);

	/**
	 * 从一个 ResultSet 中获取一个对象。
	 * <p>
	 * 因为 Dao 接口可以知道一个 POJO 的映射细节，这个函数可以帮你节省一点体力。
	 * 
	 * @param classOfT
	 * @param rs
	 * @param fm
	 * @return 对象
	 */
	<T> T getObject(Class<T> classOfT, ResultSet rs, FieldMatcher fm);

	/**
	 * 将一个对象插入到一个数据源。
	 * <p>
	 * 声明了 '@Id'，的字段会在插入数据库时被忽略，因为数据库会自动为其设值。如果想手动 设置，请设置 '@Id(auto=false)'
	 * <p>
	 * <b>插入之前</b>，会检查声明了 '@Default(@SQL("SELECT ..."))' 的字段，预先执行 SQL 为字段设置。
	 * <p>
	 * <b>插入之后</b>，会检查声明了 '@Next(@SQL("SELECT ..."))' 的字段，通过执行 SQL 将值取回
	 * <p>
	 * 如果你的字段仅仅声明了 '@Id(auto=true)'，没有声明 '@Next'，则认为你还是想取回插入后最新的 ID 值，因为
	 * 自动为你添加类似 @Next(@SQL("SELECT MAX(id) FROM tableName")) 的设置
	 * 
	 * 
	 * 
	 * @param obj
	 *            要被插入的对象
	 *            <p>
	 *            它可以是：
	 *            <ul>
	 *            <li>普通 POJO
	 *            <li>集合
	 *            <li>数组
	 *            <li>Map
	 *            </ul>
	 *            <b style=color:red>注意：</b> 如果是集合，数组或者 Map，所有的对象必须类型相同，否则可能会出错
	 * 
	 * @return 插入后的对象
	 * 
	 * @see org.nutz.dao.entity.annotation.Id
	 * @see org.nutz.dao.entity.annotation.Default
	 * @see org.nutz.dao.entity.annotation.Next
	 */
	<T> T insert(T obj);

	/**
	 * 自由的向一个数据表插入一条数据。数据用名值链描述
	 * 
	 * @param tableName
	 *            数据表名
	 * @param chain
	 *            数据名值链
	 */
	void insert(String tableName, Chain chain);

	/**
	 * 与 insert(String tableName, Chain chain) 一样，不过，数据表名，将取自 POJO 的数据表声明，请参看
	 * '@Table' 注解的详细说明
	 * 
	 * @param classOfT
	 *            实体类型
	 * @param chain
	 *            数据名值链
	 * 
	 * @see org.nutz.dao.entity.annotation.Table
	 */
	void insert(Class<?> classOfT, Chain chain);

	/**
	 * 快速插入一个对象。 对象的 '@Default' 以及 '@Next' 在这个函数里不起作用。
	 * <p>
	 * 即，它只会为你预先获取值，但不会为你在插入后获得自增的主键值。
	 * 
	 * @param obj
{'fraction_non_alphanumeric': 0.15651358950328023, 'fraction_numerical': 0.0007497656982193065, 'mean_word_length': 2.492146596858639, 'pattern_counts': {'":': 0, '<': 61, '<?xml version=': 0, '>': 61, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1430027', 'n_tokens_mistral': 2904, 'n_tokens_neox': 2922, 'n_words': 402}