Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/DBWS/Creating EclipseLink DBWS Services (ELUG)"

Line 96: Line 96:
 
*a stored procedure.
 
*a stored procedure.
  
====Using the <tt>DBWSBuilder</tt> utility to create an EclipseLink DBWS Service from a Database Table====
+
====Creating an EclipseLink DBWS Service from a Database Table====
 
Create an EclipseLink DBWS builder XML File with a <tt>&lt;table&gt;</tt> <b>query operation</b>:
 
Create an EclipseLink DBWS builder XML File with a <tt>&lt;table&gt;</tt> <b>query operation</b>:
 
<span id="Example 9-1"></span>
 
<span id="Example 9-1"></span>
Line 114: Line 114:
 
For more information, see the basic example [[EclipseLink/Examples/DBWS/DBWSBasicTable| Creating EclipseLink DBWS Service based on Database Table]].
 
For more information, see the basic example [[EclipseLink/Examples/DBWS/DBWSBasicTable| Creating EclipseLink DBWS Service based on Database Table]].
  
====Using the <tt>DBWSBuilder</tt> utility to create an EclipseLink DBWS Service from a SQL statement====
+
====Creating an EclipseLink DBWS Service from a SQL statement====
 
Create an EclipseLink DBWS builder XML File with a <tt>&lt;sql&gt;</tt> <b>query operation</b>:
 
Create an EclipseLink DBWS builder XML File with a <tt>&lt;sql&gt;</tt> <b>query operation</b>:
 
<span id="Example 9-2"></span>
 
<span id="Example 9-2"></span>
Line 153: Line 153:
 
For more information, see the basic example [[EclipseLink/Examples/DBWS/DBWSBasicSQL|Creating EclipseLink DBWS Service based on Results Sets from custom SQL <code>SELECT</code> statements]].
 
For more information, see the basic example [[EclipseLink/Examples/DBWS/DBWSBasicSQL|Creating EclipseLink DBWS Service based on Results Sets from custom SQL <code>SELECT</code> statements]].
  
====Using the <tt>DBWSBuilder</tt> utility to create an EclipseLink DBWS Service from a Stored Procedure====
+
====Creating an EclipseLink DBWS Service from a Stored Procedure====
 
Create an EclipseLink DBWS builder XML File with a <tt>&lt;procedure&gt;</tt> <b>query operation</b>:
 
Create an EclipseLink DBWS builder XML File with a <tt>&lt;procedure&gt;</tt> <b>query operation</b>:
 
<span id="Example 9-3"></span>
 
<span id="Example 9-3"></span>
Line 173: Line 173:
 
For more information, see the basic example [[EclipseLink/Examples/DBWS/DBWSBasicStoredProcedure|Creating EclipseLink DBWS Service based on Stored Procedure]].  
 
For more information, see the basic example [[EclipseLink/Examples/DBWS/DBWSBasicStoredProcedure|Creating EclipseLink DBWS Service based on Stored Procedure]].  
  
===How to Customize an EclipseLink DBWS Service===
+
==Customizing an EclipseLink DBWS Service==
 
There are a number use-cases that require an EclipseLink DBWS Service to be customized. The use-cases can be sub-divided into
 
There are a number use-cases that require an EclipseLink DBWS Service to be customized. The use-cases can be sub-divided into
 
* simple - changing an &lt;element-tag&gt; to an "attribute"
 
* simple - changing an &lt;element-tag&gt; to an "attribute"
Line 179: Line 179:
 
* advanced - hand-generating all required deployment artifacts
 
* advanced - hand-generating all required deployment artifacts
  
====Simple EclipseLink DBWS Customization====
+
===Simple customization===
 
See the example [[EclipseLink/Examples/DBWS/DBWSIntermediateAttribute|Changing an &lt;element-tag&gt; to an "attribute"]]
 
See the example [[EclipseLink/Examples/DBWS/DBWSIntermediateAttribute|Changing an &lt;element-tag&gt; to an "attribute"]]
  
====Intermediate EclipseLink DBWS Customization====
+
===Intermediate customization===
 
The primary reason to use an EclipseLink SessionCustomizer is to enable programmatic access to the EclipseLink API. Using this API, one can retrieve the ORM or OXM descriptors from the session, and from these descriptors add, change or delete mappings. Other examples might be to  
 
The primary reason to use an EclipseLink SessionCustomizer is to enable programmatic access to the EclipseLink API. Using this API, one can retrieve the ORM or OXM descriptors from the session, and from these descriptors add, change or delete mappings. Other examples might be to  
 
turn off the session cache or change the transation isolation level of the database connection:
 
turn off the session cache or change the transation isolation level of the database connection:
Line 225: Line 225:
 
