Jump to: navigation, search

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

Line 38: Line 38:
 
<br />
 
<br />
 
</onlyinclude>
 
</onlyinclude>
{| border="1"
+
 
|+ <b>EclipseLink DBWS <code>.war</code> File Contents</b>
+
 
! <b>File</b> !! <b>Description</b>
+
{| border="1" cellpadding="5" cellspacing="1"
|- web.xml |- The Web application deployment file that binds the EclipseLink database Web service to Web services stack servlet.
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|<b>File</b>
|- 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.
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|<b>Description</b>
|- eclipselink-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-builder.xml File (ELUG)#eclipselink-dbws-schema.xsd|eclipselink-dbws-schema.xsd]].
+
|<code>web.xml</code>
|- eclipselink-dbws.xml |- The EclipseLink database Web services configuration file. For more information, see [[EclipseLink dbws-builder.xml File (ELUG)#eclipselink-dbws.xml File|eclipselink-dbws.xml File]].
+
|The Web application deployment file that binds the EclipseLink DBWS service to JAX-WS stack
|- 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 ORM '''Project''' file. For more information, see [[Introduction to Relational Projects (ELUG)]].
+
|<code>swaref.xsd</code>
|- eclipselink-dbws-ox.xml |- The EclipseLink OXM '''Project''' file. For more information, see [[Introduction to XML Projects (ELUG)]].
+
|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
|- eclipselink-dbws.wsdl |- Contains equivalent entries for each operation for the specified EclipseLink database Web service. Required for deployment as a Web service.
+
|-
 +
|<code>eclipselink-dbws-schema.xsd</code>
 +
|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-builder.xml File (ELUG)#eclipselink-dbws-schema.xsd|eclipselink-dbws-schema.xsd]]
 +
|-
 +
|<code>eclipselink-dbws.xml</code>
 +
|The EclipseLink database Web services configuration file. For more information, see [[EclipseLink dbws-builder.xml File (ELUG)#eclipselink-dbws.xml File|eclipselink-dbws.xml File]]
 +
|-
 +
|<code>eclipselink-dbws-sessions.xml</code>
 +
|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)]]
 +
|-
 +
|<code>eclipselink-dbws-or.xml</code>
 +
|The EclipseLink ORM '''Project''' file. For more information, see [[Introduction to Relational Projects (ELUG)]]
 +
|-
 +
|<code>eclipselink-dbws-ox.xml</code>
 +
|The EclipseLink OXM '''Project''' file. For more information, see [[Introduction to XML Projects (ELUG)]]
 +
|-
 +
|<code>eclipselink-dbws-ox.xml</code>
 +
|Contains equivalent entries for each operation for the specified EclipseLink database Web service. Required for deployment as a Web service
 +
|-
 
|}
 
|}
  

Revision as of 09:30, 2 April 2009

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

Creating Deployable 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 stub
    |
    \---wsdl
            eclipselink-dbws-schema.xsd
            eclipselink-dbws.wsdl
            swaref.xsd                      -- optional to handle 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 WebLogic 10.3 JavaEE container. An alternate deployable .jar file has been
verified to work as a JavaSE 6 'container-less' EndPoint.


File Description
web.xml The Web application deployment file that binds the EclipseLink DBWS service to JAX-WS stack
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
eclipselink-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

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 ORM Project file. For more information, see Introduction to Relational Projects (ELUG)
eclipselink-dbws-ox.xml The EclipseLink OXM Project file. For more information, see Introduction to XML Projects (ELUG)
eclipselink-dbws-ox.xml Contains equivalent entries for each operation for the specified EclipseLink database Web service. Required for deployment as a Web service

This section describes the following:

How to Create 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 Template:SELECT statements;
  • a stored procedure.

Using the DBWSBuilder utility to create 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>
    <property name="logLevel">fine</property>
    <property name="username">scott</property>
    <property name="password">tiger</property>
    <property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property>
    <property name="driver">oracle.jdbc.OracleDriver</property>
    <property name="dataSource">jdbc/DBWStestDS</property>
    <property name="platformClassname">org.eclipse.persistence.platform.database.oracle.Oracle11Platform</property>
    <property name="wsdlLocationURI">http://localhost:7001/table_test/table_test?wsdl</property>
  </properties>
  <table
    schemaPattern="%"
    tableNamePattern="dbws_crud"
  />
</dbws-builder>

For more information, see whatever.

Using the DBWSBuilder utility to create 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>
    ...
    <property name="wsdlLocationURI">http://localhost:7001/sql_test/sql_test?wsdl</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 whatever.

Using the DBWSBuilder utility to create 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> 
    ...
    <property name="wsdlLocationURI">http://localhost:7001/procedure_test/procedure_test?wsdl</property>
    </properties> 
  <procedure
    returnType="empType" 
    catalogPattern="SOME_PKG" 
    schemaPattern="SCOTT" 
    procedurePattern="GetEmployeeByEMPNO_DEPTNO"/>
  </procedure> 
</dbws-builder>

For more information, see whatever.

How to Customize 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-tage> to an "attribute"
  • intermediate - customizing the EclipseLink ORM Project
  • advance - hand-generating all required deployment artifacts

Simple EclipseLink DBWS Customization

Intermediate EclipseLink DBWS Customization

with an EclipseLink SessionCustomizer as follows:

  1. Implement a org.eclipse.persistence.config.SessionCustomizer, as the following example shows.

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

    In the 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>

    Advanced EclipseLink DBWS Customization

    You can customize an EclipseLink DBWS service by creating your own project.xml and sessions.xml files.

    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 build method.




    Copyright Statement