Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide 10g (10.1.3.5.0) Part Number E13981-01 |
|
|
View PDF |
This section describes the following:
Configuring the persistence.xml With a Named Persistence Unit File
Configuring the persistence.xml File for the OC4J Default Persistence Unit
For more information, see "What is the persistence.xml File?".
Example 26-1 shows an example persistence.xml
file that contains one persistence unit.
Example 26-1 Named Persistence Unit
<persistence-unit name="OrderManagement5"> <provider>com.acme.persistence</provider> <transaction-type>RESOURCE_LOCAL</transaction-type> <mapping-file>order1.xml</mapping-file> <jar-file>order.jar</jar-file> <class>com.acme.Order</class> <properties> <property name="com.acme.persistence.sql-logging" value="on"/> </properties> </persistence-unit>
This persistence unit is named OrderManagement5
and uses EntityManager
provider com.acme.persistence
. Its <transaction-type>
specifies that this persistence unit requires only a non-JTA data source. It defines its set of persistent managed classes using all of <mapping-file>
, <jar-file>
, and <class>
elements (see "What Persistent Managed Classes Does This Persistence Unit Include?"). It sets property com.acme.persistence.sql.logging
to a value of on
using a <property>
element.
For detailed descriptions of <persistence-unit>
element attributes and subelements, see the EJB 3.0 specification.
You can specify the persistent managed classes associated with a persistence unit by using one or more of the following:
<mapping-file>
element: specifies one or more object-relational mapping XML files (orm.xml
files).
<jar-file>
element: specifies one or more JAR files that will be searched for classes.
<class>
element: specifies an explicit list of classes.
The annotated managed persistence classes contained in the root of the persistence unit.
The root of the persistence unit is the JAR file or directory, whose META-INF
directory contains the persistence.xml
file. To exclude managed persistence classes, add an <exclude-unlisted-classes
> element to the persistence unit.
Using the OC4J default persistence unit, you can acquire an entity manager without having to specify a persistence unit by name (see "Understanding OC4J Persistence Unit Defaults").
By default, to use the OC4J default persistence unit, you do not need to deploy a persistence.xml
file at all.
If you set orion-ejb-jar.xml
file attribute disable-default-persistent-unit
to true
, OC4J will expect a persistence.xml
file. In this case, you can still use the OC4J default persistence unit if you specify an empty persistence unit: configure your persistence.xml
file with an empty persistence unit using any of the following:
Empty <persistence>
element:
<persistence> </persistence>
Self-closing <persistence/>
element
Completely empty (zero length) persistence.xml
file
You may specify one persistence unit for each scope or module: for example, one for each EJB JAR.
In a Java EE application, you specify your data source in a <jta-data-source>
element as Example 26-2 shows. For more information, see "Configuring Data Sources".
In a Java SE application, you specify your data source using JDBC vendor extensions, as Example 26-3 shows. For more information, see "TopLink JPA Extensions for JDBC (Java SE)").
Alternatively, using OC4J, you can use the default data source (see "What is a Default Data Source?").
This section describes the TopLink JPA vendor extensions that you can define in a persistence unit, including the following:
You can specify these vendor extensions by using a <properties>
element in your persistence.xml
file. Example 26-2 shows how to set a TopLink JPA persistence unit extension in a persistence.xml
file for a Java EE application, and Example 26-3 shows how to do the same for a Java SE application.
Example 26-2 Configuring a Vendor Extension in the Persistence.xml File (Java EE)
<persistence-unit name="default" transaction-type="JTA"> <provider> oracle.toplink.essentials.PersistenceProvider </provider> <jta-data-source> jdbc/MyDataSource </jta-data-source> <properties> <property name="toplink.logging.level" value="INFO"/> </properties> </persistence-unit>
Example 26-3 Configuring a Vendor Extension in the Persistence.xml File (Java SE)
<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.logging.level" value="INFO"/> <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>
Alternatively, you can set a TopLink JPA persistence unit extension in the Map
of properties you pass into a call to javax.persistence.Persistence
method createEntityManagerFactory
as Example 26-4 shows. You can override extensions set in the persistence.xml
file in this way. When you set an extension in a Map
of properties, you can set the value using the public
static
final
field in the appropriate configuration class in oracle.toplink.essentials.config
, including the following:
CacheType
TargetDatabase
TargetServer
TopLinkProperties
Note:
To access these classes, ensure that the appropriate OC4J persistence JAR is in your classpath. For more information, see "TopLink Essentials JPA Persistence Provider".Example 26-4 shows how to set the value of extension toplink.cache.type.default
using the CacheType
configuration class.
Example 26-4 Configuring a Vendor Extension When Creating an EntityManagerFactory
import oracle.toplink.essentials.config.CacheType; Map properties = new HashMap(); properties.put(TopLinkProperties.CACHE_TYPE_DEFAULT, CacheType.Full); EntityManagerFactory emf = Persistence.createEntityManagerFactory("default", properties);
Table 26-1 lists the TopLink JPA extensions that you can define in a persistence.xml
file to configure JDBC driver parameters. These extensions apply only when used outside of a EJB container.
Table 26-1 TopLink JPA Extensions for JDBC (Java SE)
Table 26-2 lists the TopLink JPA extensions that you can define in a persistence.xml
file to configure the TopLink cache.
For more information, see "Understanding the Cache" in the Oracle TopLink Developer's Guide.
Table 26-2 TopLink JPA Extensions for Caching
Property | Usage | Default |
---|---|---|
|
The default type of session cache. A session cache is a shared cache that services clients attached to a given session. When you read objects from or write objects to the data source using a client session, TopLink saves a copy of the objects in the parent server session's cache and makes them accessible to child client sessions. Valid values:
Example: <property name="toplink.cache.type.default" value="Full"/> Example: property import oracle.toplink.essentials.config.CacheType; import oracle.toplink.essentials.config.TopLinkProperties; propertiesMap.put(ToplinkProperties.CACHE_TYPE_DEFAULT, CacheType.Full); |
|
|
The default maximum number of objects allowed in a TopLink cache. Valid values: Example: <property name="toplink.cache.size.default" value="5000"/> Example: property import oracle.toplink.essentials.config.TopLinkProperties; propertiesMap.put(ToplinkProperties.CACHE_SIZE_DEFAULT, 1000); |
1000 |
|
The default for whether or not the TopLink session cache is shared by multiple client sessions. Valid values:
Example: <property name="toplink.cache.shared.default" value="true"/> Example: property import oracle.toplink.essentials.config.TopLinkProperties; propertiesMap.put(ToplinkProperties.CACHE_SHARED_DEFAULT, "true"); |
|
|
The type of session cache for the JPA entity named For more information on entity names, see Valid values:
Example: <property name="toplink.cache.type.Order" value="Full"/> Example: property import oracle.toplink.essentials.config.CacheType import oracle.toplink.essentials.config.TopLinkProperties; propertiesMap.put(TopLinkProperties.CACHE_TYPE+".Order", CacheType.Full); |
|
|
The maximum number of JPA entities of the type denoted by JPA entity name For more information on entity names, see Valid values: Example: <property name="toplink.cache.size.Order" value="5000"/> Example: property import oracle.toplink.essentials.config.TopLinkProperties; propertiesMap.put(ToplinkProperties.CACHE_SIZE+".Order", 1000); |
1000 |
|
Whether or not the TopLink session cache is shared by multiple client sessions for JPA entities of the type denoted by JPA entity name For more information on entity names, see Valid values:
Example: <property name="toplink.cache.shared.Order" value="true"/> Example: property import oracle.toplink.essentials.config.TopLinkProperties; propertiesMap.put(ToplinkProperties.CACHE_SHARED+".Order", "true"); |
|
Table 26-3 lists the TopLink JPA extensions that you can define in a persistence.xml
file to configure TopLink logging.
For more information, see "Configuring Logging" in the Oracle TopLink Developer's Guide.
Table 26-3 TopLink JPA Extensions for Logging
Table 26-4 lists the TopLink JPA extensions that you can define in a persistence.xml
file to configure TopLink extensions for database, session, and application server.
Table 26-4 TopLink JPA Extensions for Database, Session, and Application Server
Table 26-5 lists the TopLink JPA extensions that you can define in a persistence.xml
file to configure TopLink customization and validation.
Table 26-5 TopLink JPA Extensions for Customization and Validation
Property | Usage | Default |
---|---|---|
|
Control whether or not the weaving of the entity classes is performed. Weaving is required in order to use lazy fetching of Valid values:
Example: <property name="toplink.weaving" value="true"/> Example: property import oracle.toplink.essentials.config.TopLinkProperties; propertiesMap.put(TopLinkProperties.WEAVING, "true"); |
|
|
Specify a TopLink session customizer class: a Java class that implements the For more information, see "Session Customization". Valid values: class name of a Example: <property name="toplink.session.customizer" value="acme.sessions.MySessionCustomizer"/> Example: property import oracle.toplink.essentials.config.TopLinkProperties; propertiesMap.put(TopLinkProperties.SESSION_CUSTOMIZER, "acme.sessions.MySessionCustomizer"); |
|
|
Specify a TopLink descriptor customizer class: a Java class that implements the For more information on entity names, see For more information on TopLink descriptors, see: Valid values: class name of a Example: <property name="toplink.descriptor.customizer.Order" value="acme.sessions.MyDescriptorCustomizer"/> Example: property import oracle.toplink.essentials.config.TopLinkProperties; propertiesMap.put(TopLinkProperties.DESCRIPTOR_CUSTOMIZER+".Order", "acme.sessions.MyDescriptorCustomizer"); |
Table 26-4 lists the TopLink JPA extensions that you can define in a persistence.xml
file to configure schema generation.
Table 26-6 TopLink JPA Extensions for Schema Generation
Property | Usage | Default |
---|---|---|
|
Specify what data definition language (DDL) generation action you want for your JPA entities. To specify the DDL generation target, see Valid values:
Example: <property name="toplink.ddl-generation" value="create-tables"/> Example: property import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider; propertiesMap.put(EntityManagerFactoryProvider.DDL_GENERATION, EntityManagerFactoryProvider.CREATE_ONLY); |
|
|
Specify where TopLink should write generated DDL files (see Valid values: a file specification to a directory in which you have write access. The file specification may be relative to your current working directory or absolute. If it does not end in a file separator, TopLink will append one valid for your operating system. Example: <property name="toplink.application-location" value="C:\ddl\"/> Example: property import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider; propertiesMap.put(EntityManagerFactoryProvider.APP_LOCATION, "C:\ddl\"); |
|
|
Specify the file name of the SQL file that TopLink generates containing SQL statements to create tables for JPA entities. This file is written to the location specified by Valid values: a file name valid for your operating system. Optionally, you may prefix the file name with a file path as long as the concatenation of Example: <property name="toplink.create-ddl-jdbc-file-name" value="create.sql"/> Example: property import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider; propertiesMap.put(EntityManagerFactoryProvider.CREATE_JDBC_DDL_FILE, "create.sql"); |
|
|
Specify the file name of the SQL file that TopLink generates containing the SQL statements to drop tables for JPA entities. This file is written to the location specified by Valid values: a file name valid for your operating system. Optionally, you may prefix the file name with a file path as long as the concatenation of Example: <property name="toplink.drop-ddl-jdbc-file-name" value="drop.sql"/> Example: property import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider; propertiesMap.put(EntityManagerFactoryProvider.DROP_JDBC_DDL_FILE, "drop.sql"); |
|
|
Use this property to specify the DDL generation target. Valid values:
Example: <property name="toplink.ddl-generation.output-mode" value="database"/> Example: property import oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider; propertiesMap.put(EntityManagerFactoryProvider.DDL_GENERATION_MODE, EntityManagerFactoryProvider.DDL_DATABASE_GENERATION); |
Java EE mode ( Java SE mode ( |