【转】Toplink JPA简介

最近在做一个项目，使用ejb3，持久层使用JPA，JPA 是oracle toplink实现的，之前一直使用hibernate，相关的参数配置大家也很熟悉，这里也没什么可讨论的，但是 toplink相关的配置大家应该不是非常的熟悉，我也是google了一把才有所了解的，转贴过来供大家学习。


Toplink JPA

Toplink是Oracle公司捐献给开源社区的，是最早的ORM映射框架之一，也是对JPA规范支持最好的一个框架。它遵循CDDL v1.01开源许可协议，官方主页是http://www.oracle. com/ technology/global/cn /products/ias/ toplink/index.html。
Toplink 与JPA

Toplink最新的版本是Version 2 Build 41，Oracle已经将其捐献给Eclipse社区，并且在Sun的开源应用服务器Glassfish中，被使用为默认的JPA的实现。由于它有良好的 商业背景及广泛的应用，因此对使用JPA的开发人员来说，它便是更好的实现者选择。
Toplink下载

使用浏览器打开http://www.oracle.com/technology/products/ias/toplink/jpa/download.html，进入到Toplink下载页面，如图14-6所示。

下载后找到一个JAR包文件glassfish-persistence-installer-v2-b41.jar，它是可运行的JAR包，需要使用命令行解压缩。

例如笔者将其保存在E:/down文件夹下，则命令行的命令如下所示。

java -jar glassfish-persistence-installer-v2-b41.jar

运行后，命令行页面如图14-7所示。



图14-6 Toplink下载页面 图14-7 解压缩Toplink文件

解压缩文件后，会在相应的文件目录下生成glassfish-persistence文件夹，例如这里生成的目录是E:/down/glassfish-persistence。在该文件目录下，找到如下所示的两个JAR包文件，这些就是Toplink运行所必需的类包。

— toplink-essentials.jar：Toplink的核心类包文件。

— toplink-essentials-agent.jar：Toplink运行时代理类包，支持JVM级别的AOP。
配置日志

在Toplink中有关日志配置可以有多种情况，例如日志的级别、日志的输出内容等。这些日志的配置如以下属性所示。

— 属性名：toplink.logging.logger

描述：日志的实现类名。

可选值：

— DefaultLogger（默认）：Toplink默认的日志实现类，oracle.toplink.essentials.logging. DefaultSessionLog。

— JavaLogger：使用JDK自带的java.util.logging的实现类oracle.toplink.essentials.logging. JavaLog。

— 自定义日志类的全名：如com.fengmanfei.jpa.logger.MyCustomLogger，自定义的日志类必须实现oracle.toplink.essentials.logging.SessionLog类。

示例如下：

<property name="toplink.logging.logger" value="JavaLogger"/>

<property name="toplink.logging.logger" value="com.fengmanfei.jpa.logger. MyCustomLoggerr" />

— 属性名：toplink.logging.level

描述：日志级别，这些值定义在java.util.logging.Level类中。

可选值：级别由低到高顺序依次如下所示。

— OFF：不记录任何日志。

— SEVERE：记录Toplink不能继续运行时的严重异常和登录时的异常，并且记录异常的堆栈信息。

— WARNING：记录Toplink并不是影响运行的异常没有记录到SEVERE 级别的异常，但这种方式记录的异常不包含堆栈信息。

— INFO（默认）：记录每次的登录和退出会话的信息（包括用户名）和会话连接后详细的登录信息。

— CONFIG：仅记录登录、JDBC连接和数据库信息。

— FINE：记录SQL执行的语句。

— FINER：记录的内容与WARNING 级别相同，但记录中包括异常的堆栈信息。

— FINEST ：记录所有的日志信息。

示例如下：

<property name="toplink.logging.level" value="WARNING"/>

<property name="toplink.logging.level" value=" FINE "/>

— 属性名：toplink.logging.level.<CATEGORY>

描述：配置不同日志类别的级别，日志的分类都定义在oracle.toplink.essentials.logging. SessionLog类中。

可选值：

— SQL：SQL日志。

— TRANSACTION：事务相关日志。

— EVENT：事件相关日志。

— CONNECTION：数据库会话相关日志。

— QUERY：查询数据库相关日志。

— CACHE ：缓存相关日志。

