所需软件

• JDK 1.5

• 教程源代码 (order-jsf-jpa.zip)

• 关系数据库

  您可以使用任意的最新的关系数据库。

  本教程使用的数据库是 Oracle 数据库快捷版：

  • Oracle 数据库快捷版 - Linux 版

  • Oracle 数据库快捷版 - Windows 版

  请使用为您的数据库推荐的 JDBC 驱动程序。

  Oracle 数据库快捷版的 JDBC 驱动程序位于 <ORACLE_HOME>\jdbc\lib 中。

• Web 容器：

  您可以使用任意的 Web 容器。

  本教程假设您使用了以下 Web 容器之一：

  • Tomcat 版本 5.x

• TopLink JPA

  单击上面的链接将下载一个 TopLink JPA 安装程序 JAR 文件，如 glassfish-persistence-installer-X.X-bXX.jar。

安装与配置

在开始本教程之前，您必须安装并配置好所需的软件：

1. 安装 JDK 5.0

2. 安装教程应用程序。

   • 将 order-jsf-jpa.zip 文件解压缩到您计算机上的一个目录中。

     这是 <TUTORIAL_HOME> 目录。

     解压缩完成后，应该包括以下文件：

     • jpa-example.war - 用于进行部署的完整应用程序包。

     • jpa-example-src.jar - 所有非持续性源文件。

     • persistence-unit-src.jar - 所有持续性源文件，其中包括 persistence.xml 文件。

   • 在 <TUTORIAL_HOME> 中创建一个子目录 <WAR_HOME>，并将 jpa-example.war 文件解压缩到该子目录中。

   有关教程应用程序的更多信息，请参见 了解教程应用程序。

3. 安装并设置您的关系数据库：

   • 安装 Oracle 数据库快捷版 - Linux 版

   • Oracle 数据库快捷版 - Windows 版

   • Oracle 数据库快捷版入门

   • 将关系数据库 JDBC 驱动程序添加到教程应用程序 WAR 文件子目录 <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\lib 中。

4. 安装并设置 Web 容器：

   • 安装并设置 Tomcat

5. 安装 TopLink JPA：

   • 将 TopLink JPA 安装程序 JAR 文件转移到临时目录中。

   • 通过在命令行中输入以下命令来执行您所下载的 TopLink JPA 安装程序 JAR 文件（必须使用 JDK 1.5）：

     java -jar glassfish-persistence-installer-X.X-bXX.jar
     
     

   • 向下滚动到许可协议的末尾，单击 Accept。

     安装程序会解开 README、许可文件和 TopLink Essential JAR 文件，如下所示：

     glassfish-persistence\README
     glassfish-persistence\3RD-PARTY-LICENSE.txt
     glassfish-persistence\toplink-essentials.jar
     glassfish-persistence\toplink-essentials-agent.jar
     glassfish-persistence\CDDLv1.0.txt
     
     

   • 将 toplink-essentials.jar 和 toplink-essentials-agent.jar 添加到教程应用程序 WAR 文件子目录 <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\lib 中。

了解教程应用程序

教程应用程序及其所有必要组件都包含在解压缩到 <TUTORIAL_HOME>\<WAR_HOME> 目录的名为 jpa-example.war 的 WAR 文件中（参见安装与配置）。

示例 1-1 显示了此 WAR 文件的结构，表 1-1 描述了该文件中每个重要的子目录。

images
WEB-INF
classes/
oracle/toplink/jpa/example/inventory/
services/
InventoryService.class
OrderService.class
services/impl/
JPAResourceBean.class
ManagedInventoryBean.class
ManagedOrderBean.class
tools/
DDLGenerator.class
Populator.class
ui/
InventoryManagerBean.class
lib/
- JSF JARs
- JDBC driver JARs
toplink-essentials.jar
toplink-essentials-agent.jar
jpa-demo.jar
faces-config.xml
web.xml
*.jsp

第 1 步：批注实体

批注是使用元数据对 Java 源代码进行修饰的一种简单、明确的方法，该元数据将被编译进相应的 Java 类文件，在运行时期间由 JPA 持续性提供器对其进行解释以管理 JPA 行为。

使用 JPA 批注修饰持续性类可以为 JPA 持续性提供程序指明哪些类需要持续性，并且可以指定持续性类的详细内容。

在大多数情况下，您可以使用 JPA 的默认值。本教程显示了必需的批注和一些普通的可选批注。

有关更多信息，请参见 JPA 批注引用。

在本教程中，为实体使用批注的目的是：

• 指定持续性类：@Entity

• 指定关系数据库表：@Table

• 指定主键：@Id

• 指定数据库列的属性：@Column

• 指定乐观锁定字段：@Version

• 指定命名查询：@NamedQuery 和 @NamedQueries

@Entity
public class Item {
    ...
}

