Oracle TopLink Developer's Guide
10g Release 3 (10.1.3) B13593-01 |
|
![]() Previous |
![]() Next |
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.
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:
Starting with 10g Release 3 (10.1.3), 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.
If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in the project.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 XVI, "TopLink Sessions"). Where you define a session differs depending on whether or not your application uses CMP.
This section describes:
Starting with 10g Release 3 (10.1.3), 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 "Creating Sessions".
For a CMP project, how you specify session metadata is dependent upon the J2EE application server 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 "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 2.0 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.
If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in the ejb-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.
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".
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.
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.
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 into the session) and afterLoginCustomization
(after the TopLink runtime logs into 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: cache coordination, parameterized SQL, native SQL, batch writing/batch size, byte-array/string binding, EIS login, event listeners, table qualifier, and sequencing.
For more information about session configuration, see "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".
If you are using EJB 3.0, you can use annotations to specify most of what you formerly specified in the toplink-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.