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 "EclipseLink/Examples/DBWS/DBWSBasicTable"

m (EclipseLink DBWS Service based on Database Table)
 
(43 intermediate revisions by 4 users not shown)
Line 1: Line 1:
== DBWS Example: Web Service based on a table ==
+
<css>
To better understand EclipseLink DBWS, let us consider the following use-case:-
+
  .source-plsql {padding:4px;border:1px solid black; background-color: white;}
* with the appropriate JDBC driver for the desired Database platform, use the DBWSBuilder utility to create a Web service that 'out-of-the-box' exposes the C/R/U/D (Create/Read/Update/Delete) lifecycle for a table. This is supported for *any* database where the JDBC driver can reliably and accurately deliver the information describing the table via the JDBC metadata APIs , java.sql.DatabaseMetaData.
+
  .source-sql {padding:4px;border:1px solid black; background-color: white;}
 +
  .source-java5 {padding:4px;border:1px solid black; background-color: white;}
 +
  .source-xml {padding:4px;border:1px solid black; background-color: white;}
 +
  .source-text {padding:4px;border:1px solid black; background-color: white;}
 +
</css>
 +
__NOTOC__
  
For this example, the output from DBWSBuilder is used without modification.
+
== EclipseLink DBWS Service based on Database Table ==
 +
The use-case for this example is the creation of a Web service that exposes a database table's <b>CRUD</b> (<b><i><u>C</u></i>reate/<i><u>R</u></i>ead</b>(findByPK,findAll)<b>/<i><u>U</u></i>pdate/<i><u>D</u></i>elete</b>) lifecycle operations. This is supported for any table (or tables - patterns supporting '%' can be used for catalog, schema or table names) on <b>any</b> database where the JDBC driver reliably and accurately delivers the table's metadata via the JDBC metadata APIs (<code>java.sql.DatabaseMetaData</code>).
  