For more details, please see the [[Introduction to EclipseLink Sessions (ELUG)#Session_Customization|Session Customization section]] in the User Guide.
 
For more details, please see the [[Introduction to EclipseLink Sessions (ELUG)#Session_Customization|Session Customization section]] in the User Guide.
  
====Advanced EclipseLink DBWS Customization====
+
===Advanced customization===
 
You can customize an EclipseLink DBWS service by creating your own '''project.xml''' and '''sessions.xml''' files.  
 
You can customize an EclipseLink DBWS service by creating your own '''project.xml''' and '''sessions.xml''' files.  
 
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.xml file that references both projects.  
 
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.xml file 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. See the advanced example [[EclipseLink/Examples/DBWS/ExistingMappingFiles|Creating EclipseLink DBWS Service based upon existing ORM and OXM 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. See the advanced example [[EclipseLink/Examples/DBWS/ExistingMappingFiles|Creating EclipseLink DBWS Service based upon existing ORM and OXM Projects]].
  
=== DBWSBuilder API ===
+
==DBWSBuilder API==
 
The EclipseLink DBWS design-time utility, <tt>DBWSBuilder</tt>, is a Java application that generates EclipseLink DBWS files and assembles them into deployable archives. One can also set the <tt>DBWSBuilder</tt>’s properties, add table or procedure definitions and SQL operations programmatically through <tt>DBWSBuilder</tt>’s API.  
 
The EclipseLink DBWS design-time utility, <tt>DBWSBuilder</tt>, is a Java application that generates EclipseLink DBWS files and assembles them into deployable archives. One can also set the <tt>DBWSBuilder</tt>’s properties, add table or procedure definitions and SQL operations programmatically through <tt>DBWSBuilder</tt>’s API.  
  

Revision as of 08:45, 3 April 2009

Note: A basic overview of EclipseLink Database Web Services (DBWS) can be found here

Creating EclipseLink DBWS Services

This section describes how to automatically generate a .war file containing the EclipseLink DBWS service descriptor along with all required deployment artifacts for a JAX-WS 2.0 Web service (WSDL, XML schema, web.xml, EclipseLink ORM and OXM native Project XML files, etc.)

 root of war file
    \---web-inf
    |
    |   web.xml
    |
    +---classes
    |   +---foo                               -- optional domain classes (typically not required)
    |   |   \---bar                              
    |   |           Address.class
    |   |           Employee.class
    |   |           PhoneNumber.class
    |   |
    |   +---META-INF
    |   |       eclipselink-dbws.xml
    |   |       eclipselink-dbws-or.xml
    |   |       eclipselink-dbws-ox.xml
    |   |       eclipselink-dbws-sessions.xml -- name can be overridden by <sessions-file> entry in eclipselink-dbws.xml
    |   |
    |   \---_dbws
    |           DBWSProvider.class            -- auto-generated JAX-WS 2.0 Provider
    |
    \---wsdl
            eclipselink-dbws-schema.xsd
            eclipselink-dbws.wsdl
            swaref.xsd
EclipseLink DBWS Service .war File Contents
File Description
web.xml The Web application deployment file (required for deployment as a JAX-WS Web service)
eclipselink-dbws.xml The EclipseLink DBWS service descriptor file (described in full in the User Guide)
eclipselink-dbws-or.xml The EclipseLink ORM Project XML file. For more information, see Introduction to Relational Projects (ELUG)
eclipselink-dbws-ox.xml The EclipseLink OXM Project XML file. For more information, see Introduction to XML Projects (ELUG)
eclipselink-dbws-sessions.xml The EclipseLink sessions.xml file for the EclipseLink DBWS service. It contains references to the EclipseLink ORM and OxM Project XML files. For more information, see Introduction to EclipseLink Sessions (ELUG)
eclipselink-dbws-schema.xsd Contains XML type definitions for operation arguments and return types. The DBWSBuilder utility automatically generates this file from the database metadata to derive element-tag names and types
eclipselink-dbws.wsdl Contains entries for all operations in the EclipseLink DBWS service (required for deployment as a JAX-WS Web service)
swaref.xsd (optional) Contains XML type definitions for SOAP attachments

NB - the files swaref.xsd and web.xml have names and content determined by their roles in web deployment and cannot be changed.

The deployable .war file has been verified to work with the Oracle WebLogic Server 10.3 JavaEE container. An alternate deployable .jar file has been
verified to work as a JavaSE 6 'container-less' EndPoint.

This section describes the following:

Creating EclipseLink DBWS Services Using the DBWSBuilder utility

You can use the EclipseLink DBWS design-time tool DBWSBuilder to create deployment files. DBWSBuilder is a Java application that processes the operations described in an EclipseLink DBWS builder XML file to produce all the required deployment artifacts.

Be sure to set the following environment variables in the <ECLIPSELINK_HOME>\utils\dbws\setenv.cmd (or setenv.sh file) before invoking DBWSBuilder:

  • $JAVA_HOME
  • $DRIVER_CLASSPATH

There are script files provided for invoking DBWSBuilder. They are located in <ECLIPSELINK_HOME>\utils\dbws. The scripts are dbwsbuilder.cmd for Windows usage and dbwsbuilder.sh for other operating systems.

DBWSBuilder usage - [] indicates optional argument:
prompt > dbwsbuilder.cmd -builderFile {path_to_builder.xml} -stageDir {path_to_stageDir} -packageAs[:archive_flag] {packager} [additional args]
Available packagers:
  -packageAs:[default=archive] javase [jarFilename]
  -packageAs:[default=archive] wls [warFilename]

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

  • an existing relational database table;
  • one or more SQL SELECT statements;
  • a stored procedure.

Creating an EclipseLink DBWS Service from a Database Table

Create an EclipseLink DBWS builder XML File with a <table> query operation:

<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <properties>
    <property name="projectName">table_test</property>
    ... database properties ...
  </properties>
  <table
    schemaPattern="%"
    tableNamePattern="dbws_crud"
  />
</dbws-builder>

For more information, see the basic example Creating EclipseLink DBWS Service based on Database Table.

Creating an EclipseLink DBWS Service from a SQL statement

Create an EclipseLink DBWS builder XML File with a <sql> query operation:

<?xml version="1.0" encoding="UTF-8"?> 
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  <properties>
    <property name="projectName">sql_test</property>
    ... database properties ...
  </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>
Parameter Binding

The SQL SELECT statement for a <sql> operation may have parameters that must be bound to a datatype from the eclipselink-dbws-schema.xsd, or to any of the basic XSD datatypes. The SQL SELECT string uses JDBC-style '?' markers to indicate the position of the argument. The <sql> operation uses nested <binding> elements to match the datatype to the parameters. The order in which <binding> elements are defined must match the order of '?' markers in the SQL string:

<?xml version="1.0" encoding="UTF-8"?> 
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  <properties>
    <property name="projectName">sql_binding_test</property>
    ... database properties ...
  </properties> 
  <sql name="findEmpByName" isCollection="true" isSimpleXMLFormat="true">  
    <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> 
</dbws-builder>

The argument named "EMPNO" is bound to an integer type while the argument named "LAST_NAME" is bound to a string type.
For more information, see the basic example Creating EclipseLink DBWS Service based on Results Sets from custom SQL SELECT statements.

Creating an EclipseLink DBWS Service from a Stored Procedure

Create an EclipseLink DBWS builder XML File with a <procedure> query operation:

<?xml version="1.0" encoding="UTF-8"?> 
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  <properties> 
    <property name="projectName">procedure_test</property> 
    ... database properties ...
    </properties> 
  <procedure
    returnType="empType" 
    catalogPattern="SOME_PKG" 
    schemaPattern="SCOTT" 
    procedurePattern="GetEmployeeByEMPNO_DEPTNO"/>
  </procedure> 
</dbws-builder>

For more information, see the basic example Creating EclipseLink DBWS Service based on Stored Procedure.

Customizing an EclipseLink DBWS Service

There are a number use-cases that require an EclipseLink DBWS Service to be customized. The use-cases can be sub-divided into

  • simple - changing an <element-tag> to an "attribute"
  • intermediate - customizing the EclipseLink ORM or OXM Projects
  • advanced - hand-generating all required deployment artifacts

Simple customization

See the example Changing an <element-tag> to an "attribute"

Intermediate customization

The primary reason to use an EclipseLink SessionCustomizer is to enable programmatic access to the EclipseLink API. Using this API, one can retrieve the ORM or OXM descriptors from the session, and from these descriptors add, change or delete mappings. Other examples might be to turn off the session cache or change the transation isolation level of the database connection:

Implement a org.eclipse.persistence.config.SessionCustomizer:

package some.java.package;
 
import org.eclipse.persistence.config.SessionCustomizer; 
import org.eclipse.persistence.sessions.Session; 
import org.eclipse.persistence.sessions.DatabaseLogin; 
 
public class MySessionCustomizer implements SessionCustomizer {
 
  public MySessionCustomizer() {
  }
 
  public void customize(Sesssion session) { 
    DatabaseLogin login = (DatabaseLogin)session.getDatasourceLogin(); 
    login.setTransactionIsolation(DatabaseLogin.TRANSACTION_READ_UNCOMMITTED); 
  } 
}

In the DBWSBuilder builder XML file, specify if the customization applies to the ORM Project or the OXM Project:

<?xml version="1.0" encoding="UTF-8"?> 
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  <properties>
    <property name="projectName">customize_test</property>
     ...
    <property name="orSessionCustomizerClassName">some.java.package.MyORSessionCustomizer</property>

or

<?xml version="1.0" encoding="UTF-8"?> 
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  <properties>
    <property name="projectName">customize_test</property>
     ...
    <property name="oxSessionCustomizerClassName">some.java.package.MyOXSessionCustomizer</property>

For more details, please see the Session Customization section in the User Guide.

Advanced customization

You can customize an EclipseLink DBWS service by creating your own project.xml and sessions.xml files. 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.xml file 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. See the advanced example Creating EclipseLink DBWS Service based upon existing ORM and OXM Projects.

DBWSBuilder API

The EclipseLink DBWS design-time utility, DBWSBuilder, is a Java application that generates EclipseLink DBWS files and assembles them into deployable archives. One can also set the DBWSBuilder’s properties, add table or procedure definitions and SQL operations programmatically through DBWSBuilder’s API.

More info pending


Copyright Statement