JPA基础知识----JPA 基本注解，JPA API

JPA 是什么
    Java Persistence API：用于对象持久化的 API
    Java EE 5.0 平台标准的 ORM 规范，使得应用程序以统一的方式访问持久层

JPA和Hibernate的关系
    JPA 是 hibernate 的一个抽象（就像JDBC和JDBC驱动的关系）：
      - JPA 是规范：JPA 本质上就是一种  ORM 规范，不是ORM 框架 —— 因为 JPA 并未提供 ORM 实现，它只是制订了一些规范，提供了一些编程的 API 接口，但具体实现则由 ORM 厂商提供实现
      - Hibernate 是实现：Hibernate 除了作为 ORM 框架之外，它也是一种 JPA 实现
    从功能上来说， JPA 是 Hibernate 功能的一个子集
JPA 的供应商
    JPA 的目标之一是制定一个可以由很多供应商实现的 API，目前Hibernate 3.2+、TopLink 10.1+ 以及 OpenJPA 都提供了 JPA 的实现
    - Hibernate：JPA 的始作俑者就是 Hibernate 的作者。Hibernate 从 3.2 开始兼容 JPA
    - OpenJPA：OpenJPA  是 Apache 组织提供的开源项目
    - TopLink：TopLink 以前需要收费，如今开源了
JPA 包括 3方面的技术
    ORM  映射元数据：JPA 支持 XML 和  JDK 5.0 注解两种元数据的形式，元数据描述对象和表之间的映射关系，框架据此将实体对象持久化到数据库表中。  
    JPA 的 API：用来操作实体对象，执行CRUD操作，框架在后台完成所有的事情，开发者从繁琐的 JDBC和 SQL代码中解脱出来。  
    查询语言（JPQL）：这是持久化操作中很重要的一个方面，通过面向对象而非面向数据库的查询语言查询数据，避免程序和具体的  SQL 紧密耦合。

一、JPA 基本注解

   JPA 基本注解:@Entity, @Table, @Id, @GeneratedValue, @Column, @Basic，@Transient, @Temporal, 用 table 来生成主键详解

1-1、@Entity

    @Entity 标注用于实体类声明语句之前，指出该Java 类为实体类，将映射到指定的数据库表。如声明一个实体类 Customer，它将映射到数据库中的 customer 表上。

1-2、@Table

    当实体类与其映射的数据库表名不同名时需要使用 @Table 标注说明，该标注与 @Entity 标注并列使用，置于实体类声明语句之前，可写于单独语句行，也可与声明语句同行。
    @Table 标注的常用选项是 name，用于指明数据库的表名
    @Table标注还有一个两个选项 catalog 和 schema 用于设置表所属的数据库目录或模式，通常为数据库名。uniqueConstraints 选项用于设置约束条件，通常不须设置。

1-3、@Id

    @Id 标注用于声明一个实体类的属性映射为数据库的主键列。该属性通常置于属性声明语句之前，可与声明语句同行，也可写在单独行上。
    @Id标注也可置于属性的getter方法之前。

1-4、@GeneratedValue

    @GeneratedValue  用于标注主键的生成策略，通过 strategy 属性指定。默认情况下，JPA 自动选择一个最适合底层数据库的主键生成策略：SqlServer 对应 identity，MySQL 对应 auto increment。
在 javax.persistence.GenerationType 中定义了以下几种可供选择的策略：
      - IDENTITY：采用数据库 ID自增长的方式来自增主键字段，Oracle 不支持这种方式；
      - AUTO： JPA自动选择合适的策略，是默认选项；
      - SEQUENCE：通过序列产生主键，通过 @SequenceGenerator 注解指定序列名，MySql 不支持这种方式
      - TABLE：通过表产生主键，框架借由表模拟序列产生主键，使用该策略可以使应用更易于数据库移植。

1-5、@Basic

    @Basic 表示一个简单的属性到数据库表的字段的映射,对于没有任何标注的 getXxxx() 方法,默认即为@Basic
    fetch: 表示该属性的读取策略,有 EAGER 和 LAZY 两种,分别表示主支抓取和延迟加载,默认为 EAGER.
    optional:表示该属性是否允许为null, 默认为true