The DBWSBuilder program is driven by a [http://wiki.eclipse.org/EclipseLink/Development/DBWS/FunctionalSpecification#Design-time_Tool control-file] that describes the database artifact(s) under consideration.
+
This example uses the <tt>DBWSBuilder</tt> utility to generate a DBWS XML schema - it is generated using very simple rules:
It then uses JDBC metadata to build all the required deployment artifacts to create a Web Service that can be deployed on OC4J.
+
* table name ==> translate any characters not supported by XML <sup>1</sup> ==> translate to_lowercase ==> add suffix 'Type' ==> top-level complex type in <tt>.xsd</tt> file
 +
* column name ==> translate any characters not supported by XML <sup>1</sup> ==> translate to_lowercase ==> becomes &lt;element-tag&gt; name
 +
**All columns are expressed as elements
 +
**BLOB columns are automatically mapped to <tt>xsd:base64Binary</tt>
 +
**<tt>xsd:base64Binary</tt> elements can be included in-line to the XML document, or handled as binary attachments (SwaRef or MTOM style).
  
=== Web Service based on a Table ===
+
<sup>1</sup> same algorithm documented as part of the SQL/X (a.k.a. SQL/XML:2003) specification
  
Given a table or tables (patterns supporting '%' can be used for catalog, schema or table names), a Web Service is automatically generated that exposes the complete CRUD lifecycle:-
+
The <code>EMP</code> table from the Oracle <tt>scott</tt> database schema will be used for this example:
 
+
{| border="1" cellpadding="5" cellspacing="1"
Create/Retrieve(single row -> findByPK/all rows -> readAll)/Update/Delete
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|OWNER
 
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|TABLE_NAME
An XML schema is generated using two very simple rules:
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|COLUMN_NAME
* table name ==> translate any characters un-supported by XML ==> to_lowercase ==> add suffix 'Type' ==> top-level complex element type in .xsd file
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|DATA_TYPE
** same algorithm documented as part of the SQL/X (a.k.a. SQL/XML:2003) specification)
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|DATA_LENGTH
* column name ==> translate characters ==> to_lowercase ==> element tag name
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|DATA_PRECISION
** All columns expressed as XML elements; BLOB columns are automatically mapped to xsd:base64Binary and can be included in-line to the XML document, or handled as binary attachments (SwaRef-style).
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|DATA_SCALE
** XML element names can be customized using a custom org.eclipse.persistence.tools.dbws.NamingConventionTransformer.
+
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|NULLABLE
 
+
The following "Employee" table from the Scott database schema will be used for this example:
+
{{XtextTable}}
+
 
+
| OWNER || TABLE_NAME || COLUMN_NAME || DATA_TYPE || DATA_LENGTH || DATA_PRECISION || DATA_SCALE || NULLABLE  
+
 
|-
 
|-
| SCOTT || EMP || EMPNO || NUMBER || 22 || 4 || 0 || N  
+
|SCOTT
 +
|EMP
 +
|EMPNO
 +
|NUMBER
 +
|22
 +
|4
 +
|0
 +
|N
 
|-
 
|-
| SCOTT || EMP || ENAME || VARCHAR2 || 10 || (null) || (null)| | Y  
+
|SCOTT
 +
|EMP
 +
|ENAME
 +
|VARCHAR2
 +
|10
 +
|(null)
 +
|(null)
 +
|Y
 
|-
 
|-
| SCOTT || EMP || JOB || VARCHAR2 || 9 || (null) || (null) || Y  
+
|SCOTT
 +
|EMP
 +
|JOB
 +
|VARCHAR2
 +
|9
 +
|(null)
 +
|(null)
 +
|Y
 
|-
 
|-
| SCOTT || EMP || MGR || NUMBER || 22 || 4 || 0 || Y  
+
|SCOTT
 +
|EMP
 +
|MGR
 +
|NUMBER
 +
|22
 +
|4
 +
|0
 +
|Y
 
|-
 
|-
| SCOTT || EMP || HIREDATE || DATE || 7 || (null) || (null) || Y  
+
|SCOTT
 +
|EMP
 +
|HIREDATE
 +
|DATE
 +
|7
 +
|(null)
 +
|(null)
 +
|Y
 
|-
 
|-
| SCOTT || EMP || SAL || NUMBER || 22 || 7 || 2 || Y  
+
|SCOTT
 +
|EMP
 +
|SAL
 +
|NUMBER
 +
|22
 +
|7
 +
|2
 +
|Y
 
|-
 
|-
| SCOTT || EMP || COMM || NUMBER || 22 || 7 || 2 || Y  
+
|SCOTT
 +
|EMP
 +
|COMM
 +
|NUMBER
 +
|22
 +
|7
 +
|2
 +
|Y
 
|-
 
|-
| SCOTT || EMP || DEPTNO || NUMBER || 22 || 2 || 0 || Y  
+
|SCOTT
 +
|EMP
 +
|DEPTNO
 +
|NUMBER
 +
|22
 +
|2
 +
|0
 +
|Y
 
|}
 
|}
  
The DBWSBuilder tool requires a DBWS configuration file as input.
+
The DBWSBuilder utility requires a DBWS configuration file as input.
 
+
<source lang="xml" enclose="div">
Example '''dbws-builder.xml''' file
+
<?xml version="1.0" encoding="UTF-8"?>
 
+
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<div class="pre">
+
<?xml version="1.0" encoding="UTF-8"?>
+
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
 
   <properties>
 
   <properties>
     <property name="projectName">crud</property>
+
     <property name="projectName">emp</property>
     <property name="contextRoot">/basic/crud</property>
+
     ... database properties
    <property name="logLevel">off</property>
+
    <property name="username"></property>
+
    <property name="password"></property>
+
    <property name="url"></property>
+
    <property name="driver">jdbc_driver</property>
+
    <property name="dataSource">jdbc/DBWSPoolDS</property>
+
    <property name="platformClassname">Database Platform</property>
+
 
   </properties>
 
   </properties>
 
   <table
 
   <table
 
     catalogPattern="%"
 
     catalogPattern="%"
     tableNamePattern="DBWS_CRUD"
+
     tableNamePattern="EMP"
 
   />
 
   />
</dbws-builder>
+
</dbws-builder>
</div>
+
</source>
 
+
<source lang="text">
The DBWSBuilder tool is provided as part of the EcliseLink install.  It can be invoked as follows
+
prompt > dbwsbuilder.cmd -builderFile dbws-builder.xml -stageDir output_directory -packageAs wls emp.war
 
