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"

(→‎Configuration)
m
 
(90 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.
+
−
 
+
−
The EclipseLink DBWS service descriptor file is described in full in the User Guide [[EclipseLink/UserGuide/EclipseLink_dbws-builder.xml_File_(ELUG)|EclipseLink DBWS builder xml File]]
+
−
 
+
−
===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. All EclipseLink Object-to-XML mapping capabilities are available to describe how objects are converted to XML (and vice-versa). The design-time tool can auto-generate an XML Schema.
+
−
====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 pre-determined structure, such as:
+
−
* a resultSet from a custom SQL <b>query operation</b>
+
−
* the results from a Stored Procedure <b>query operation</b>
+
−
* the 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 gathered 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 'anything' schema above can validate such 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>
+
−
The element tags <tt><b>simple-xml-format</b></tt> and <tt><b>simple-xml</b></tt> can be customized.
+
−
 
+
−
----
+
−
[[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