— SEQUENCING：生成sequence相关日志。

— EJB：EJB日志。

— DMS：Oracle动态监控系统（Oracle Dynamic Monitoring System ）相关日志。

— EJB_OR_METADATA ：EJB注释相关日志。

— WEAVER ：类织入（class weaver）日志。

— PROPERTIES ：开发环境属性相关日志。

示例如下：

<property name="toplink.logging.level.sql" value="WARNING"/>

— 属性名：toplink.logging.timestamp

描述：是否输出日志的时间戳。

可选值：

— true（默认）：记录时间戳。

— false：不记录时间戳。

示例如下：

<property name="toplink.logging.timestamp" value="false"/>

— 属性名：toplink.logging.thread

描述：是否输出日志线程ID。

可选值：

— true（默认）：记录线程ID。

— false：不记录线程ID。

示例如下：

<property name="toplink.logging.thread" value="false"/>

— 属性名：toplink.logging.session

描述：是否输出日志会话ID。

可选值：

— true（默认）：记录会话ID。

— false：不记录会话ID。

示例如下：

<property name="toplink.logging.session" value="false"/>

— 属性名：toplink.logging.exceptions

描述：是否在应用程序抛出异常之前记录异常日志。

可选值：

— true：记录所有的异常。

— false（默认）：不记录应用程序的异常。

示例如下：

<property name="toplink.logging.exceptions" value="true"/>
配置缓存

缓存能够提高系统的性能，系统要根据不同的需求选择最佳的优化方式。Toplink提供了各种情况下，各种缓存的设置方式，这些配置如下所示。

— 属性名：toplink.cache.type.default

描述：默认会话缓存的类型，这些值是定义在oracle.toplink.essentials.config.CacheType类中的常量。

可选值：

— Full：完全缓存实体，实体只有删除后才同时删除内存中的缓存。建议在数据量小，内存足够大时采用该种缓存类型。

— Weak：与Full类似，不过缓存采用的是弱引用（Weak Reference）的方式，当垃圾回收时，会自动回收弱引用的对象。如果使用了事务，建议采用该种缓存方式。

— HardWeak ：与Weak类似，但是对二级缓存采用强缓存（Hard Reference）。

— SoftWeak（默认）：与Weak类似，但是对二级缓存采用软缓存（Soft Reference）。当内存不足时，Toplink会自动优化回收缓存的对象，大多数情况下，建议采用该配置。

— NONE：不缓存实体，不建议采用该配置。

★ 提示 ★

有关弱引用、软引用的相关知识涉及JVM底层对象引用优化的内容，读者若想进一步了解，可以参阅java.lang.ref.SoftReference和java.lang.ref.WeakReference类相关知识。

示例如下：

<property name="toplink.cache.type.default" value="Full"/>

— 属性名：toplink.cache.size.default，

描述：默认缓存的最大容量，可以为0到Integer.MAX_VALUE之间的数值，默认为1000。

示例如下：

<property name="toplink.cache.size.default" value="5000"/>

— 属性名：toplink.cache.shared.default

描述：默认是否共享缓存。

可选值：

— true（默认）：多个会话共享缓存。

— false：每个会话分别缓存。

示例如下：

<property name="toplink.cache.shared.default" value="false"/>

— 属性名：toplink.cache.type.<ENTITY>

描述：针对特定实体设置缓存类型，其中ENTITY为@Entity标注的实体名称，类型值toplink.cache.type.default配置相同。

可选值：

— Full：同toplink.cache.type.default。

— HardWeak：同toplink.cache.type.default。

— None：同toplink.cache.type.default。

— SoftWeak（默认）：同toplink.cache.type.default。

— Weak：同toplink.cache.type.default。

示例如下：

<property name="toplink.cache.type.Customer" value="Full"/>

— 属性名：toplink.cache.size.<ENTITY>

描述：针对特定实体缓存的最大容量，可以为0到Integer.MAX_VALUE之间的数值，默认为1000。

示例如下：

<property name="toplink.cache.size.Customer " value="5000"/>

— 属性名：toplink.cache.shared.<ENTITY>

描述：指定实体是否共享缓存。

可选值：

— true（默认）：多个会话共享缓存。

— false：每个会话分别缓存。

示例如下：