1-6、@Column

    当实体的属性与其映射的数据库表的列不同名时需要使用@Column 标注说明，该属性通常置于实体的属性声明语句之前，还可与 @Id 标注一起使用。
    @Column 标注的常用属性是 name，用于设置映射数据库表的列名。此外，该标注还包含其它多个属性，如：unique 、nullable、length等。
    @Column 标注的 columnDefinition 属性: 表示该字段在数据库中的实际类型.通常 ORM 框架可以根据属性类型自动判断数据库中字段的类型,但是对于Date类型仍无法确定数据库中字段类型究竟是DATE,TIME还是TIMESTAMP.此外,String的默认映射类型为VARCHAR, 如果要将 String 类型映射到特定数据库的 BLOB 或TEXT 字段类型.
    @Column标注也可置于属性的getter方法之前

1-7、@Transient

    表示该属性并非一个到数据库表的字段的映射,ORM框架将忽略该属性.
    如果一个属性并非数据库表的字段映射,就务必将其标示为@Transient,否则,ORM框架默认其注解为@Basic

1-8、@Temporal

    在核心的 Java API 中并没有定义 Date 类型的精度(temporal precision).  而在数据库中,表示 Date 类型的数据有 DATE, TIME, 和 TIMESTAMP 三种精度(即单纯的日期,时间,或者两者 兼备).在进行属性映射时可使用@Temporal注解来调整精度.

1-9、用 table 来生成主键详解

    将当前主键的值单独保存到一个数据库的表中，主键的值每次都是从指定的表中查询来获得
    这种方法生成主键的策略可以适用于任何数据库，不必担心不同数据库不兼容造成的问题。

/**
 * 注解@Entity映射的表名和类名一样
 * 注解@Table：当实体类与其映射的数据库表名不同名时使用。其中name，用于指明数据库的表名 
 */
@Table(name="JPA_CUTOMERS")
@Entity
public class Customer {
	private Integer id;
	private String lastName;
	private String email;
	private int age;
	private Date createdTime;
	private Date birth;

	public Customer() {}

//用 table 来生成主键详解（用的少）:
//将当前主键的值单独保存到一个数据库的表中，主键的值每次都是从指定的表中查询来获得
//这种方法生成主键的策略可以适用于任何数据库，不必担心不同数据库不兼容造成的问题
/*	@TableGenerator(name="ID_GENERATOR", --name 属性表示该主键生成的名称，它被引用在@GeneratedValue中设置的generator 值中(即这两个名字要一样）
			table="jpa_id_generators",   --table 属性表示表生成策略所持久化的表名
			pkColumnName="PK_NAME",      --pkColumnName 属性的值表示在持久化表中，该主键生成策略所对应键值的名称
			pkColumnValue="CUSTOMER_ID", --pkColumnValue 属性的值表示在持久化表中，该生成策略所对应的主键（跟pkColumnName属性可以确定唯一的一行，该行有很多列）
			valueColumnName="PK_VALUE",  --valueColumnName 属性的值表示在持久化表中，该主键当前所生成的值，它的值将会随着每次创建累加，（再加这个属性能确定唯一的那个点）
			allocationSize=100)          --allocationSize 表示每次主键值增加的大小, 默认值为 50
	@GeneratedValue(strategy=GenerationType.TABLE,generator="ID_GENERATOR")*/
	@GeneratedValue(strategy=GenerationType.AUTO)
	@Id
	public Integer getId() {
		return id;
	}
	public void setId(Integer id) {
		this.id = id;
	}

	/**
	 * 注解@Column 当实体的属性与其映射的数据库表的列不同名时需要使用
	 * nullable=false不能为空
	 */
	@Column(name="LAST_NAME",length=50,nullable=false)
	public String getLastName() {
		return lastName;
	}
	public void setLastName(String lastName) {
		this.lastName = lastName;
	}