+
</source>
'''dbwsbuilder.cmd -builderFile dbws-builder.xml -stageDir output_directory -packageAs javase'''
+
  
 
where
 
where
* builderFile is the DBWS Config XML file
+
* <tt>dbws-builder.xml</tt> is the DBWS builder XML file above
* stageDir is the output directory for the generated web service artifacts
+
* <tt>output_directory</tt> is the output directory for the generated files
* packageAs allows the user to specify the platform on which the resulting web service will be deployed
+
* <tt>-packageAs</tt> specifies the platform on which the web service will be deployed
  
 +
<span id="gen_schema">
  
An .xsd file is auto-generated by DBWSBuilder, deriving element-tag names from the Database table metadata:-
+
The <onlyinclude> <tt>DBWSBuilder</tt>-generated <tt><b>eclipselink-dbws-schema.xsd</b></tt> file derives &lt;element-tag&gt; names from the Database table metadata:
<div class="pre">
+
<source lang="xml" enclose="div">
<xml version="1.0" encoding="UTF-8">
+
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema>
+
<xsd:schema
   <xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   <xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    
+
   >
 
   <xsd:complexType name="empType">
 
   <xsd:complexType name="empType">
 
     <xsd:sequence>
 
     <xsd:sequence>
Line 97: Line 148:
 
     </xsd:sequence>
 
     </xsd:sequence>
 
   </xsd:complexType>
 
   </xsd:complexType>
  <xsd:element name="emp" type="empType"/>
+
</xsd:schema>
  </xsd:schema>
+
</source>
</div>
+
</onlyinclude>
 +
</span>
  
 +
===Generated EclipseLink DBWS service descriptor===
 +
One can see the CRUD operations in the generated EclipseLink DBWS service descriptor <tt><b>eclipselink-dbws.xml</b></tt> file:
 +
<source lang="xml" enclose="div">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<dbws xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns1="urn:emp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 +
  <name>emp</name>
 +
  <sessions-file>eclipselink-dbws-sessions.xml</sessions-file>
 +
  <update>
 +
      <name>update_empType</name>
 +
      <parameter>
 +
        <name>theInstance</name>
 +
        <type>ns1:empType</type>
 +
      </parameter>
 +
  </update>
 +
  <insert>
 +
      <name>create_empType</name>
 +
      <parameter>
 +
        <name>theInstance</name>
 +
        <type>ns1:empType</type>
 +
      </parameter>
 +
  </insert>
 +
  <query>
 +
      <name>findByPrimaryKey_empType</name>
 +
      <parameter>
 +
        <name>id</name>
 +
        <type>xsd:decimal</type>
 +
      </parameter>
 +
      <result>
 +
        <type>ns1:empType</type>
 +
      </result>
 +
      <named-query>
 +
        <name>findByPrimaryKey</name>
 +
        <descriptor>empType</descriptor>
 +
      </named-query>
 +
  </query>
 +
  <delete>
 +
      <name>delete_empType</name>
 +
      <parameter>
 +
        <name>theInstance</name>
 +
        <type>ns1:empType</type>
 +
      </parameter>
 +
  </delete>
 +
  <query>
 +
      <name>findAll_empType</name>
 +
      <result isCollection="true">
 +
        <type>ns1:empType</type>
 +
      </result>
 +
      <named-query>
 +
        <name>findAll</name>
 +
        <descriptor>empType</descriptor>
 +
      </named-query>
 +
  </query>
 +
</dbws>
 +
</source>
  
 
+
===SOAP Messaging===
'''SOAP Response'''
+
The following SOAP Message invokes the <tt><b>&lt;findAll_empType&gt;</b></tt> operation for the <tt>emp</tt> DBWS service:
<div class="pre">
+
<source lang="xml" enclose="div">
  <env:Envelope
+
<?xml version="1.0" encoding="UTF-8"?>
  xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
+
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Header/>
+
 
   <env:Body>
 
   <env:Body>
     <srvc:findByPrimaryKey_empResponse