<property name="toplink.cache.shared.Customer" value="false"/>
配置JDBC和数据库

在J2SE环境中，配置JDBC时可以采用如下所示的配置进行优化。

— 属性名：toplink.jdbc.bind-parameters

描述：是否使用预编译SQL和参数查询。

可选值：

— true（默认）：预编译SQL和参数查询。

— false：不使用。

示例如下：

<property name="toplink.jdbc.bind-parameters" value="false"/>

— 属性名：toplink.jdbc.driver

描述：JDBC驱动的类的全名。

示例如下：

<property name="toplink.jdbc.driver" value="oracle.jdbc.driver.OracleDriver"/>

— 属性名：toplink.jdbc.password

描述：JDBC连接的密码。

示例如下：

<property name=" toplink.jdbc.password " value="123"/>

— 属性名：toplink.jdbc.read-connections.max

描述：读取JDBC数据库时最大连接数，可以为0到Integer.MAX_VALUE之间的数值，默认为2。

示例如下：

<property name="toplink.jdbc.read-connections.max" value="3"/>

— 属性名：toplink.jdbc.read-connections.min

描述：读取JDBC数据库时最小连接数，可以为0到Integer.MAX_VALUE之间的数值，默认为2。

示例如下：

<property name="toplink.jdbc.read-connections.max" value="1"/>

— 属性名：toplink.jdbc.read-connections.shared

描述：读取数据库时，是否共享连接。

可选值：

— true：允许用户共享连接。

— false（默认）：不共享连接。

示例如下：

<property name="toplink.jdbc.read-connections.shared" value="true"/>

— 属性名：toplink.jdbc.url

描述：JDBC连接的URL。

示例如下：

<property name="toplink.jdbc.url" value="jdbc:oracle:thin:@LOCALHOST:1521:ORCL"/>

— 属性名：toplink.jdbc.user

描述：JDBC连接的用户名。

示例如下：

<property name="toplink.jdbc.user" value="root"/>

— 属性名：toplink.jdbc.write-connections.max

描述：写JDBC数据库时最大连接数，可以为0到Integer.MAX_VALUE之间的数值，默认为10。

示例如下：

<property name="toplink.jdbc.write-connections.max" value="5"/>

— 属性名：toplink.jdbc.write-connections.min

描述：写JDBC数据库时最小连接数，可以为0到Integer.MAX_VALUE之间的数值，默认为5。

示例如下：

<property name="toplink.jdbc.write-connections.max" value="2"/>

另外，如果在J2EE环境中，也可以配置数据库相关的具体配置，如下所示。

— 属性名：toplink.target-database

描述：指定JPA使用的数据库类型，这些值定义在oracle.toplink.essentials.config.Target Database枚举类型的常量中。

可选值：

Auto（默认）、Attunity、Cloudscape、Database、DB2、DB2Mainframe、DBase、Derby、

HSQL、Informix、JavaDB、MySQL4、Oracle、PointBase、PostgreSQL、SQLAnyWhere、SQLServer、Sybase和TimesTen。

示例如下：

<property name="toplink.target-database" value="Oracle"/>

— 属性名：toplink.session-name

描述：指定会话的名称，如果要在持久化上下文外访问Toplink会话需指定该名称。如果不指定，则自动生成一个唯一标识。

示例如下：

<property name="toplink.session-name" value="MySession"/>

— 属性名：toplink.target-server

描述：指定JPA运行的服务器类型，这些值定义在oracle.toplink.essentials.config.Target Server枚举类型的常量中。

可选值：

None（默认）、OC4J_10_1_3、SunAS9。

示例如下：

<property name="toplink.target-server" value="OC4J_10_1_3"/>
配置DDL

DDL是针对映射是否自动更新数据库脚本的配置，配置这些内容可以优化对DDL的支持。有关DDL的配置如下所示。

— 属性名：toplink.ddl-generation

描述：指定DDL生成方式，这些值定义在cle.toplink.essentials.ejb.cmp3.EntityManager FactoryProvider类中。

可选值：

— none（默认）：不生成DDL，不自动生成数据库。

— create-tables：只生成不存在的表，不改变原有表结构。

— drop-and-create-tables：删除原表，重新生成新表。

示例如下：

<property name="toplink.ddl-generation" value="create-tables"/>

— 属性名：toplink.application-location