	//如果 列名跟字段一样如列名是email，则可以不用写，相关加了@Basic，但字段的属性都是默认的
//	@Basic
	public String getEmail() {
		return email;
	}
	public void setEmail(String email) {
		this.email = email;
	}

	public int getAge() {
		return age;
	}
	public void setAge(int age) {
		this.age = age;
	}

	//---------------------------------------------------------------
	//注解@Temporal 调整时间精度 2015-11-11 10:11:11
	@Temporal(TemporalType.TIMESTAMP)
	public Date getCreatedTime() {
		return createdTime;
	}
	public void setCreatedTime(Date createdTime) {
		this.createdTime = createdTime;
	}
	
	//2015-11-11
	@Temporal(TemporalType.DATE)
	public Date getBirth() {
		return birth;
	}
	public void setBirth(Date birth) {
		this.birth = birth;
	}

	//工具方法. 不需要映射为数据表的一列. 如果没有加@Transient，则会出错，因为没有set方法
	@Transient
	public String getInfo(){
		return "lastName: " + lastName + ", email: " + email;
	}

}

二、JPA API

2-1、JPA相关接口/类：Persistence

    Persistence  类是用于获取 EntityManagerFactory 实例。该类包含一个名为 createEntityManagerFactory 的 静态方法 。
    createEntityManagerFactory 方法有如下两个重载版本。
      - 带有一个参数的方法以 JPA 配置文件 persistence.xml 中的持久化单元名为参数
      - 带有两个参数的方法：前一个参数含义相同，后一个参数 Map类型，用于设置 JPA 的相关属性，这时将忽略其它地方设置的属性。Map 对象的属性名必须是 JPA 实现库提供商的名字空间约定的属性名。

2-2、EntityManagerFactory

    EntityManagerFactory 接口主要用来创建 EntityManager 实例。该接口约定了如下4个方法：
      - createEntityManager()：用于创建实体管理器对象实例。
      - createEntityManager(Map map)：用于创建实体管理器对象实例的重载方法，Map 参数用于提供 EntityManager 的属性。
      - isOpen()：检查 EntityManagerFactory 是否处于打开状态。实体管理器工厂创建后一直处于打开状态，除非调用close()方法将其关闭。
      - close()：关闭 EntityManagerFactory 。 EntityManagerFactory 关闭后将释放所有资源，isOpen()方法测试将返回 false，其它方法将不能调用，否则将导致IllegalStateException异常。

	public static void main(String[] args) {
		
		//1. 创建 EntitymanagerFactory
		//这个名字是persistence.xml配置文件里persistence-unit name="jpa-1"
		String persistenceUnitName = "jpa-1";
		
		//Map<String, Object> properites = new HashMap<String, Object>();
		//该Map的key必须是跟persistence.xml配置文件里property name的值一样
		//properites.put("hibernate.show_sql", false);
		
		//Persistence  类主要是用于获取 EntityManagerFactory 实例
		EntityManagerFactory entityManagerFactory = 
				Persistence.createEntityManagerFactory(persistenceUnitName);
				//Persistence.createEntityManagerFactory(persistenceUnitName, properites); //这个方法用得少，了解就行
				
		//2. 创建 EntityManager. 类似Session .其中entityManagerFactory类似于 Hibernate 的 SessionFactory
		EntityManager entityManager = entityManagerFactory.createEntityManager();
		
		//3. 开启事务
		EntityTransaction transaction = entityManager.getTransaction();
		transaction.begin();
		
		//4. 进行持久化操作
		Customer customer = new Customer();
		customer.setAge(12);
		customer.setEmail("tom@atguigu.com");
		customer.setLastName("Tom");
		customer.setBirth(new Date());
		customer.setCreatedTime(new Date());
		
		entityManager.persist(customer);
		
		//5. 提交事务
		transaction.commit();
		
		//6. 关闭 EntityManager
		entityManager.close();
		
		//7. 关闭 EntityManagerFactory
		entityManagerFactory.close();
	}

