| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
| Oracle® TopLink Developer's Guide 10g Release 3 (10.1.3.1.0) Part Number B28218-01 |
|
|
View PDF |
This chapter includes TopLink information you need when creating deployment files for the following types of applications:
For more information on packaging and deployment, see the following:
Depending on the type of application you are deploying, you may need to create any of the following deployment files:
TopLink Workbench provides the ability to create deployment files from a TopLink Workbench project (see "Exporting Project Information"). After you build a project, you have two options to create the deployment files:
Create XML deployment files that require no compiling.
Create Java source files, which you compile and deploy outside of TopLink Workbench.
Oracle recommends XML deployment because XML files are easier to deploy and troubleshoot than compiled Java files. This approach gives you a very flexible configuration that enables you to make changes safely and easily. XML deployment files do not require third-party applications or compilers to deploy successfully.
|
Note: If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in deployment descriptors. Use deployment descriptors to override annotations or specify options not supported by annotations. For more information on what annotations are currently supported, see Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide. |
The project.xml file is the core of your application. It contains the descriptors and mappings you define and also includes any named queries or finders associated with your project.
This section describes the following:
Starting with 10g Release 3 (10.1.3.1.0), the project.xml file uses an XML schema file format (XSD file) instead of the old document type definition. This defines not only the elements and attributes, but also the rules that govern how the elements and attributes are used in a valid XML file. The XSD file is formatted as standard XML and fully compliant with Oracle namespaces. Although TopLink can read both the current XSD and older DTD formats, only the current XSD format is written out.
Previously formats were defined only by the DTDs. You can now generate deployment XML files based on the following XML schemas:
object-persistence_1_0.xsd: This schema defines general persistence and mapping concepts.
toplink-object-persistence_10_1_3.xsd: This schema extends the general concepts to include additional TopLink specific data.
For more information, refer to the appropriate XSD in the <TOPLINK_HOME>\config\xsds directory. The XSD files are also available on OTN at:
For a non-CMP application, you define your project metadata in a project.xml file.
The project.xml file provides a simple and flexible way to configure, modify, and troubleshoot the project metadata. Because of these attributes, the project.xml file is the preferred way to configure a TopLink project.TopLink Workbench provides a graphical tool to build and edit the project.xml file. For information on creating projects with TopLink Workbench, see "Creating project.xml With TopLink Workbench".
For a CMP application, how you specify project metadata is dependent upon the J2EE application server you are deploying your application (see "toplink-ejb-jar.xml File").
Because you must synchronize the project.xml file with the classes and data source associated with your application, Oracle recommends that you not modify this file manually. TopLink Workbench ensures proper synchronization, and is the best way to make changes to the project. Simply modify the project in TopLink Workbench and redeploy the project.xml file. Using this option reduces development time by eliminating the need to regenerate and recompile Java code each time the project changes.
See "Exporting Project Information" for detailed information on exporting the deployment XML information.
|
Note: You can name this file with a name other thanproject.xml; however, for clarity, this discussion assumes that the file has not been renamed. |
Optionally, you can use the DeploymentXMLGenerator API to programatically generate the project.xml file in either of the following ways:
From an application, instantiate the DeploymentXMLGenerator and your java source. Call the following method:
generate (<MW_Project.mwp>, <output file.xml>)
From the command line, use:
java -classpath toplink.jar;toplinkmw.jar;xmlparserv2.jar;ejb.jar; oracle.toplink.workbench.external.api.DeploymentXMLGenerator <MW_Project.mwp> <output file.xml>
Before you use either method, ensure your the classpath includes the <ORACLE_HOME>\toplink\config directory.
|
Note: If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in theproject.xml file. To override annotations or specify options not supported by annotations, you can still provide a project.xml file in your EJB 3.0 application. For more information on what annotations are currently supported, see Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide |
Each TopLink project belongs to a TopLink session. A session is the facade through which an application accesses TopLink functionality (for more information on sessions, see Part XV, "TopLink Sessions"). Where you define a session differs depending on whether or not your application uses CMP.
This section describes the following:
Starting with 10g Release 3 (10.1.3.1.0), the sessions.xml file uses an XML schema file format (XSD file) instead of the old document type definition. In addition to gaining all the benefits of using an XSD, this change ensures that the TopLink run-time environment provides better diagnostics during sessions.xml file loading and validation.
The XSD files are also available on OTN at: http://www.oracle.com/technology/oracleas/schema/sessions_10_1_3.xsd
When you use the XSD formatted sessions.xml file, the TopLink run time separates sessions.xml file validation from session instantiation. Separating XML file formatting problems from Session Manager session instantiation problems simplifies troubleshooting. Exceptions thrown during validation clearly indicate that the failure is due to an invalid sessions.xml file as Example 8-1 illustrates.
Example 8-1 Enhanced Validation Exceptions
Exception [TOPLINK-9010] (Oracle TopLink - 10g (10.0.3)(Build 040127Dev)): oracle.toplink.exceptions.SessionLoaderException Exception Description: A End tag does not match start tag 'session'. was thrown while parsing the XML file against the XML schema. Internal Exception: oracle.xml.parser.v2.XMLParseException: End tag does not match start tag 'session'.
For a non-CMP application, you define your sessions in a sessions.xml file.
The sessions.xml file provides a simple and flexible way to configure, modify, and troubleshoot the application sessions. Because of these attributes, the sessions.xml file is the preferred way to configure a TopLink session.TopLink Workbench provides a graphical tool to build and edit the sessions.xml file. For information on creating sessions with TopLink Workbench, see Chapter 73, "Creating Sessions".
For a CMP project, how you specify session metadata is dependent upon the J2EE application server to which you are deploying your application:
For OC4J, the session configuration is done in the orion-ejb-jar.xml file. You can specify the data-source, some common session options, and a session customizer class (see "OC4J and the orion-ejb-jar.xml File"). In this case, you name the TopLink project XML file as toplink-ejb-jar.xml (see "project.xml File")
For BEA WebLogic Server, the session configuration is done in the toplink-ejb-jar.xml file. You can specify the data-source, some common session options, and a session customizer class (see "toplink-ejb-jar.xml File").
For IBM WebSphere application server, the session configuration is done in a sessions.xml file which must be named toplink-ejb-jar.xml (see Chapter 73, "Creating Sessions").
Each EJB module contains one ejb-jar.xml file that describes all the EJB in the module.
Most IDEs provide facilities to create the ejb-jar.xml file. For more information about generating this file from your IDE, see your IDE documentation.
If you build an EJB application, Oracle recommends that you use TopLink Workbench to build the ejb-jar.xml file. Because TopLink Workbench can both read and write the ejb-jar.xml file, you can use TopLink Workbench to maintain your ejb-jar.xml file in the following ways:
When you change the file manually outside of TopLink Workbench, reimport the ejb-jar.xml file into TopLink Workbench project to refresh the project.
When you change the TopLink Workbench project, TopLink Workbench updates the ejb-jar.xml file automatically when you save the project.
For more information about managing the ejb-jar.xml file in TopLink Workbench, see "Working With the ejb-jar.xml File" for more information.
|
Note: If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in theejb-jar.xml file. To override annotations or specify options not supported by annotations, you can still provide an ejb-jar.xml file in your EJB 3.0 application. For more information on what annotations are currently supported, see Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide. |
The contents of the <J2EE-Container>-ejb-jar.xml file depend on the container to which you deploy your EJB. To create this file, use the tools that accompany your container.
In most cases, the <J2EE-Container>-ejb-jar.xml file integrates with TopLink without revision. However, in some cases, you must make some TopLink-specific modifications.
|
Note: If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in the<J2EE-Container>-ejb-jar.xml file. To override annotations or specify options not supported by annotations, you can still provide a <J2EE-Container>-ejb-jar.xml file in your EJB 3.0 application. For more information on what annotations are currently supported, see Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide. |
For more information, see the following:
Table 8-1 summarizes the scenarios in which you may choose to modify the orion-ejb-jar.xml file.
Table 8-1 When to Modify the orion-ejb-jar.xml File
| CMP Type | Mapping Type | Action |
|---|---|---|
|
Orion |
Specified in |
|
|
Orion |
Default mappings |
|
|
Toplink |
Specified in |
|
|
Toplink |
Specified in |
|
|
Toplink |
Default mappings (no |
|
For more information on configuring the orion-ejb.jar.xml file, see "Configuring the orion-ejb-jar.xml File for OC4J".
For more information on configuring the weblogic-ejb-jar.xml, see "Configuring the weblogic-ejb-jar.xml File for BEA WebLogic Server".
The toplink-ejb-jar.xml file is used only in CMP projects. The TopLink runtime uses properties set in the <J2EE container>-ejb-jar.xml file (see "<J2EE-Container>-ejb-jar.xml File") to locate the toplink-ejb-jar.xml file and read it in.
|
Note: If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in thetoplink-ejb-jar.xml file. To override annotations or specify options not supported by annotations, you can still provide a toplink-ejb-jar.xml file in your EJB 3.0 application. For more information on what annotations are currently supported, see Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide |
The purpose of toplink-ejb-jar.xml file depends on the type of application server you are using:
When deploying a CMP application to OC4J, the toplink-ejb-jar.xml file is the name used for the project.xml file.
To create the toplink-ejb-jar.xml file in this case, simply rename your project.xml file. For more information, see "project.xml File".
When deploying a CMP application to BEA WebLogic Server, the toplink-ejb-jar.xml file contains a reference to the project.xml file.
Example 8-2 shows a typical BEA WebLogic Server toplink-ejb-jar.xml file:
Example 8-2 BEA WebLogic Server toplink-ejb-jar.xml File
<?xml version="1.0"?>
<!DOCTYPE toplink-ejb-jar PUBLIC "-//Oracle Corp.//DTD TopLink CMP WebLogic 10.0.3 Developer Preview//EN" "toplink-wls-ejb-jar_10_0_3.dtd">
<toplink-ejb-jar>
<session>
<name>ejb20_EmployeeDemo</name>
<project-xml>Employee.xml</project-xml>
<login>
<datasource>jdbc/JTSTopLinkDS</datasource>
<non-jts-datasource>jdbc/TopLinkDS</non-jts-datasource>
</login>
<customization-class>
oracle.toplink.demos.ejb.cmp.wls.employee.EmployeeCustomizer
</customization-class>
</session>
</toplink-ejb-jar>
For BEA WegLogic Server, you can specify an optional deployment customization class (that implements oracle.toplink.ejb.cmp.DeploymentCustomization interface) used to allow deployment customization of TopLink mapping and run-time configuration. In Example 8-2, the deployment customization class is named EmployeeCustomizer. This deployment customization class must be fully qualified by its package name and included in the deployment JAR.
At deployment time, the TopLink runtime creates a new instance of this class and invokes its methods beforeLoginCustomization (before the TopLink runtime logs in to the session) and afterLoginCustomization (after the TopLink runtime logs in to the session), passing in the TopLink session as a parameter.
Use your implementation of the beforeLoginCustomization method to configure session attributes not supported by the pm-properties, including the following:
cache coordination
parameterized SQL
native SQL
batch writing/batch size
byte-array/string binding
EIS login
event listeners
table qualifier
sequencing
In Example 8-2, notice the <non-jts-datasource> element. The usage of this element is not limited to BEA WebLogic Server toplink-ejb-jar.xml file. Any time you use cache coordination with Java Transaction API (JTA), you need to configure this element through TopLink Workbench (see "Configuring a Nontransactional Read Login"). This enables TopLink to do the out-of-context read operations and optimization of the sequencing assignments (see "Externally Managed Transactional Data Sources").
For more information about session configuration, see Chapter 74, "Configuring a Session".
When deploying a CMP application to IBM WebSphere application server, the toplink-ejb-jar.xml file is the name used for the sessions.xml file and contains a reference to the project.xml file.
To create the toplink-ejb-jar.xml file in this case, simply rename your sessions.xml file. For more information, see "sessions.xml File".
In a Java application, TopLink does not use a J2EE container for deployment. Instead, it relies on TopLink mechanisms to provide functionality and persistence. The key elements of this type of application are the lack of a J2EE container and the fact that you deploy the application by placing the application JAR file on the classpath.
Java applications require the following deployment files:
Many designers build TopLink applications that use JavaServer Pages (JSP) and Java servlets. This type of design generally supports Web-based applications.
JSP and servlet applications require the following deployment files:
Session beans generally model a process, operation, or service and as such, are not persistent. You can build TopLink applications that wrap interaction with TopLink in session beans. Session beans execute all TopLink-related operations on behalf of the client.This type of design uses JTS and externally managed transactions, but does not incur the overhead associated with CMP applications. Session bean applications also scale and deploy easily.
Session bean applications require the following deployment files:
Many applications use the persistence mechanisms a J2EE container offers. TopLink provides full support for this type of application.
You can only use one persistence manager for all the entity beans with container-managed persistence in a JAR file.
CMP applications require the following deployment files:
If you choose to write your own persistence code with BMP, you can take advantage of the classes in oracle.toplink.ejb.bmp package. Whether or not you use these classes, BMP applications require the following deployment files:
To deploy a TopLink application to OC4J 10g Release 3 (10.1.3.1.0) or later, modify the orion-ejb-jar.xml file as follows:
If you are migrating an application from a previous release of OC4J, you can use the TopLink migration tool to automatically migrate persistence information from your orion-ejb-jar.xml file to a new toplink-ejb-jar.xml. For more information, see "Migrating OC4J Orion Persistence to OC4J TopLink Persistence".
If you are using TopLink as your OC4J persistence manager, the default persistence manager in 10g Release 3 (10.1.3.1.0), you can configure the persistence-manager subentry (see Table 8-2) in the orion-ejb-jar.xml file. For more information on the scenarios in which you would want to modify orion-ejb-jar.xml, see "OC4J and the orion-ejb-jar.xml File".
If you are not using TopLink as your OC4J persistence manager, do not modify the persistence-manager subentries.
OC4J 10g Release 3 (10.1.3.1.0) and later do not support entity-deployment attribute pm-name. Use persistence-manager attribute name instead (see Table 8-2). When OC4J parses the orion-ejb.jar.xml file, if it finds a pm-name attribute, OC4J ignores its value and logs the following warning message:
|
WARNING: Use of |
Table 8-2 orion-ejb-jar.xml File persistence-manager Entries
| Entry | Description |
|---|---|
|
|
The name of the persistence manager to use. Set this value to If you set the |
|
Do not configure this attribute. If |
|
|
This property applies only when If you export your TopLink mapping metadata to a deployment XML file, set this property to the name of the deployment XML file (default: Do not set this property if you are using a TopLink project class instead of a mapping metadata file (see |
When you select TopLink as the persistence manager (see name in Table 8-2), use the persistence-manager subentries for pm-properties (see Table 8-3) to configure the TopLink session that the TopLink run time creates and uses internally for CMP projects. The persistence-manager subentries take the place of a sessions.xml file in a CMP project.
|
Note: You can only configure a subset of session features using these properties and in most cases, default configuration applies. To configure all session features and to override defaults, you must use a customization class (seecustomization-class in Table 8-3). |
Table 8-3 orion-ejb-jar.xml File persistence-manager Subentries for pm-properties
| Entry | Description |
|---|---|
|
|
Unique name for this TopLink-persisted EJB deployment JAR file. Must be unique among all TopLink-persisted deployed JAR files in this application server instance. When the TopLink run time internally creates a TopLink session for this TopLink-persisted deployed JAR file, the TopLink session manager stores the session instance under this If you do not specify a name, the TopLink runtime will generate a unique name. |
|
|
If you export your TopLink mapping metadata to a Java class (that extends Do not set this property if you are using a mapping metadata file (see |
|
Optional Java class (that implements Use your implementation of the The class must be fully qualified by its package name and included in the deployment JAR file. |
|
|
Optional TopLink database platform class (instance of Set this value to the database platform class that corresponds to the database that your application uses. The class must be fully qualified by its package name. |
|
|
Optional flag to allow relationships between remote objects. Valid values are:
|
|
When you select TopLink as the persistence manager (see name in Table 8-2), use the pm-properties subentry for cache-synchronization (see Table 8-4) to configure TopLink cache coordination features of the session that the TopLink run time uses internally for CMP projects. For more information about TopLink cache coordination, see "Understanding Cache Coordination".
When this subentry is present, you must use a customization class (see customization-class in Table 8-3) to complete cache coordination configuration. For more information about TopLink cache coordination configuration, see Chapter 88, "Configuring a Coordinated Cache".
Table 8-4 orion-ejb-jar.xml File pm-properties Subentries for cache-synchronization
| Entry | Description |
|---|---|
|
|
An indicator of whether or not cache coordination updates should be propagated to other servers synchronously or asynchronously. Valid values are as follows:
|
|
|
For a JMS coordinated cache: assuming that you are using the Oracle Application Server Containers for J2EE (OC4J) JNDI naming service and that all the hosts in your coordinated cache can communicate using OC4J proprietary RMI protocol ORMI, use a URL like: ormi://<JMS-host-IP>:<JMS-host-port> where For an RMI or CORBA coordinated cache: assuming that you are using the OC4J JNDI naming service and that all the hosts in your coordinated cache can communicate using OC4J proprietary RMI protocol ORMI on OC4J default port 23791, use a URL like: ormi://<session-host-IP>:23791 where |
|
|
Optional username required to log in to the JNDI naming service. |
When you select TopLink as the persistence manager (see name in Table 8-2), use the pm-properties subentry for default-mapping (see Table 8-5) to configure the TopLink default mapping and automatic table generation feature.
For more information about TopLink default mappings, see "Default Mapping in CMP Projects Using OC4J at Run Time".
For more information about TopLink automatic table generation, see "Automatic Database Table Creation".
Table 8-5 orion-ejb-jar.xml File pm-properties Subentries for default-mapping
| Entry | Description |
|---|---|
|
|
Optional element that determines what TopLink will do to prepare the database tables that are being mapped to. Valid values are:
If no The This setting overrides autocreate-tables and autodelete-tables configuration at the application (EAR) or system level. For more information, see "Automatic Database Table Creation". |
|
|
An element used if the generated table names are not long enough to be unique. Values are restricted to In default mapping, each entity is mapped to one table. The only exception is in many-to-many mappings where there is one extra relation table involved in the source and target entities. When However, if the same entity is defined in multiple JAR files in an application, or across multiple applications, table-naming collision is inevitable. To address this problem, set If there is no The |
To deploy a TopLink application to a BEA WebLogic Server, modify the weblogic-ejb-jar.xml file as described in:
Avoid the weblogic-ejb-jar.xml tags that TopLink either does not support or does not require (see "Unsupported weblogic-ejb-jar.xml File Tags").
If you are migrating a BEA WEbLogic Server application to OC4J, you can use the TopLink migration tool to automatically migrate persistence information from your weblogic-ejb-jar.xml file to a new toplink-ejb-jar.xml file. For more information, see "Migrating BEA WebLogic Persistence to OC4J TopLink Persistence".
Within the weblogic-ejb-jar.xml file, each bean must have a persistence-descriptor entry with subentries, as follows:
Configure the persistence-descriptor entry with subentries that indicate TopLink is available and should be used:
If you deploy to WebLogic 6.1 (Service Pack 4), include a persistence-type element and a persistence-use element. Both elements require a type-identifier and a type-version tag. Table 8-6 lists the options for the type-identifier tag, and Table 8-7 lists the options for the type-version tag.
If you deploy to WebLogic 7.0 or 8.1, include a persistence-use element with a type-identifier and a type-version tag. Table 8-6 lists the options for the type-identifier tag, and Table 8-7 lists the options for the type-version tag.
If you use WebLogic 6.1, add the element type-storage to the persistence-type element, and set it to META-INF\toplink-ejb-jar.xml.
If you use WebLogic 7.0 or 8.1, add the element type-storage to the persistence-use element, and set it to META-INF\toplink-ejb-jar.xml. Set the enable-call-by-reference element to TRUE to enable call-by-reference:
<weblogic-enterprise-bean>
<ejb-name>AccountBean</ejb-name>
...
<enable-call-by-reference>True</enable-call-by-reference>
...
</weblogic-enterprise-bean>
The weblogic-ejb-jar.xml file includes several tags that TopLink either does not support or does not require:
concurrency-strategy: This tag specifies how WebLogic manages concurrent users for a given bean. Because TopLink manages concurrent access internally, it does not require this tag.
For more information about the TopLink concurrency strategy, see "Configuring Locking Policy".
db-is-shared: Because TopLink does not make any assumptions about the exclusivity of database access, TopLink does not require this tag. TopLink addresses multiuser access issues through various locking and refreshing policies.
delay-updates-until-end-of-tx: TopLink always delays updates until the end of a transaction, and does not require this tag.
finders-load-bean: TopLink always loads the bean upon execution of the finder, and does not require this tag.
pool: TopLink does not use a pooling strategy for entity beans. This avoids object-identity problems that can occur due to pooling.
lifecycle: This element manages beans that follow a pooling strategy. Because TopLink does not use a pooling strategy, TopLink ignores this tag.
is-modified-method-name: TopLink does not require a bean developer-defined method to detect changes in the object state.
isolation-level: Because isolation level settings for the cache or database transactions are specified in the TopLink project, TopLink ignores this tag.
cache: Because you define TopLink cache properties in TopLink Workbench, this tag is unnecessary.