+
     <findAll_empType xmlns="urn:empService" xmlns:urn="urn:emp"/>
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+
  </env:Body>
      xmlns:ns1="urn:emp"
+
</env:Envelope>
      xmlns:srvc="urn:empService"
+
</source>
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+
returning:
 +
<source lang="xml" enclose="div">
 +
<?xml version="1.0" encoding="utf-16"?>
 +
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
 +
  <SOAP-ENV:Header />
 +
  <SOAP-ENV:Body>
 +
    <srvc:findAll_empTypeResponse xmlns="urn:emp" xmlns:srvc="urn:empService">
 
       <srvc:result>
 
       <srvc:result>
         <ns1:emp>
+
         <empType>
           <ns1:empno>7499</ns1:empno>
+
           <empno>7369</empno>
           <ns1:ename>ALLEN</ns1:ename>
+
          <ename>SMITH</ename>
           <ns1:job>SALESMAN</ns1:job>
+
          <job>CLERK</job>
           <ns1:mgr>7698</ns1:mgr>
+
          <mgr>7902</mgr>
           <ns1:hiredate>1981-02-20T00:00:00.0</ns1:hiredate>
+
          <hiredate>1980-12-17T00:00:00.0-05:00</hiredate>
           <ns1:sal>1600</ns1:sal>
+
          <sal>800</sal>
           <ns1:comm>300</ns1:comm>
+
          <deptno>20</deptno>
           <ns1:deptno>30</ns1:deptno>
+
        </empType>
         </ns1:emp>
+
        <empType>
 +
          <empno>7499</empno>
 +
           <ename>ALLEN</ename>
 +
           <job>SALESMAN</job>
 +
           <mgr>7698</mgr>
 +
           <hiredate>1981-02-20T00:00:00.0-05:00</hiredate>
 +
           <sal>1600</sal>
 +
           <comm>300</comm>
 +
           <deptno>30</deptno>
 +
         </empType>
 +
        ....
 
       </srvc:result>
 
       </srvc:result>
     </srvc:findByPrimaryKey_empResponse>
+
     </srvc:findAll_empTypeResponse>
   </env:Body>
+
   </SOAP-ENV:Body>
  </env:Envelope>
+
</SOAP-ENV:Envelope>
</div>
+
</source>
 +
 
 +
[[Category:EclipseLink/Example/DBWS]]

Latest revision as of 08:34, 7 December 2011


EclipseLink DBWS Service based on Database Table

The use-case for this example is the creation of a Web service that exposes a database table's CRUD (Create/Read(findByPK,findAll)/Update/Delete) lifecycle operations. This is supported for any table (or tables - patterns supporting '%' can be used for catalog, schema or table names) on any database where the JDBC driver reliably and accurately delivers the table's metadata via the JDBC metadata APIs (java.sql.DatabaseMetaData).

This example uses the DBWSBuilder utility to generate a DBWS XML schema - it is generated using very simple rules:

  • table name ==> translate any characters not supported by XML 1 ==> translate to_lowercase ==> add suffix 'Type' ==> top-level complex type in .xsd file
  • column name ==> translate any characters not supported by XML 1 ==> translate to_lowercase ==> becomes <element-tag> name
    • All columns are expressed as elements
    • BLOB columns are automatically mapped to xsd:base64Binary
    • xsd:base64Binary elements can be included in-line to the XML document, or handled as binary attachments (SwaRef or MTOM style).

1 same algorithm documented as part of the SQL/X (a.k.a. SQL/XML:2003) specification

The EMP table from the Oracle scott database schema will be used for this example:

OWNER TABLE_NAME COLUMN_NAME DATA_TYPE DATA_LENGTH DATA_PRECISION DATA_SCALE NULLABLE
SCOTT EMP EMPNO NUMBER 22 4 0 N
SCOTT EMP ENAME VARCHAR2 10 (null) (null) Y
SCOTT EMP JOB VARCHAR2 9 (null) (null) Y
SCOTT EMP MGR NUMBER 22 4 0 Y
SCOTT EMP HIREDATE DATE 7 (null) (null) Y
SCOTT EMP SAL NUMBER 22 7 2 Y
SCOTT EMP COMM NUMBER 22 7 2 Y
SCOTT EMP DEPTNO NUMBER 22 2 0 Y