2-3、EntityManager

    在 JPA 规范中, EntityManager 是完成持久化操作的核心对象。实体作为普通 Java 对象，只有在调用 EntityManager 将其持久化后才会变成持久化对象。EntityManager 对象 在一组实体类与底层数据源之间进行 O/R 映射的管理。它可以用来管理和更新 Entity Bean, 根椐主键查找 Entity Bean, 还可以通过JPQL语句查询实体。
   实体的状态:
     - 新建状态:   新创建的对象，尚未拥有持久性主键。
     - 持久化状态：已经拥有持久性主键并和持久化建立了上下文环境
     - 游离状态：拥有持久化主键，但是没有与持久化建立上下文环境
     - 删除状态:  拥有持久化主键，已经和持久化建立上下文环境，但是从数据库中删除。
   ① find (Class<T> entityClass,Object primaryKey)：返回指定的 OID 对应的实体类对象，如果这个实体存在于当前的持久化环境，则返回一个被缓存的对象；否则会创建一个新的 Entity, 并加载数据库中相关信息；若 OID 不存在于数据库中，则返回一个 null。第一个参数为被查询的实体类类型，第二个参数为待查找实体的主键值。
    ②getReference (Class<T> entityClass,Object primaryKey)：与find()方法类似， 不同的是：如果缓存中不存在指定的 Entity, EntityManager 会创建一个 Entity 类的代理，但是不会立即加载数据库中的信息，只有第一次真正使用此 Entity 的属性才加载，所以如果此 OID 在数据库不存在，getReference() 不会返回 null 值, 而是抛出EntityNotFoundException
   ③ persist (Object entity)：用于将新创建的 Entity 纳入到 EntityManager 的管理。该方法执行后，传入 persist() 方法的 Entity 对象转换成持久化状态。
      - 如果传入 persist() 方法的 Entity 对象已经处于持久化状态，则 persist() 方法什么都不做。
      - 如果对删除状态的 Entity 进行 persist() 操作，会转换为持久化状态。
      - 如果对游离状态的实体执行 persist() 操作，可能会在 persist() 方法抛出 EntityExistException(也有可能是在flush或事务提交后抛出)。
    ④remove (Object entity)：删除实例。如果实例是被管理的，即与数据库实体记录关联，则同时会删除关联的数据库记录。
    ⑤merge (T entity)：merge() 用于处理 Entity 的同步。即数据库的插入和更新操作
    ⑥flush ()：同步持久上下文环境，即将持久上下文环境的所有未保存实体的状态信息保存到数据库中。
    ⑦setFlushMode (FlushModeType flushMode)：设置持久上下文环境的Flush模式。参数可以取2个枚举
      - FlushModeType.AUTO 为自动更新数据库实体，
      - FlushModeType.COMMIT 为直到提交事务时才更新数据库记录。
    ⑧getFlushMode ()：获取持久上下文环境的Flush模式。返回FlushModeType类的枚举值。
    ⑨refresh (Object entity)：用数据库实体记录的值更新实体对象的状态，即更新实例的属性值。
    ⑩ clear ()：清除持久上下文环境，断开所有关联的实体。如果这时还有未提交的更新则会被撤消。
    ①contains (Object entity)：判断一个实例是否属于当前持久上下文环境管理的实体。
    ② isOpen ()：判断当前的实体管理器是否是打开状态。
    ③getTransaction ()：返回资源层的事务对象。EntityTransaction实例可以用于开始和提交多个事务。
    ④close ()：关闭实体管理器。之后若调用实体管理器实例的方法或其派生的查询对象的方法都将抛出 IllegalstateException 异常，除了getTransaction 和 isOpen方法(返回 false)。不过，当与实体管理器关联的事务处于活动状态时，调用 close 方法后持久上下文将仍处于被管理状态，直到事务完成。

    ①createQuery (String qlString)：创建一个查询对象。
    ②createNamedQuery (String name)：根据命名的查询语句块创建查询对象。参数为命名的查询语句。
    ③createNativeQuery (String sqlString)：使用标准 SQL语句创建查询对象。参数为标准SQL语句字符串。
    ④createNativeQuery (String sqls, String resultSetMapping)：使用标准SQL语句创建查询对象，并指定返回结果集 Map的 名称。

