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/UserGuide/DBWS/Overview"

(→‎An example of an auto-generated XML Schema)
m
 
(98 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
<div style="float:right;border:1px solid #000000;padding:5px;max-width:500px;">__TOC__</div>
+
For the current version, see:
−
==EclipseLink DBWS Overview==
+
'''[http://www.eclipse.org/eclipselink/documentation/2.4/dbws/toc.htm Developing Persistence Architectures Using EclipseLink Database Web Services, Release 2.4]'''
−
<onlyinclude>
+
−
The goal of EclipseLink DBWS is to enable simple and efficient access to relational database artifacts via a Web service, extending EclipseLink's core capabilities while leveraging existing components (ORM, OXM).
+
  
−
EclipseLink DBWS has two parts: a design-time tooling component (DBWSBuilder) and a runtime provider component that takes a service descriptor (along with related deployment artifacts) and realizes it as a JAX-WS 2.0 Web service. The runtime provider uses EclipseLink to bridge between the database and the XML SOAP Messages used by Web service clients.
+
For EclispeLink DBWS Overview, see http://www.eclipse.org/eclipselink/documentation/2.4/dbws/overview.htm
  
−
An EclipseLink DBWS service may be comprised of any number of '''operations''' of which there are 4 types:
+
[[Category:DBWS]]
−
# Insert - inserts into the database persistent entities described by an XML document.
+
−
# Update - updates database persistent entities described by an XML document.
+
−
# Delete - removes from the database persistent entities described by an XML document.
+
−
# Query - retrieves from the database persistent entities described by an XML document. <br>Selection criteria for Query operations can be specified by:
+
−
#* custom <tt>SQL SELECT</tt> statement
+
−
#* Stored Procedure invocation
+
−
#* EclipseLink Named Query (that can use the complete range of EclipseLink ORM Expression Framework APIs)
+
−
 
+
−
The XML documents used by an '''operation''' conform to an XML Schema Definition (<tt>.xsd</tt> file).
+
−
 
+
−
===XML-to-Relational Mapping (XRM)===
+
−
EclipseLink's ORM and OXM features provides the basis for a powerful '''bridge''' between a database's relational structure(s) and XML's hierarchical structure.
+
−
[[Image:XRRunTime.png]]
+
−
</onlyinclude>
+
−
===Configuration===
+
−
The metadata for an EclipseLink DBWS service is contained in an easy-to-read service descriptor file <b>eclipselink-dbws.xml</b>:
+
−
* contains <b><i>name of EclipseLink DBWS service</i></b>
+
−
* contains <b><i>name of sessions.xml</i></b> - if not present, then <tt>'eclipselink-dbws-sessions.xml'</tt> will be used
+
−
* operation definitions
+
−
Example DBWS Service descriptor file
+
−
<source lang="xml">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<dbws
+
−
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+
−
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
−
  >
+
−
  <name>example</name>
+
−
  <query>
+
−
    <name>countEmployees
+
−
    <result>
+
−
      <type>xsd:int</type>
+
−
    </result>
+
−
    <sql><![CDATA[select count(*) from EMP]]></sql>
+
−
  </query>
+
−
</dbws>
+
−
</source>
+
−
The information required by the EclipseLink DBWS service descriptor file is kept to a minimum and omitted fields have simple defaults, allowing for both auto-generation by tools or manual editing.
+
−
 
+
−
===XML Schema Definition===
+
−
An EclipseLink DBWS service requires an XML Schema Definition file to specify how information returned from the database is to be shaped. The EclipseLink OXM Project handles converting information from the database to XML, giving the user access to the complete range of EclipseLink Object-to-XML mapping capabilities.
+
−
====An example of an auto-generated XML Schema====
+
−
The design-time tool derives element-tag names from Database table metadata (column names, types, nullable, etc):
+
−
{| border="1" cellpadding="5" cellspacing="1"
+
−
! 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
+
−
! 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
+
−
! 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
+
−
! 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
+
−
! 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
+
−
! 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
+
−
! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|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
+
−
|}
+
−
<source lang="xml">
+
−
<?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>
+
−
</source>
+
−
 
+
−
====Simple XML Format (SXF)====
+
−
The design-time tools will not generate an XML Schema Definition when the information returned by a <b>query operation</b> has no easy-to-predetermine structure:
+
−
* resultSet from a custom SQL <b>query operation</b>
+
−
* results from a Stored Procedure <b>query operation</b>
+
−
* updated row-count from an <b>update operation</b>
+
−
 
+
−
<source lang="xml" border="1">
+
−
<?xml version="1.0" encoding="UTF-8"?>
+
−
<xsd:schema
+
−
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+
−
  >
+
−
  <xsd:complexType name="simple-xml-format">
+
−
    <xsd:sequence>
+
−
      <xsd:any minOccurs="0"/>
+
−
    </xsd:sequence>
+
−
  </xsd:complexType>
+
−
</xsd:schema>
+
−
</source>
+
−
The EclipseLink DBWS runtime provider uses information only available at the time of query execution to build XML element-tag names; thus, these XML documents are 'dumb' as they cannot be validated against any schema - or more accurately, only the 'sequence-of-any' schema above can validate the documents.
+
−
<source lang="xml">
+
−
Element tag names are direct copies of table's column names:
+
−
<?xml version = '1.0' encoding = 'UTF-8'?>
+
−
<simple-xml-format>
+
−
  <simple-xml>
+
−
    <EMPNO>7788</EMPNO>
+
−
    <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>
+
−
    <EMPNO>7369</EMPNO>
+
−
    <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>
+
−
 
+
−
 
+
−
----
+
−
[[Category: Release 1.1]]
+
−
[[Category: DBWS]]
+

Latest revision as of 08:39, 1 November 2012

For the current version, see: Developing Persistence Architectures Using EclipseLink Database Web Services, Release 2.4

For EclispeLink DBWS Overview, see http://www.eclipse.org/eclipselink/documentation/2.4/dbws/overview.htm

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/UserGuide/DBWS/Overview&oldid=320672"

This page was last modified 08:39, 1 November 2012 by Rick Sapir. Based on work by Mike Norman and David Twelves.

Back to the top