描述：指定DDL生成SQL脚本的文件的目录，默认为当前的"."+File.separator。

示例如下：

property name="toplink.application-location" value="C:/ddl/"/>

— 属性名：toplink.create-ddl-jdbc-file-name

描述：指定DDL生成创建SQL脚本的文件名，默认为createDDL.jdbc。

示例如下：

<property name="toplink.create-ddl-jdbc-file-name" value="create.sql"/>

— 属性名：toplink.drop-ddl-jdbc-file-name

描述：指定DDL生成删除SQL脚本的文件名，默认为dropDDL.jdbc。

示例如下：

<property name="toplink.drop-ddl-jdbc-file-name" value="drop.sql"/>

— 属性名：toplink.ddl-generation.output-mode

描述：指定DDL的输出方式，这些值定义在cle.toplink.essentials.ejb.cmp3.EntityManager FactoryProvider类中。

可选值：

— both（在J2SE中默认）：即生成SQL文件，又在数据库中执行。

— database：仅在数据库中执行。

— sql-script（在Java EE中默认）：仅生成SQL文件。

示例如下：

<property name="toplink.ddl-generation.output-mode" value="database"/>
其他自定义配置

除了前面几节介绍的这些基本配置外，Toplink还可以配置其他的优化选项，这些配置如下所示。

— 属性名：toplink.orm.throw.exceptions

描述：当加载persistence.xml 文件中的<mapping-file>映射文件时，是否要抛出异常。

可选值：

— true（默认）：抛出异常。

— false：仅记录在日志中。

示例如下：

<property name="oracle.orm.throw.exceptions" value="false"/>

— 属性名：toplink.weaving

描述：是否加载实体使用织入，如果对@OneToOne和@ManyToOne的关系实体使用惰性加载，则必须使用织入的方式。

可选值：

— true（默认）：织入实体。

— false：不织入实体。

— static：静态织入实体，如果运行在不是Java EE 5容器中，或者JDK 不支持代理-javaagent:toplink-essentials-agent.jar方式运行时，需要设置此选项。

示例如下：

<property name="toplink.weaving" value="false"/>

— 属性名：toplink.session.customizer

描述：自定义会话的实现类的全名，这些类必须是实现oracle.toplink.essentials.tools. sessionconfiguration.SessionCustomizer接口的类。

示例如下：

<property name="toplink.session.customizer"

value="com.fengmanfei.jpa.sessions.MySessionCustomizer"/>

— 属性名：toplink.descriptor.customizer.<ENTITY>

描述：自定义实体描述的类名，这些类必须是实现oracle.toplink.essentials.tools. sessionconfiguration.DescriptorCustomizer接口的类。

示例如下：

<property name=" toplink.descriptor.customizer.Customer "

value="com.fengmanfei.jpa.sessions.MyDescriptorCustomizer"/>
配置查询优化

在本书的第9.3.6节中，曾讲述了对于不同的实现 框架，可以设置提示来优化查询。Toplink中也提供了针对查询的优化配置，这些可配置的常量都定义在oracle.toplink. essentials.config. TopLinkQueryHints 类中。

— 属性名：toplink.jdbc.bind-parameters

描述：是否使用参数查询，可设置的值都定义在oracle.toplink.essentials.config.HintValues类中。

可选值：

— true：使用参数查询。

— false：不使用参数查询。

— PersistenceUnitDefault（默认）：根据JDBC的设置决定是否使用参数查询。

示例如下：

import oracle.toplink.essentials.config.HintValues;

import oracle.toplink.essentials.config.TopLinkQueryHints;

query.setHint(TopLinkQueryHints.BIND_PARAMETERS, HintValues.TRUE);

— 属性名：toplink.pessimistic-lock

描述：是否使用悲观锁（Pessimistic Lock），可设置的值都定义在oracle.toplink.essentials. config.PessimisticLock类中。

可选值：

— NoLock（默认）：不使用悲观锁。

— Lock：相当于SELECT .... FOR UPDATE。

— LockNoWait：相当于SELECT .... FOR UPDATE NO WAIT。

示例如下：

import oracle.toplink.essentials.config.PessimisticLock;

import oracle.toplink.essentials.config.TopLinkQueryHints;