public class APITest {
	private EntityManagerFactory entityManagerFactory;
	private EntityManager entityManager;
	private EntityTransaction transaction;
	
	@Before
	public void init(){
		entityManagerFactory = Persistence.createEntityManagerFactory("jpa-1");
		entityManager = entityManagerFactory.createEntityManager();
		transaction = entityManager.getTransaction();
		transaction.begin();
	}
	
	@After
	public void destroy(){
		transaction.commit();
		entityManager.close();
		entityManagerFactory.close();
	}
	/**
	 * 让缓存中的状态跟数据表中的记录保持一致（与flush相反),会有两个 select
	 * 同 hibernate 中 Session 的 refresh 方法. 
	 */
	@Test
	public void testRefresh(){
		Customer customer = entityManager.find(Customer.class, 1);
		customer = entityManager.find(Customer.class, 1);
		
		entityManager.refresh(customer);
	}
	
	/**
	 * 运行到该方法并在提交事务前 ，会强制发送update语句，（数据库的数据没有改变，因为没提交事务）
	 * 使数据表中的记录跟缓存中对象状态保持一致,刷新缓存
	 * 
	 * 同 hibernate 中 Session 的 flush 方法. 
	 */
	@Test
	public void testFlush(){
		Customer customer = entityManager.find(Customer.class, 1);
		System.out.println(customer);
		
		customer.setLastName("AA");
		
		entityManager.flush();
	}
	
	//情况4: 若传入的是一个游离对象, 即传入的对象有 OID. 
	//1. 若在 EntityManager 缓存中有对应的对象
	//2. JPA 会把游离对象的属性复制到查询到EntityManager 缓存中的对象中.
	//3. EntityManager 缓存中的对象执行 UPDATE. 
	@Test
	public void testMerge4(){
		Customer customer = new Customer();
		customer.setAge(18);
		customer.setBirth(new Date());
		customer.setCreatedTime(new Date());
		customer.setEmail("dd@163.com");
		customer.setLastName("DD");
		
		customer.setId(4);
		Customer customer2 = entityManager.find(Customer.class, 4);
		
		entityManager.merge(customer);
		
		System.out.println(customer == customer2); //false
	}
	
	
	//情况3: 若传入的是一个游离对象, 即传入的对象有 OID. 
	//1. 若在 EntityManager 缓存中没有该对象
	//2. 若在数据库中也（有！！！）对应的记录
	//3. JPA 会查询对应的记录, 然后返回该记录对一个的对象, 再然后会把游离对象的属性复制到查询到的对象中.
	//4. 对查询到的对象执行 update 操作. 
	@Test
	public void testMerge3(){
		Customer customer = new Customer();
		customer.setAge(18);
		customer.setBirth(new Date());
		customer.setCreatedTime(new Date());
		customer.setEmail("ee@163.com");
		customer.setLastName("EE");//setLastName方法中变化EE -- DD --EE
		
		customer.setId(4);
		
		Customer customer2 = entityManager.merge(customer);
		
		System.out.println(customer == customer2); //false
	}
	
	//情况2.若传入的是一个游离对象, 即传入的对象有 OID. 
	//1. 若在 EntityManager 缓存中没有该对象
	//2. 若在数据库中也（没有！！！）对应的记录
	//3. JPA 会创建一个新的对象, 然后把当前游离对象的属性复制到新创建的对象中
	//4. 对新创建的对象执行 insert 操作. 
	@Test
	public void testMerge2(){
		Customer customer = new Customer();
		customer.setAge(18);
		customer.setBirth(new Date());
		customer.setCreatedTime(new Date());
		customer.setEmail("dd@163.com");
		customer.setLastName("DD");
		
		customer.setId(100);
		
		Customer customer2 = entityManager.merge(customer);
		
		//customer没有被持久化，因为如果是持久化，则id不可能为100
		System.out.println("customer#id:" + customer.getId()); //100
		System.out.println("customer2#id:" + customer2.getId()); //4
	}
	