@Entity
// specify table name as the default will be ORDER which is a reserved word
@Table(name="ORDER_TABLE")
...
public class Order {
    ...
}

public class Order {

@Id
@GeneratedValue
protected long orderId;
    ...
}

public class Inventory {
@Id
@Column(insertable=false, updatable=false)
protected long id;
    ...
public void setItem(Item item) {
this.item = item;
this.id = item.getSKU();
    }
    ...
}

@Entity
public class Item {
protected long SKU;
    ...
@Id
@GeneratedValue
public long getSKU() {
return SKU;
    }
    ...
}

public class Inventory {
@Id
@Column(insertable=false, updatable=false)
protected long id;
    ...
public void setItem(Item item) {
this.item = item;
this.id = item.getSKU();
    }
    ...
}

public class Inventory {
    ...
@OneToOne
@JoinColumn(name="ID")
protected Item item;
    ...
}

public class Order {
    ...
@Version
protected int version;
    ...
}

public class Inventory {
    ...
@Version
protected int version;
    ...
}

public class Item {
    ...
@Version
public void setVersion(int version) {
this.version = version;
    }
    ...
}

@NamedQuery(
name="inventoryForCategory",
query="SELECT i FROM Inventory i WHERE i.item.category = :category and i.quantity <= :maxQuantity"
)

@NamedQueries({

@NamedQuery(
name="shippedOrdersForItem",
query="SELECT o FROM Order o JOIN o.item i WHERE i.sKU = :itemId and o.arrivalDate is not null"
    ),

@NamedQuery(
name="pendingOrdersForItem",
query="SELECT o FROM Order o WHERE o.item.sKU = :itemId and o.arrivalDate is null"
    )
})

第 2 步：配置持续性单元

实体管理器是您用来对实体实施基本持续性操作（创建、读取、更新和删除）的主要 JPA 界面。

一个持续性单元通过对实体管理器供应商、配置属性和持续性管理的类等详细内容进行逻辑分组来定义实体管理器的配置。

每个持续性单元都必须拥有名称。一个指定的 EJB-JAR、WAR、EAR 或应用程序客户端 JAR 中只能存在给定名称的一个持续性单元（参见打包 Persistence.xml 文件）。在获取实体管理器工厂时，您根据名称来指定持续性单元（参见获取实体管理器工厂）。

持续性单元在 persistence.xml 文件中定义。

在本教程中，persistence.xml 文件包含在 <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\lib\jpa-demo.jar 中。在此 persistence.xml 文件中，我们定义了示例 1-14 显示的持续性单元。

...
<persistence-unit name="default" transaction-type="RESOURCE_LOCAL">
<provider>
oracle.toplink.essentials.PersistenceProvider
</provider>
<exclude-unlisted-classes>false</exclude-unlisted-classes>
<properties>
<property name="toplink.jdbc.driver" value="oracle.jdbc.OracleDriver"/>
<property name="toplink.jdbc.url" value="jdbc:oracle:thin:@myhost:l521:MYSID"/>
<property name="toplink.jdbc.password" value="tiger"/>
<property name="toplink.jdbc.user" value="scott"/>
</properties>
</persistence-unit>
...

第 3 步：使用 JPA 实施服务

管理教程用户界面的主要资源是 oracle.toplink.jpa.example.inventory.ui.InventoryManagerBean。该资源中包含对以下各类的引用，这些类使用 JPA 实施此应用程序提供的服务：

• oracle.toplink.jpa.example.inventory.services.impl.ManagedOrderBean（实施 oracle.toplink.jpa.example.inventory.services.OrderService）

• oracle.toplink.jpa.example.inventory.services.impl.ManagedInventoryBean（实施 oracle.toplink.jpa.example.inventory.services.InventoryService）

这两个类显示了使用 JPA 进行以下操作的方法：

• 获取实体管理器工厂

• 创建实体

• 读取实体

• 更新实体

• 删除实体

public EntityManagerFactory getEMF (){
if (emf == null){
emf = Persistence.createEntityManagerFactory("default");
    }
return emf;
}

public void  createNewOrder(Order order){
EntityManager em = jpaResourceBean.getEMF().createEntityManager();
try{
em.getTransaction().begin();
em.persist(order);
em.getTransaction().commit();
}finally{
em.close();
    }
}

public Order getOrderById(long orderId){
EntityManager em = jpaResourceBean.getEMF().createEntityManager();
try{
return em.find(Order.class, orderId);
}finally{
em.close();
    }
}

public void alterOrderQuantity(long orderId, int newQuantity){
EntityManager em = jpaResourceBean.getEMF().createEntityManager();
try{
em.getTransaction().begin();
Order order = em.find(Order.class, orderId);
order.setQuantity(newQuantity);
em.getTransaction().commit();
}finally{
em.close();
    }
}