query.setHint(TopLinkQueryHints.PESSIMISTIC_LOCK, PessimisticLock.LockNoWait);

— 属性名：toplink.refresh

描述：是否更新查询结果中会话缓存中的对象，可设置的值都定义在oracle.toplink. essentials.config.HintValues类中。

可选值：

— true：更新缓存中的对象。

— false（默认）：不更新缓存中的对象。

示例如下：

import oracle.toplink.essentials.config.HintValues;

import oracle.toplink.essentials.config.TopLinkQueryHints;

query.setHint(TopLinkQueryHints.REFRESH, HintValues.TRUE);

— 属性名：toplink.refresh.cascade

描述：更新查询结果中会话缓存中的对象时，是否更新关联的对象，该toplink.refresh值只有设置为true时才有效。可设置的值都定义在oracle.toplink.essentials.config.Cascade Policy类中。

可选值：

— NoCascading：不更新关联的实体缓存。

— CascadePrivateParts：仅更新自定义的类实体描述关系中关联的实体，参阅toplink. descriptor.customizer.<ENTITY>属性配置。

— CascadeAllParts：更新所有关联的实体缓存。

— CascadeByMapping（默认）：更新通过注释方式关联的实体对象。

示例如下：

import oracle.toplink.essentials.config.CascadePolicy;

import oracle.toplink.essentials.config.TopLinkQueryHints;

query.setHint(TopLinkQueryHints.REFRESH_CASCADE, CascadePolicy.CascadePrivateParts);
加载优化

当在Java SE环境中，配置映射@OneToOne或@ManyToOne标注时，TopLink JPA会忽略“fetch”属性设置，并且默认为即时加载（FetchType.EAGER）。若想要实现惰性加载则需要通过以下两种方式配置，类似于 OpenJPA的增强器的使用。

— 使用toplink-essentials-agent.jar代理（并列样式是内容在同一个级别的情况下使用）。

— 将属性toplink.weaving配置为true。

— 在运行的命令行中添加如下代码。

-javaagent:toplink-essentials-agent.jar

— 将toplink-essentials-agent.jar类包添加在当前的类路径中。

— 使用oracle.toplink.weaving.StaticWeave对编译的类转化。

— 将toplink-essentials.jar类包添加到当前的类路径中。

— 使用StaticWeave类转化。

java oracle.toplink.weaving.StaticWeave [arguments] <source> <target>

其中“arguments”为可设置的参数，“source”为Java源代码的文件路径或JAR包，“target”为编译后的类目录或JAR包。

例如下面的代码。

java oracle.toplink.weaving.StaticWeave -classpath c:/classpath1;c:/classpath2 c:/foo-source.jar c:/foo-target.jar





最后 ，配置后台打印sql后，日志类似





2009-03-08 22:05:17 配置 [oracle.toplink.essentials.session.file:/K:/java/aom/workspace/517fan/.explodedEar/ejbJar.jar/-517fan.connection] connecting(DatabaseLogin(
platform=>MySQL4Platform
user name=> ""
connector=>JNDIConnector datasource name=>null
))
2009-03-08 22:05:17 配置 [oracle.toplink.essentials.session.file:/K:/java/aom/workspace/517fan/.explodedEar/ejbJar.jar/-517fan.connection] Connected: jdbc:mysql://localhost:3306/517fan
User: root@localhost
Database: MySQL Version: 5.1.30-community
Driver: MySQL-AB JDBC Driver Version: mysql-connector-java-5.1.6 ( Revision: ${svn.Revision} )
2009-03-08 22:05:17 配置 [oracle.toplink.essentials.session.file:/K:/java/aom/workspace/517fan/.explodedEar/ejbJar.jar/-517fan.connection] connecting(DatabaseLogin(
platform=>MySQL4Platform
user name=> ""
connector=>JNDIConnector datasource name=>jdbc/517fan
))
2009-03-08 22:05:17 配置 [oracle.toplink.essentials.session.file:/K:/java/aom/workspace/517fan/.explodedEar/ejbJar.jar/-517fan.connection] Connected: jdbc:mysql://localhost:3306/517fan
User: root@localhost
Database: MySQL Version: 5.1.30-community
Driver: MySQL-AB JDBC Driver Version: mysql-connector-java-5.1.6 ( Revision: ${svn.Revision} )