The DBWSBuilder utility requires a DBWS configuration file as input.

<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <properties>
    <property name="projectName">emp</property>
    ... database properties
  </properties>
  <table
   catalogPattern="%"
   tableNamePattern="EMP"
 />
</dbws-builder>
prompt > dbwsbuilder.cmd -builderFile dbws-builder.xml -stageDir output_directory -packageAs wls emp.war

where

  • dbws-builder.xml is the DBWS builder XML file above
  • output_directory is the output directory for the generated files
  • -packageAs specifies the platform on which the web service will be deployed

The DBWSBuilder-generated eclipselink-dbws-schema.xsd file derives <element-tag> names from the Database table metadata:

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 >
  <xsd:complexType name="empType">
    <xsd:sequence>
      <xsd:element name="empno" type="xsd:int" xsi:nil="false"/>
      <xsd:element name="ename" type="xsd:string" xsi:nil="true"/>
      <xsd:element name="job" type="xsd:string" xsi:nil="true"/>
      <xsd:element name="mgr" type="xsd:int" minOccurs="0" xsi:nil="true"/>
      <xsd:element name="hiredate" type="xsd:dateTime" xsi:nil="true"/>
      <xsd:element name="sal" type="xsd:decimal" xsi:nil="true"/>
      <xsd:element name="comm" type="xsd:int" minOccurs="0" xsi:nil="true"/>
      <xsd:element name="deptno" type="xsd:int" xsi:nil="true"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

Generated EclipseLink DBWS service descriptor

One can see the CRUD operations in the generated EclipseLink DBWS service descriptor eclipselink-dbws.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<dbws xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns1="urn:emp" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <name>emp</name>
   <sessions-file>eclipselink-dbws-sessions.xml</sessions-file>
   <update>
      <name>update_empType</name>
      <parameter>
         <name>theInstance</name>
         <type>ns1:empType</type>
      </parameter>
   </update>
   <insert>
      <name>create_empType</name>
      <parameter>
         <name>theInstance</name>
         <type>ns1:empType</type>
      </parameter>
   </insert>
   <query>
      <name>findByPrimaryKey_empType</name>
      <parameter>
         <name>id</name>
         <type>xsd:decimal</type>
      </parameter>
      <result>
         <type>ns1:empType</type>
      </result>
      <named-query>
         <name>findByPrimaryKey</name>
         <descriptor>empType</descriptor>
      </named-query>
   </query>
   <delete>
      <name>delete_empType</name>
      <parameter>
         <name>theInstance</name>
         <type>ns1:empType</type>
      </parameter>
   </delete>
   <query>
      <name>findAll_empType</name>
      <result isCollection="true">
         <type>ns1:empType</type>
      </result>
      <named-query>
         <name>findAll</name>
         <descriptor>empType</descriptor>
      </named-query>
   </query>
</dbws>

SOAP Messaging

The following SOAP Message invokes the <findAll_empType> operation for the emp DBWS service:

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
  <env:Body>
    <findAll_empType xmlns="urn:empService" xmlns:urn="urn:emp"/>
  </env:Body>
</env:Envelope>

returning:

<?xml version="1.0" encoding="utf-16"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
  <SOAP-ENV:Header />
  <SOAP-ENV:Body>
    <srvc:findAll_empTypeResponse xmlns="urn:emp" xmlns:srvc="urn:empService">
      <srvc:result>
        <empType>
          <empno>7369</empno>
          <ename>SMITH</ename>
          <job>CLERK</job>
          <mgr>7902</mgr>
          <hiredate>1980-12-17T00:00:00.0-05:00</hiredate>
          <sal>800</sal>
          <deptno>20</deptno>
        </empType>
        <empType>
          <empno>7499</empno>
          <ename>ALLEN</ename>
          <job>SALESMAN</job>
          <mgr>7698</mgr>
          <hiredate>1981-02-20T00:00:00.0-05:00</hiredate>
          <sal>1600</sal>
          <comm>300</comm>
          <deptno>30</deptno>
        </empType>
        ....
      </srvc:result>
    </srvc:findAll_empTypeResponse>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Back to the top