Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Creating EclipseLink Files for Deployment (ELUG)"

m (What You May Need to Know About Unsupported weblogic-ejb-jar.xml File Tags)
m (dbws deployment)
Line 392: Line 392:
 
* <tt>isolation-level</tt><nowiki>: Because isolation level settings for the cache or database transactions are specified in the EclipseLink project, EclipseLink ignores this tag.</nowiki>
 
* <tt>isolation-level</tt><nowiki>: Because isolation level settings for the cache or database transactions are specified in the EclipseLink project, EclipseLink ignores this tag.</nowiki>
 
* <tt>cache</tt><nowiki>: Because you define EclipseLink cache properties in Workbench, this tag is unnecessary.</nowiki>
 
* <tt>cache</tt><nowiki>: Because you define EclipseLink cache properties in Workbench, this tag is unnecessary.</nowiki>
 +
 +
 +
 +
 +
==Creating Deployment Files for EclipseLink Database Web Services ==
 +
 +
This section describes how to automatically generate a WAR file containing the WSDL,  as well as all deployment files that an EclipseLink database Web service requires.
 +
 +
This section describes the following:
 +
*[[#How to Create Deployment Files for an EclipseLink Database Web Service Using  DBWSBuilder]]
 +
*[[#How to Customize an EclipseLink Database Web Service Using Java Through Session Customization]]
 +
*[[#How to Customize an EclipseLink Database Web Service Using project.xml and  sessions.xml]]
 +
*[[#What You May Need to Know About Creating Deployment Files for an EclipseLink Database Web Service]]
 +
*[[#Binding]]
 +
*[[#DBWSBuilder]]
 +
 +
=== How to Create Deployment Files for an EclipseLink Database Web Service Using DBWSBuilder ===
 +
You can use the EclipseLink database Web service design-time tool called DBWSBuilder to create deployment files. eclipselinkDBWSBuilder  (eclipselink.tools.dbws) is a Java application that processes the operations  described in a eclipselink-dbws-builder.xml file (see [[#eclipselink-dbws-builder.xml]]) to produce the requisite files. You invoke this tool using the following command:
 +
 +
<tt>
 +
prompt > java -cp eclipselink.jar:eclipselink-dbws.jar:eclipselink-dbws-tools.jar\eclipselink.tools.dbws.DBWSBuilder -eclipselink-dbws-builder {path_to_eclipselink_dbws_builder.xml_file} -output {path_to_output_directory}
 +
</tt>
 +
 +
Using DBWSBuilder, you can generate an EclipseLink database Web service from the
 +
following sources:
 +
*an existing relational database table;
 +
*one or more SQL statements written with respect to an existing relational database schema;
 +
*a stored procedure.
 +
 +
 +
To create deployment files for your EclipseLink database Web service, do the following:
 +
#Create the table in your relational database and ensure that the relational database  management system is online.
 +
# Execute DBWSBuilder. Optionally, specify a SessionCustomizer class name using the DBWSBuilder property orSessionCustomizerClassName (if you are customizing the EclipseLink object-relational mappings), or oxSessionCustomizerClassName (when customizing the EclipseLink XML mappings).
 +
#Package and deploy the EclipseLink database Web service.
 +
 +
 +
===== Using the eclipselink-dbws-builder.xml File to Create Deployment Files for a Eclipselink Database Web Service Using DBWSBuilder from a Database Table =====
 +
 +
'''''Using eclipselink-dbws-builder.xml File to Create an EclipseLink Database Web Service from a Table '''''
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 +
 +
 +
<properties>
 +
<property name="projectName">crud</property>
 +
<property name="logLevel">off</property>
 +
<property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property>
 +
<property name="driver">oracle.jdbc.OracleDriver</property>
 +
<property name="dataSource">jdbc/DBWSPoolDS</property>
 +
<property name="username">scott</property>
 +
<property name="password">tiger</property>
 +
<property name="platformClassname">eclipselink.platform.database.oracle.Oracle10Platform</property>
 +
</properties>
 +
 +
<table catalogPattern="%" tableNamePattern="XR_CRUD_TABLE"/>
 +
 +
</dbws-builder>
 +
</source>
 +
 +
===Using the eclipselink-dbws-builder.xml File to Create Deployment Files for an Eclipselink Database Web Service Using DBWSBuilder from SQL ===
 +
 +
<span id="Example 9–2"></span>
 +
''''' Using eclipselink-dbws-builder.xml File to Create an EclipseLink Database Web Service from SQL '''''
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 +
 +
 +
<properties>
 +
<property name="projectName">employee</property>
 +
<property name="driver">oracle.jdbc.OracleDriver</property>
 +
<property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property>
 +
<property name="username">scott</property>
 +
<property name="password">tiger</property>
 +
 +
 +
</properties>
 +
<sql name="employeeInfo" simpleXMLFormatTag="employee-info" xmlTag="aggregate-counts" >
 +
 +
<text>
 +
<![CDATA[select count(*) as "COUNT", max(SAL) as "MAX-Salary" from EMP]]>
 +
</text>
 +
</sql>
 +
</dbws-builder>
 +
 +
</source>
 +
For more information, see [[#What You May Need to Know About Builder Operations]].
 +
 +
===== Using the eclipselink-dbws-builder.xml File to Create Deployment Files for a eclipselink Database Web Service Using DBWSBuilder from a Stored Procedure =====
 +
 +
<span id="Example 9–3"></span>
 +
'''''Using eclipselink-dbws-builder.xml File to Create an EclipseLink Database Web Service from Stored Procedure '''''
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 +
 +
 +
<properties>
 +
<property name="projectName">employee</property>
 +
<property name="driver">oracle.jdbc.OracleDriver</property>
 +
<property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property>
 +
<property name="username">scott</property>
 +
<property name="password">tiger</property>
 +
 +
 +
</properties>
 +
 +
 +
<procedure returnType="empType"
 +
catalogPattern="SOME_PKG"
 +
schemaPattern="SCOTT"
 +
procedurePattern="GetEmployeeByEMPNO_DEPTNO"/>
 +
 +
 +
</procedure>
 +
</dbws-builder>
 +
</source>
 +
 +
For more information, see [[#What You May Need to Know About Builder Operations]].
 +
 +
===== How to Customize a Eclipselink Database Web Service Using Java Through Session Customization =====
 +
You can customize an EclipseLink database Web service with an EclipseLink
 +
SessionCustomizer as follows:
 +
<ol>
 +
<li>Implement a eclipselink.tools.sessionconfiguration.SessionCustomizer, as  this example shows. <br>
 +
<span id="Example 9–4"></span><br>
 +
''''' Implementing a SessionCustomizer '''''
 +
 +
<source lang="java">
 +
import eclipselink.tools.sessionconfiguration.SessionCustomizer;
 +
import eclipselink.sessions.Session;
 +
import eclipselink.sessions.DatabaseLogin;
 +
 +
 +
public class MySessionCustomizer implements SessionCustomizer {
 +
 +
 +
public void customize(Sesssion session) {
 +
DatabaseLogin login = (DatabaseLogin)session.getDatasourceLogin();
 +
login.setTransactionIsolation(DatabaseLogin.TRANSACTION_READ_UNCOMMITTED);
 +
}
 +
}
 +
</source>
 +
<br>
 +
For more information, see [[#EclipseLink Database Web Services Customization]]. </li>
 +
<li>Add the SessionCustomizerto the classpath. </li>
 +
<li>Execute DBWSBuilder using the following command: <br>
 +
<tt>
 +
prompt > java -cp eclipselink.jar:eclipselink-dbws.jar:eclipselink-dbws-tools.jar \ eclipselink.tools.dbws.DBWSBuilder -eclipselink-dbws-builder {path_to_eclipselink_dbws_builder.xml_file} -output {path_to_output_directory}
 +
</tt>
 +
<br>
 +
When executing the DBWSBuilder, specify the SessionCustomizer class name using the DBWSBuilder property orSessionCustomizerClassName (if you are customizing the EclipseLink object-relational mappings), or
 +
oxSessionCustomizerClassName (when customizing the EclipseLink XML mappings).
 +
 +
For more information, see the following: 
 +
*[[#eclipselink-dbws-builder.xml]]
 +
*[[DBWSBuilder]]
 +
*[[EclipseLink Database Web Services WAR File]]
 +
</li>
 +
<li>Package and deploy the EclipseLink database Web service. </li>
 +
</ol>
 +
 +
===== How to Customize a eclipselink Database Web Service Using project.xml and sessions.xml =====
 +
You can customize an EclipseLink database Web service by creating your own project.xmland sessions.xml files, as follows:
 +
<ol>
 +
<li>Execute DBWSBuilder using the following command: <br>
 +
<tt>
 +
prompt > java -cp eclipselink.jar:eclipselink-dbws.jar:eclipselink-dbws-tools.jar \eclipselink.tools.dbws.DBWSBuilder -eclipselink-dbws-builder {path_to_eclipselink_dbws_builder.xml_file} -output {path_to_output_directory} </tt>
 +
 +
This creates the necessary EclipseLink database Web service files and subdirectories.
 +
 +
For more information, see the following:
 +
*[[#How to Create Deployment Files for an EclipseLink Database Web Service Using DBWSBuilder]]
 +
*[[#DBWSBuilder]]
 +
*[[#eclipselink-dbws-builder.xml]]
 +
</li>
 +
<li>Manually create your project.xml files and sessions.xml file using your tool of choice:
 +
**Map your objects to your relational database in an EclipseLink relational project
 +
**Map your objects to your XML schema in an EclipseLink XMl project</li>
 +
<li>Add both projects to your session.
 +
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 +
| align="left" |
 +
'''Note''': Your custom sessions.xml file must use the same name as specified by the DBWSBuilder property sessionsFileName (see [[#Table 9–4|eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties)]]).
 +
|}
 +
 +
For more information, see the following:
 +
*[[Introduction to Projects (ELUG)]
 +
*[[Introduction to EclipseLink Sessions (ELUG)]]
 +
*[[#What You May Need to Know About Creating Deployment Files for an EclipseLink Database Web Service]]
 +
</li>
 +
<li>Replace the generated project.xml files and sessions.xml file in your EclipseLink database Web services directory hierarchy with your custom project.xml files and sessions.xml files. </li>
 +
<li>Execute DBWSBuilder. For more information, see the following:
 +
**[[#DBWSBuilder]]
 +
**[[#EclipseLink Database Web Services WAR File]]</li>
 +
<li> Package and deploy the EclipseLink database Web service. </li>
 +
</ol>
 +
 +
=== What You May Need to Know About Creating Deployment Files for an EclipseLink Database Web Service ===
 +
This figure illustrates the process for creating EclipseLink database Web service
 +
deployment files.
 +
 +
''''' Creating EclipseLink Database Web Service Deployment Files '''''
 +
 +
This illustration shows the process for creating EclipseLink database Web service deployment files. The EclipseLink database Web service design-time tool takes your XSD and database schema as input to generate from table, SQL, stored procedure, or package and create a WAR file containing an EclipseLink database Web service xr-service.xml file, an EclipseLink database Web service WSDL file, EclipseLink object-relational and XML project.xml files, and EclipseLink sessions.xml file.
 +
 +
This section describes the following:
 +
*EclipseLink Database Web Services WAR File
 +
*Unstructured Data
 +
*EclipseLink Database Web Services Customization
 +
 +
For more information, see the following:
 +
*[[Introduction to EclipseLink (ELUG)#Considering EclipseLink Database Web Service Architecture]]
 +
*[[#eclipselinlk-dbws.xml File]].
 +
 +
 +
===== EclipseLink Database Web Services WAR File =====
 +
When you generate an EclipseLink database Web service, all generated files are packaged into a WAR file, as this example shows. [[#Table 9–1]] lists the files in these WAR files.
 +
 +
<span id="Example 9–5"></span>
 +
''''' EclipseLink Database Web Services WAR File '''''
 +
 +
<tt>
 +
 +
eclipselink-dbws.war
 +
  index.html
 +
  META-INF/
 +
    MANIFEST.MF
 +
  web-inf/
 +
    oracle-webservices.xml
 +
    web.xml
 +
    classes/
 +
      META-INF/
 +
        eclipselink-dbws.xml
 +
        eclipselink-dbws-sessions.xml // override eclipselink-dbws.xml sessions-file
 +
        eclipselink-dbws-or.xml
 +
        eclipselink-dbws-ox.xml
 +
      com/ // optional domain classes
 +
        acme/
 +
          Address.class
 +
          Employee.class
 +
          PhoneNumber.class
 +
    wsdl/
 +
      eclipselink-dbws.wsdl
 +
      swaref.xsd
 +
      eclipselink-dbws-schema.xsd
 +
</tt>
 +
 +
 +
<span id="Table 9–1"></span>
 +
''''' EclipseLink Database Web Service WAR File Contents '''''
 +
 +
{| class="RuleFormalWideMax" dir="ltr" title="EclipseLink Database Web Service WAR File Contents." width="100%" border="1" frame="border" rules="all" cellpadding="3" frame="border" rules="all"
 +
|- align="left" valign="top"
 +
! id="r1c1-t2" align="left" valign="bottom" | '''File'''
 +
! id="r1c2-t2" align="left" valign="bottom" | '''Description'''
 +
|- align="left" valign="top"
 +
| align="left" |
 +
index.html
 +
|
 +
Default EclipseLink database Web service landing page. The name and content of this file is determined by its role in Web deployment and cannot be changed.
 +
Applicable to all WAR files.
 +
|-
 +
|
 +
swaref.xsd
 +
|
 +
Contains XML type definitions for attachments. The name and content of this file is determined by its role in Web deployment and cannot be changed.
 +
|-
 +
|
 +
topink-dbws-schema.xsd
 +
|
 +
Contains XML type definitions for operation arguments and return types. The EclipseLink database Web service automatically generates this file from your database table metadata and uses it to derive
 +
element-tag names and types. For more information, see [[#eclipselink-dbws-schema.xsd]].
 +
|-
 +
|
 +
MANIFEST.MF
 +
|
 +
The manifest file for the WAR file.
 +
|-
 +
|
 +
oracle-webservices.xml
 +
|
 +
The deployment descriptor that the OC4J Web services stack requires. The name and content of this file is determined by its role in Web deployment and cannot be changed.
 +
|-
 +
|
 +
web.xml
 +
|
 +
The Web application deployment file that binds the EclipseLink database Web service to an OC4J Web services stack servlet.
 +
|-
 +
|
 +
eclipselink-dbws.xml
 +
|
 +
The EclipseLink database Web services configuration file. For more information, see [[#eclipselink-dbws.xml File]].
 +
|-
 +
|
 +
eclipselink-dbws-sessions .xml
 +
|
 +
The EclipseLink sessions.xml file for this EclipseLink database Web service. It contains references to the EclipseLink relational and object-XML project.xml files. For more information, see [[Introduction to EclipseLink Sessions (ELUG)]].
 +
|-
 +
|
 +
eclipselink-dbws-or.xml
 +
|The EclipseLink relational project.xmlfile. For more information, see [[Introduction to Relational Projects (ELUG]].
 +
|-
 +
|
 +
eclipselink-dbws-ox.xml
 +
|The EclipseLink object-XML project.xml file. For more information, see [[Introduction to XML Projects (ELUG)]].
 +
|-
 +
|
 +
eclipselink-dbws.wsdl
 +
|Contains equivalent entries for each operation for the specified EclipseLink database Web service. Required for deployment as a Web service.
 +
|}
 +
 +
Before you can deploy the EclipseLink database Web service, you must package the
 +
WAR in the appropriate Java EE archive for your application, such as an EAR.
 +
 +
 +
===== Unstructured Data =====
 +
In some circumstances, an EclipseLink database Web services operation may return unstructured data rather than a persistent entity. For example:
 +
*a resultSet from a custom SQL SELECT statement;
 +
*information returned by a Stored Procedure;
 +
*scalar results such as from a Stored Function or a count of updated-rows from an update operation.
 +
 +
The OC4J Web services provider will return such unstructured data as documents that
 +
conform to the Simple XML Format (SXF) schema shown in this example.
 +
 +
<span id="Example 9-6"></span>
 +
'''''Simple XML Format XSD for Unstructured Data '''''
 +
 +
<source lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
 +
<xsd:complexType name="sxfType">
 +
<xsd:sequence>
 +
<xsd:any minOccurs="0"/>
 +
 +
 +
</xsd:sequence>
 +
 +
 +
</xsd:complexType>
 +
 +
 +
<xsd:element name="simple-xml-format" type="sxfType"/>
 +
</xsd:schema>
 +
</source>
 +
 +
The following example shows a typical unstructured data document. Note the following:
 +
*Element tag names are direct copies of table column names.
 +
*The default root-element tag name is simple-xml-format and each row uses the tag name simple-xml. You can customize these element tag names using simpleXMLFormatTagand xmlTag attributes of builder operations (see [[#Table 9–5|Common Attributes of Builder Operations]]).
 +
*Columnar data uses tag names taken either from the database schema (the actual database column name) or from the stored procedure, stored function, or trigger.
 +
 +
 +
<span id="Example 9–7"></span>
 +
 +
''''' Example Unstructured Data Document '''''
 +
<source lang="xml">
 +
 +
<simple-xml-format>
 +
<simple-xml>
 +
<ENAME>SCOTT</ENAME>
 +
<JOB>ANALYST</JOB>
 +
<MGR>7566</MGR>
 +
<HIREDATE>1987-04-19T00:00:00.000-0400</HIREDATE>
 +
<SAL>3000</SAL>
 +
<DEPTNO>20</DEPTNO>
 +
</simple-xml>
 +
<simple-xml>
 +
<ENAME>SMITH</ENAME>
 +
<JOB>CLERK</JOB>
 +
<MGR>7902</MGR>
 +
<HIREDATE>1980-12-17T00:00:00.000-0400</HIREDATE>
 +
<SAL>800</SAL>
 +
<DEPTNO>20</DEPTNO>
 +
</simple-xml>
 +
 +
 +
</simple-xml-format>
 +
</source>
 +
 +
 +
===== EclipseLink Database Web Services Customization =====
 +
To customize an EclipseLink database Web service, you can do the following:
 +
*Implement an EclipseLink SessionCustomizer class.
 +
<blockquote>
 +
A SessionCustomizer is a Java class that implements the eclipselink.tools.sessionconfiguration.SessionCustomizer interface and provides a default (zero-argument) constructor.
 +
 +
Use this class's customizemethod, which takes an eclipselink.sessions.Session, to programmatically access advanced EclipseLink session API. Using this API you can get object relational and XML descriptors and from descriptors, you can get object relational and XML mappings.
 +
 +
In this way, you can access all session, descriptor, and mapping API to customize any part of the EclipseLink runtime that the EclipseLink database Web service generates. For example, to turn off the session cache. This approach is best when you just want to customize a few details.
 +
 +
You specify the SessionCustomizerusing DBWSBuilder properties (see [[#eclipselink-dbws-builder.xml]] and [[#DBWSBuilder]]).
 +
 +
By default, the session names are defined based on the eclipselink-dbws.xml
 +
file (see [[#eclipselink-dbws.xml File]]) name attribute as follows:
 +
*relational session name: name-dbws-or-session
 +
*object-xml session name: name-dbws-ox-session
 +
</blockquote>
 +
*Manually generate project.xml files and sessions.xml file.
 +
<blockquote>
 +
Using your preferred tool you can map your objects to your relational database in an EclipseLink relational project, map your objects to your XML schema in an EclipseLink XMl project, and create an EclipseLink sessions.xmlfile that references both projects.
 +
 +
In this way, you can control all aspects of the relational and XML mapping. This
 +
approach is best when you want to customize most or all details.
 +
 +
</blockquote>
 +
 +
 +
=== Binding ===
 +
The binding nested element of the sqlbuilder operation is an EclipseLink database Web services function that you use to bind an argument in an SQL statement to an XSD data type (see [[#Table 9–8|Attributes of the sql Operation]]). You define this element in the eclipselink-dbws-build.xml file (see [[#Example 9–5|eclipselink-dbws-build.xml File]]).
 +
 +
 +
<span id="Table 9–2"></span>
 +
''''' Attributes of the binding Element '''''
 +
 +
Attribute Description Required
 +
name The name of the stored procedure, stored function, or trigger to execute. The parent
 +
builder operation specifies the database that provides the stored procedure, stored
 +
function, or trigger.
 +
Yes
 +
type The XSD data type to bind to the argument name. Yes
 +
 +
 +
This example shows a typical sql operation that specifies arguments using nested bindingelements. The order in which you define bindingelements must match the order of the arguments in your SQL statement.
 +
 +
<span id="Example 9–8"></span>
 +
''''' SQLOperation Task: With Binding Elements for Arguments '''''
 +
 +
<source lang="xml">
 +
...
 +
 +
 +
<sql name="findXREmpByName" isCollection="true" returnType="xr_empType">
 +
<text>
 +
<![CDATA[select * from EMP where EMPNO = ? and LAST_NAME = ?]]>
 +
</text>
 +
<binding name="EMPNO" type="xsd:int"/>
 +
<binding name="LAST_NAME" type="xsd:string"/>
 +
 +
 +
</sql>
 +
...
 +
</source>
 +
 +
For more information, see [[#eclipselink-dbws-builder.xml]].
 +
 +
=== DBWSBuilder ===
 +
The EclipseLink database Web service design-time tool, DBWSBuilder, is a Java application that produces EclipseLink database Web service files and assembles them into a Web Archive (WAR) file.
 +
 +
You set the DBWSBuilder’s properties (see [[#Table 9–4|eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties)]]) to define features of your EclipseLink database Web service.
 +
 +
You can also set the design-time tool’s properties, add table and procedure definitions, and SQL operations programmatically through the API. Use the eclipselink.tools.dbws.DBWSBuilder class’s methods such as setDriver, setProjectName, setURL, and so on, to set properties; the addDbTableand addDbStoredProceduremethods–to add table and procedure definitions; and the addSQLOperation method–to add SQL operations.
 +
 +
{| class="Note oac_no_warn" width="80%" border="1" frame="hsides" rules="groups" cellpadding="3" frame="hsides" rules="groups"
 +
| align="left" |
 +
'''Note''': Before adding a table or procedure definition, ensure that the definitions are supported by calling the checkTablesand checkStoredProcedures methods.
 +
|}
 +
 +
Once you set all the data and definitions, invoke the builder using its buildmethod.
 +
  
  

Revision as of 13:14, 11 March 2009

Contents

Related Topics

This section includes EclipseLink information that you need when creating deployment files for various types of applications.

For more information on packaging and deployment, see the following:


Introduction to the EclipseLink Deployment File Creation

Depending on the type of application you are deploying, you may need to create any of the following deployment files:

Workbench provides the ability to create deployment files from a Workbench project. 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 Workbench.

We recommend 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 JPA, 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.


project.xml File

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.


XSD File Format

The project.xml file XSD is persistence_1_0.xsd and it is located in the <ECLIPSELINK_HOME>\xsds directory.


POJO Applications and Project Metadata

For a POJO 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 an EclipseLink project.Workbench provides a graphical tool to build and edit the project.xml file. For information on creating projects with Workbench, see Creating the project.xml File with Workbench.


JPA Applications and Project Metadata

For a JPA application, you can express project metadata using JPA annotations, persistence.xml, orm.xml, and EclipseLink JPA annotation and persistence.xml property extensions. The EclipseLink JPA persistence provider interprets all these sources of metadata to create an in-memory EclipseLink session and project at run time.

Using EclipseLink JPA, you also have the option of specifying your metadata using EclipseLink sessions.xml and project.xml while accessing your persistent classes using JPA and an EntityManager. For more information, see What You May Need to Know About EclipseLink JPA Overriding Mechanisms.


Creating the project.xml File with Workbench

Because you must synchronize the project.xml file with the classes and data source associated with your application, we recommend that you not modify this file manually. Workbench ensures proper synchronization, and is the best way to make changes to the project. Simply modify the project in 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 than project.xml; however, for clarity, this discussion assumes that the file has not been renamed.


Creating project.xml Programatically

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 the following:
java -classpath eclipselink.jar;eclispelinkmw.jar;
org.eclipse.persistence.tools.workbench.mappings.DeploymentXMLGenerator <MW_Project.mwp> <output file.xml>

Before you use either method, ensure that your classpath includes the <ECLIPSELINK_HOME>\jlib\eclipselink.jar and <ECLIPSELINK_HOME>\utils\workbench\jlib\eclipselinkmw.jar files.


Note: 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.


sessions.xml File

Each EclipseLink project belongs to an EclipseLink session. A session is the facade through which an application accesses EclipseLink functionality (for more information on sessions, see EclipseLink Sessions).


XSD File Format

The sessions.xml file XSD is eclipse_persistence_sessions_1_0.xsd and it is located in the <ECLIPSELINK_HOME>\xsds directory as well as on the web at http://www.eclipse.org/eclipselink/xsds/eclipse_persistence_sessions_1_0.xsd.

When you use the XSD formatted sessions.xml file, the EclipseLink 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 the following illustrates.


Enhanced Validation Exceptions

Exception [ECLIPSELINK-9010] (EclipseLink): org.eclipselink.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'.


POJO Applications and Session Metadata

For a POJO 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 an EclipseLink session.EclipseLink provides graphical toosl to build and edit the sessions.xml file. For information see Creating a Session.


JPA Applications and Session Metadata

For a JPA application, you can express session metadata using JPA annotations, persistence.xml, orm.xml, and EclipseLink JPA annotation and persistence.xml property extensions. The EclipseLink JPA persistence provider interprets all these sources of metadata to create an in-memory EclipseLink session and project at run time.

Using EclipseLink JPA, you also have the option of specifying your metadata using EclipseLink sessions.xml and project.xml while accessing your persistent classes using JPA and an EntityManager. For more information, see What You May Need to Know About EclipseLink JPA Overriding Mechanisms.



Creating Deployment Files for Java Applications

In a Java application, EclipseLink does not use a Java EE container for deployment. Instead, it relies on EclipseLink mechanisms to provide functionality and persistence. The key elements of this type of application are the lack of a Java EE 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:



Creating Deployment Files for JavaServer Pages and Servlet Applications

Many designers build EclipseLink 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:



Creating Deployment Files for Session Bean Applications

Session beans generally model a process, operation, or service and as such, are not persistent. You can build EclipseLink applications that wrap interaction with EclipseLink in session beans. Session beans execute all EclipseLink-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 persistence applications. Session bean applications also scale and deploy easily.

This section describes the following:


How to Create Deployment Files for EJB 3.0 Session Bean Applications

We recommend using JPA annotations and persistence unit properties, or a special-case eclipselink.sessions-xml persistence unit property (see EclipseLink JPA Persistence Unit Properties for Database, Session, and Application Server) in your EJB 3.0 session bean application.

You may also choose to use the project.xml File and sessions.xml File.

For more information, see the following:



Creating Deployment Files for JPA Applications

See Packaging and Deploying EclipseLink JPA Applications for information on how to create deployment files for your JPA application.



Configuring the weblogic-ejb-jar.xml File for WebLogic Server

Before you deploy a EclipseLink application to Oracle WebLogic Server, you must modify the weblogic-ejb-jar.xml file.

Avoid the weblogic-ejb-jar.xml tags that EclipseLink either does not support or does not require (see What You May Need to Know About Unsupported weblogic-ejb-jar.xml File Tags).


What You May Need to Know About Unsupported weblogic-ejb-jar.xml File Tags

The weblogic-ejb-jar.xml file includes the following tags that EclipseLink either does not support or does not require:

  • concurrency-strategy: This tag specifies how Oracle WebLogic Server manages concurrent users for a given bean. Because EclipseLink manages concurrent access internally, it does not require this tag.
    For more information about the EclipseLink concurrency strategy, see Configuring Locking Policy.
  • db-is-shared: Because EclipseLink does not make any assumptions about the exclusivity of database access, EclipseLink does not require this tag. EclipseLink addresses multiuser access issues through various locking and refreshing policies.
  • delay-updates-until-end-of-tx: EclipseLink always delays updates until the end of a transaction, and does not require this tag.
  • finders-load-bean: EclipseLink always loads the bean upon execution of the finder, and does not require this tag.
  • pool: EclipseLink 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 EclipseLink does not use a pooling strategy, EclipseLink ignores this tag.
  • is-modified-method-name: EclipseLink 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 EclipseLink project, EclipseLink ignores this tag.
  • cache: Because you define EclipseLink cache properties in Workbench, this tag is unnecessary.



Creating Deployment Files for EclipseLink Database Web Services

This section describes how to automatically generate a WAR file containing the WSDL, as well as all deployment files that an EclipseLink database Web service requires.

This section describes the following:

How to Create Deployment Files for an EclipseLink Database Web Service Using DBWSBuilder

You can use the EclipseLink database Web service design-time tool called DBWSBuilder to create deployment files. eclipselinkDBWSBuilder (eclipselink.tools.dbws) is a Java application that processes the operations described in a eclipselink-dbws-builder.xml file (see #eclipselink-dbws-builder.xml) to produce the requisite files. You invoke this tool using the following command:

prompt > java -cp eclipselink.jar:eclipselink-dbws.jar:eclipselink-dbws-tools.jar\eclipselink.tools.dbws.DBWSBuilder -eclipselink-dbws-builder {path_to_eclipselink_dbws_builder.xml_file} -output {path_to_output_directory}

Using DBWSBuilder, you can generate an EclipseLink database Web service from the following sources:

  • an existing relational database table;
  • one or more SQL statements written with respect to an existing relational database schema;
  • a stored procedure.


To create deployment files for your EclipseLink database Web service, do the following:

  1. Create the table in your relational database and ensure that the relational database management system is online.
  2. Execute DBWSBuilder. Optionally, specify a SessionCustomizer class name using the DBWSBuilder property orSessionCustomizerClassName (if you are customizing the EclipseLink object-relational mappings), or oxSessionCustomizerClassName (when customizing the EclipseLink XML mappings).
  3. Package and deploy the EclipseLink database Web service.


Using the eclipselink-dbws-builder.xml File to Create Deployment Files for a Eclipselink Database Web Service Using DBWSBuilder from a Database Table

Using eclipselink-dbws-builder.xml File to Create an EclipseLink Database Web Service from a Table

<?xml version="1.0" encoding="UTF-8"?> 
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 
 
<properties> 
<property name="projectName">crud</property> 
<property name="logLevel">off</property> 
<property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property> 
<property name="driver">oracle.jdbc.OracleDriver</property> 
<property name="dataSource">jdbc/DBWSPoolDS</property> 
<property name="username">scott</property> 
<property name="password">tiger</property> 
<property name="platformClassname">eclipselink.platform.database.oracle.Oracle10Platform</property> 
</properties> 
 
<table catalogPattern="%" tableNamePattern="XR_CRUD_TABLE"/> 
 
</dbws-builder>

Using the eclipselink-dbws-builder.xml File to Create Deployment Files for an Eclipselink Database Web Service Using DBWSBuilder from SQL

Using eclipselink-dbws-builder.xml File to Create an EclipseLink Database Web Service from SQL

<?xml version="1.0" encoding="UTF-8"?> 
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 
 
<properties> 
<property name="projectName">employee</property> 
<property name="driver">oracle.jdbc.OracleDriver</property> 
<property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property> 
<property name="username">scott</property> 
<property name="password">tiger</property> 
 
 
</properties> 
<sql name="employeeInfo" simpleXMLFormatTag="employee-info" xmlTag="aggregate-counts" > 
 
<text> 
<![CDATA[select count(*) as "COUNT", max(SAL) as "MAX-Salary" from EMP]]> 
</text> 
</sql> 
</dbws-builder>

For more information, see #What You May Need to Know About Builder Operations.

Using the eclipselink-dbws-builder.xml File to Create Deployment Files for a eclipselink Database Web Service Using DBWSBuilder from a Stored Procedure

Using eclipselink-dbws-builder.xml File to Create an EclipseLink Database Web Service from Stored Procedure

<?xml version="1.0" encoding="UTF-8"?> 
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
 
 
<properties> 
<property name="projectName">employee</property> 
<property name="driver">oracle.jdbc.OracleDriver</property> 
<property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property> 
<property name="username">scott</property> 
<property name="password">tiger</property> 
 
 
</properties> 
 
 
<procedure returnType="empType" 
catalogPattern="SOME_PKG" 
schemaPattern="SCOTT" 
procedurePattern="GetEmployeeByEMPNO_DEPTNO"/> 
 
 
</procedure> 
</dbws-builder>

For more information, see #What You May Need to Know About Builder Operations.

How to Customize a Eclipselink Database Web Service Using Java Through Session Customization

You can customize an EclipseLink database Web service with an EclipseLink SessionCustomizer as follows:

  1. Implement a eclipselink.tools.sessionconfiguration.SessionCustomizer, as this example shows.

    Implementing a SessionCustomizer
    import eclipselink.tools.sessionconfiguration.SessionCustomizer; 
    import eclipselink.sessions.Session; 
    import eclipselink.sessions.DatabaseLogin; 
     
     
    public class MySessionCustomizer implements SessionCustomizer { 
     
     
    public void customize(Sesssion session) { 
    DatabaseLogin login = (DatabaseLogin)session.getDatasourceLogin(); 
    login.setTransactionIsolation(DatabaseLogin.TRANSACTION_READ_UNCOMMITTED); 
    } 
    }


    For more information, see #EclipseLink Database Web Services Customization.
  2. Add the SessionCustomizerto the classpath.
  3. Execute DBWSBuilder using the following command:
    prompt > java -cp eclipselink.jar:eclipselink-dbws.jar:eclipselink-dbws-tools.jar \ eclipselink.tools.dbws.DBWSBuilder -eclipselink-dbws-builder {path_to_eclipselink_dbws_builder.xml_file} -output {path_to_output_directory}
    When executing the DBWSBuilder, specify the SessionCustomizer class name using the DBWSBuilder property orSessionCustomizerClassName (if you are customizing the EclipseLink object-relational mappings), or oxSessionCustomizerClassName (when customizing the EclipseLink XML mappings). For more information, see the following:
  4. Package and deploy the EclipseLink database Web service.
How to Customize a eclipselink Database Web Service Using project.xml and sessions.xml

You can customize an EclipseLink database Web service by creating your own project.xmland sessions.xml files, as follows:

  1. Execute DBWSBuilder using the following command:
    prompt > java -cp eclipselink.jar:eclipselink-dbws.jar:eclipselink-dbws-tools.jar \eclipselink.tools.dbws.DBWSBuilder -eclipselink-dbws-builder {path_to_eclipselink_dbws_builder.xml_file} -output {path_to_output_directory} This creates the necessary EclipseLink database Web service files and subdirectories. For more information, see the following:
  2. Manually create your project.xml files and sessions.xml file using your tool of choice:
      • Map your objects to your relational database in an EclipseLink relational project
      • Map your objects to your XML schema in an EclipseLink XMl project
  3. Add both projects to your session.

    Note: Your custom sessions.xml file must use the same name as specified by the DBWSBuilder property sessionsFileName (see eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties)).

    For more information, see the following:

  4. Replace the generated project.xml files and sessions.xml file in your EclipseLink database Web services directory hierarchy with your custom project.xml files and sessions.xml files.
  5. Execute DBWSBuilder. For more information, see the following:
  6. Package and deploy the EclipseLink database Web service.

What You May Need to Know About Creating Deployment Files for an EclipseLink Database Web Service

This figure illustrates the process for creating EclipseLink database Web service deployment files.

Creating EclipseLink Database Web Service Deployment Files

This illustration shows the process for creating EclipseLink database Web service deployment files. The EclipseLink database Web service design-time tool takes your XSD and database schema as input to generate from table, SQL, stored procedure, or package and create a WAR file containing an EclipseLink database Web service xr-service.xml file, an EclipseLink database Web service WSDL file, EclipseLink object-relational and XML project.xml files, and EclipseLink sessions.xml file.

This section describes the following:

  • EclipseLink Database Web Services WAR File
  • Unstructured Data
  • EclipseLink Database Web Services Customization

For more information, see the following:


EclipseLink Database Web Services WAR File

When you generate an EclipseLink database Web service, all generated files are packaged into a WAR file, as this example shows. #Table 9–1 lists the files in these WAR files.

EclipseLink Database Web Services WAR File

eclipselink-dbws.war 
 index.html 
 META-INF/ 
   MANIFEST.MF 
 web-inf/
   oracle-webservices.xml 
   web.xml 
   classes/ 
     META-INF/ 
       eclipselink-dbws.xml 
       eclipselink-dbws-sessions.xml // override eclipselink-dbws.xml sessions-file 
       eclipselink-dbws-or.xml 
       eclipselink-dbws-ox.xml 
     com/ // optional domain classes 
       acme/ 
         Address.class 
         Employee.class 
         PhoneNumber.class 
   wsdl/ 
     eclipselink-dbws.wsdl 
     swaref.xsd 
     eclipselink-dbws-schema.xsd 


EclipseLink Database Web Service WAR File Contents

File Description

index.html

Default EclipseLink database Web service landing page. The name and content of this file is determined by its role in Web deployment and cannot be changed. Applicable to all WAR files.

swaref.xsd

Contains XML type definitions for attachments. The name and content of this file is determined by its role in Web deployment and cannot be changed.

topink-dbws-schema.xsd

Contains XML type definitions for operation arguments and return types. The EclipseLink database Web service automatically generates this file from your database table metadata and uses it to derive element-tag names and types. For more information, see #eclipselink-dbws-schema.xsd.

MANIFEST.MF

The manifest file for the WAR file.

oracle-webservices.xml

The deployment descriptor that the OC4J Web services stack requires. The name and content of this file is determined by its role in Web deployment and cannot be changed.

web.xml

The Web application deployment file that binds the EclipseLink database Web service to an OC4J Web services stack servlet.

eclipselink-dbws.xml

The EclipseLink database Web services configuration file. For more information, see #eclipselink-dbws.xml File.

eclipselink-dbws-sessions .xml

The EclipseLink sessions.xml file for this EclipseLink database Web service. It contains references to the EclipseLink relational and object-XML project.xml files. For more information, see Introduction to EclipseLink Sessions (ELUG).

eclipselink-dbws-or.xml

The EclipseLink relational project.xmlfile. For more information, see Introduction to Relational Projects (ELUG.

eclipselink-dbws-ox.xml

The EclipseLink object-XML project.xml file. For more information, see Introduction to XML Projects (ELUG).

eclipselink-dbws.wsdl

Contains equivalent entries for each operation for the specified EclipseLink database Web service. Required for deployment as a Web service.

Before you can deploy the EclipseLink database Web service, you must package the WAR in the appropriate Java EE archive for your application, such as an EAR.


Unstructured Data

In some circumstances, an EclipseLink database Web services operation may return unstructured data rather than a persistent entity. For example:

  • a resultSet from a custom SQL SELECT statement;
  • information returned by a Stored Procedure;
  • scalar results such as from a Stored Function or a count of updated-rows from an update operation.

The OC4J Web services provider will return such unstructured data as documents that conform to the Simple XML Format (SXF) schema shown in this example.

Simple XML Format XSD for Unstructured Data

<?xml version="1.0" encoding="UTF-8"?> 
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 
<xsd:complexType name="sxfType"> 
<xsd:sequence> 
<xsd:any minOccurs="0"/> 
 
 
</xsd:sequence> 
 
 
</xsd:complexType> 
 
 
<xsd:element name="simple-xml-format" type="sxfType"/> 
</xsd:schema>

The following example shows a typical unstructured data document. Note the following:

  • Element tag names are direct copies of table column names.
  • The default root-element tag name is simple-xml-format and each row uses the tag name simple-xml. You can customize these element tag names using simpleXMLFormatTagand xmlTag attributes of builder operations (see Common Attributes of Builder Operations).
  • Columnar data uses tag names taken either from the database schema (the actual database column name) or from the stored procedure, stored function, or trigger.


Example Unstructured Data Document

<simple-xml-format> 
<simple-xml> 
<ENAME>SCOTT</ENAME> 
<JOB>ANALYST</JOB> 
<MGR>7566</MGR> 
<HIREDATE>1987-04-19T00:00:00.000-0400</HIREDATE> 
<SAL>3000</SAL> 
<DEPTNO>20</DEPTNO> 
</simple-xml> 
<simple-xml> 
<ENAME>SMITH</ENAME> 
<JOB>CLERK</JOB> 
<MGR>7902</MGR> 
<HIREDATE>1980-12-17T00:00:00.000-0400</HIREDATE> 
<SAL>800</SAL> 
<DEPTNO>20</DEPTNO> 
</simple-xml> 
 
 
</simple-xml-format>


EclipseLink Database Web Services Customization

To customize an EclipseLink database Web service, you can do the following:

  • Implement an EclipseLink SessionCustomizer class.

A SessionCustomizer is a Java class that implements the eclipselink.tools.sessionconfiguration.SessionCustomizer interface and provides a default (zero-argument) constructor.

Use this class's customizemethod, which takes an eclipselink.sessions.Session, to programmatically access advanced EclipseLink session API. Using this API you can get object relational and XML descriptors and from descriptors, you can get object relational and XML mappings.

In this way, you can access all session, descriptor, and mapping API to customize any part of the EclipseLink runtime that the EclipseLink database Web service generates. For example, to turn off the session cache. This approach is best when you just want to customize a few details.

You specify the SessionCustomizerusing DBWSBuilder properties (see #eclipselink-dbws-builder.xml and #DBWSBuilder).

By default, the session names are defined based on the eclipselink-dbws.xml file (see #eclipselink-dbws.xml File) name attribute as follows:

  • relational session name: name-dbws-or-session
  • object-xml session name: name-dbws-ox-session
  • Manually generate project.xml files and sessions.xml file.

Using your preferred tool you can map your objects to your relational database in an EclipseLink relational project, map your objects to your XML schema in an EclipseLink XMl project, and create an EclipseLink sessions.xmlfile that references both projects.

In this way, you can control all aspects of the relational and XML mapping. This approach is best when you want to customize most or all details.


Binding

The binding nested element of the sqlbuilder operation is an EclipseLink database Web services function that you use to bind an argument in an SQL statement to an XSD data type (see Attributes of the sql Operation). You define this element in the eclipselink-dbws-build.xml file (see eclipselink-dbws-build.xml File).


Attributes of the binding Element

Attribute Description Required name The name of the stored procedure, stored function, or trigger to execute. The parent builder operation specifies the database that provides the stored procedure, stored function, or trigger. Yes type The XSD data type to bind to the argument name. Yes


This example shows a typical sql operation that specifies arguments using nested bindingelements. The order in which you define bindingelements must match the order of the arguments in your SQL statement.

SQLOperation Task: With Binding Elements for Arguments

... 
 
 
<sql name="findXREmpByName" isCollection="true" returnType="xr_empType"> 
<text> 
<![CDATA[select * from EMP where EMPNO = ? and LAST_NAME = ?]]> 
</text> 
<binding name="EMPNO" type="xsd:int"/> 
<binding name="LAST_NAME" type="xsd:string"/> 
 
 
</sql> 
...

For more information, see #eclipselink-dbws-builder.xml.

DBWSBuilder

The EclipseLink database Web service design-time tool, DBWSBuilder, is a Java application that produces EclipseLink database Web service files and assembles them into a Web Archive (WAR) file.

You set the DBWSBuilder’s properties (see eclipselink-dbws-builder.xml File Elements (DBWSBuilder Properties)) to define features of your EclipseLink database Web service.

You can also set the design-time tool’s properties, add table and procedure definitions, and SQL operations programmatically through the API. Use the eclipselink.tools.dbws.DBWSBuilder class’s methods such as setDriver, setProjectName, setURL, and so on, to set properties; the addDbTableand addDbStoredProceduremethods–to add table and procedure definitions; and the addSQLOperation method–to add SQL operations.

Note: Before adding a table or procedure definition, ensure that the definitions are supported by calling the checkTablesand checkStoredProcedures methods.

Once you set all the data and definitions, invoke the builder using its buildmethod.




Copyright Statement

Back to the top