	/**
	 * 总的来说: 类似于 hibernate Session 的 saveOrUpdate 方法.
	 */
	//情况1. 若传入的是一个临时对象,没有id
	//会创建一个新的对象, 把临时对象的属性复制到新的对象中, 然后对新的对象执行持久化操作. 
	//所以新的对象中有 id, 但以前的临时对象中没有 id.
	@Test
	public void testMerge1(){
		Customer customer = new Customer();
		//注意不要设置id,不然会出现异常
		customer.setAge(18);
		customer.setBirth(new Date());
		customer.setCreatedTime(new Date());
		customer.setEmail("cc@163.com");
		customer.setLastName("CC");
		
		//merge返回一个Customer对象
		Customer customer2 = entityManager.merge(customer);
		
		System.out.println("customer#id:" + customer.getId()); //null
		System.out.println("customer2#id:" + customer2.getId()); //3
	}
	
	/************************************************************/
	/**
	 * 类似于 hibernate 中 Session 的 delete 方法. 把对象对应的记录从数据库中移除
	 * 但注意: 该方法只能移除 持久化 对象. 而 hibernate 的 delete 方法实际上还可以移除 游离对象.
	 */
	@Test
	public void testRemove(){
//		Customer customer = new Customer();
//		customer.setId(2);
		
		Customer customer = entityManager.find(Customer.class, 2);
		entityManager.remove(customer);
	}
	
	/**
	 * 类似于 hibernate 的 save 方法. 使对象由临时状态变为持久化状态. 
	 * 	和 hibernate 的 save 方法的不同之处: 若对象有 id, 则不能执行 insert 操作, 而会抛出异常.而hibernate可以 
	 */
	@Test
	public void testPersistence(){
		Customer customer = new Customer();
		customer.setAge(15);
		customer.setBirth(new Date());
		customer.setCreatedTime(new Date());
		customer.setEmail("bb@163.com");
		customer.setLastName("BB");
		//customer.setId(100); //若这里设置 id, 则不能执行 insert 操作, 而会抛出异常. 
		
		entityManager.persist(customer);
		System.out.println(customer.getId());
	}
	
	/**
	 * #getReference类似于 hibernate 中 Session 的 load 方法，会出现懒加载异常
	 * 
	 * 这里与下面的#find输出有点不同: 是先在控制台上打印代理对象，再细线!!，再打sql语句(因为需要才打印的)!!，再打结果
	 */
	@Test
	public void testGetReference(){
		Customer customer = entityManager.getReference(Customer.class, 1);
		System.out.println(customer.getClass().getName()); //com.changwen.jpa.api.Customer_$$_javassit
		
		System.out.println("-------------------------------------");
//		transaction.commit();
//		entityManager.close();
		System.out.println(customer);
	}
	
	/**
	 * #find 类似于 hibernate 中 Session 的 get 方法.
	 */
	@Test
	public void testFind() {
		//这里是先在控制台上打印sql语句，再打细线，再打结果
		Customer customer = entityManager.find(Customer.class, 1);
		System.out.println("-------------------------------------");
		System.out.println(customer);
	}
}

2-4、EntityTransaction

    EntityTransaction 接口用来管理资源层实体管理器的事务操作。通过调用实体管理器的 getTransaction方法 获得其实例。
    ①begin ()：用于启动一个事务，此后的多个数据库操作将作为整体被提交或撤消。若这时事务已启动则会抛出 IllegalStateException 异常。
    ②commit ()：用于提交当前事务。即将事务启动以后的所有数据库更新操作持久化至数据库中。
    ③rollback ()：撤消(回滚)当前事务。即撤消事务启动后的所有数据库更新操作，从而不对数据库产生影响。
    ④setRollbackOnly ()：使当前事务只能被撤消。
    ⑤getRollbackOnly ()：查看当前事务是否设置了只能撤消标志。
    ⑥isActive ()：查看当前事务是否是活动的。如果返回true则不能调用begin方法，否则将抛出 IllegalStateException 异常；如果返回 false 则不能调用 commit、rollback、setRollbackOnly 及 getRollbackOnly 方法，否则将抛出 IllegalStateException 异常。
多与Hibernate进行对比