public void requestCancelOrder(long orderId){
EntityManager em = jpaResourceBean.getEMF().createEntityManager();
try{
em.getTransaction().begin();
Order order = em.find(Order.class, orderId);
em.remove(order);
em.getTransaction().commit();
}finally{
em.close();
    }
}

第 4 步：使用命名查询和动态查询

ManagedOrderBean 和 ManagedInventoryBean 类都使用 JPA 查询。本节描述了它们如何使用 JPA 进行以下操作：

• 利用命名查询来查询实体

• 利用动态查询来查询实体

public Collection<Inventory> getInventoryForCategoryMaxQuantity(String category, int quantity){
EntityManager em = jpaResourceBean.getEMF().createEntityManager();
try{
Query query = em.createNamedQuery("inventoryForCategory");
query.setParameter("category", category);
query.setParameter("maxQuantity", quantity);
return query.getResultList();
}finally{
em.close();
    }
}

public Collection<Category> getCategories(){
EntityManager em = jpaResourceBean.getEMF().createEntityManager();
Collection<Category> result = em.createQuery("Select new oracle.toplink.jpa.example.inventory.nonentity.Category(i.category) from Item i group by i.category").getResultList();
em.close();
return result;
}

第 5 步：打包与部署

本节介绍了如何打包和部署教程应用程序，其中包括以下操作：

• 打包 Persistence.xml 文件

• 利用 Tomcat 5.x 进行打包和部署

第 6 步：生成数据库模式并进行填充

在运行教程应用程序前，您必须创建并填充数据库模式，如下所示：

1. 编辑示例 1-22 中显示的命令行，使类路径包含以下内容：

   • <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\classes

   • <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\lib\jpa-demo.jar

   • 所有 JDBC JAR

     对于 Oracle 数据库，请确保将 dms.jar 包含在内。

   • <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\lib\toplink-essentials-agent.jar

   • <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\lib\toplink-essentials.jar

   在此示例中，<TUTORIAL_HOME>\<WAR_HOME> 为 C:\Temp\war。

   示例 1-22 利用 DDLGenerator 生成模式

   java.exe -client -classpath "C:\Temp\war\WEB-INF\classes;C:\Temp\war\WEB-INF\lib\dms.jar;C:\Temp\war\WEB-INF\lib\jpa-demo.jar;C:\Temp\war\WEB-INF\lib\ocrs12.jar;C:\Temp\war\WEB-INF\lib\ojdbc14dms.jar;C:\Temp\war\WEB-INF\lib\ojdl.jar;C:\Temp\war\WEB-INF\lib\orai18n.jar;C:\Temp\war\WEB-INF\lib\toplink-essentials-agent.jar;C:\Temp\war\WEB-INF\lib\toplink-essentials.jar" -Dtoplink.ddl-generation=drop-and-create-tables oracle.toplink.jpa.example.inventory.tools.DDLGenerator
   
   

   
   

   注意： 有关使用供应商扩展功能管理模式生成的更多信息，参见 TopLink 用于模式生成的供应商扩展功能。

   
   

2. 执行命令行。

3. 编辑示例 1-23 显示的命令行，使类路径包含以下内容：

   • <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\classes

   • <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\lib\jpa-demo.jar

   • 所有 JDBC JAR

     对于 Oracle 数据库，请确保将 dms.jar 包含在内。

   • <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\lib\toplink-essentials-agent.jar

   • <TUTORIAL_HOME>\<WAR_HOME>\WEB-INF\lib\toplink-essentials.jar

   在此示例中，<TUTORIAL_HOME>\<WAR_HOME> 为 C:\Temp\war。

   示例 1-23 利用 Populator 填充模式

   java.exe -client -classpath "C:\Temp\war\WEB-INF\classes;C:\Temp\war\WEB-INF\lib\jpa-demo.jar;C:\Temp\war\WEB-INF\lib\dms.jar;C:\Temp\war\WEB-INF\lib\ocrs12.jar;C:\Temp\war\WEB-INF\lib\ojdbc14dms.jar;C:\Temp\war\WEB-INF\lib\ojdl.jar;C:\Temp\war\WEB-INF\lib\orai18n.jar;C:\Temp\war\WEB-INF\lib\toplink-essentials-agent.jar;C:\Temp\war\WEB-INF\lib\toplink-essentials.jar" -javaagent:C:\Temp\war\WEB-INF\lib\toplink-essentials-agent.jar=main oracle.toplink.jpa.example.inventory.tools.Populator
   
   

4. 执行命令行。

第 7 步：运行应用程序

要在部署之后访问应用程序（参见第 5 步：打包与部署），请启动浏览器并输入以下 URL：

• 对于 Tomcat：

  http://<hostname>:8080/jpa-example/index.faces

  其中 <hostname> 是您部署应用程序的计算机的名称。