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
 
(65 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, providing Java EE-compliant client-neutral access to the database without having to write Java code. EclipseLink DBWS extends EclipseLink's core capabilities while leveraging existing ORM and OXM components.
+
  
EclipseLink DBWS has two parts: a design-time tooling component (<tt>DBWSBuilder</tt>) 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 <b>operations</b> of which there are 4 types:
+
[[Category:DBWS]]
# <b>insert</b> - inserts into the database persistent entities described by an XML document.
+
# <b>update</b> - updates database persistent entities described by an XML document.
+
# <b>delete</b> - removes from the database persistent entities described by an XML document.
+
# <b>query</b> - 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)
+
#* (future) JP-QL
+
 
+
The XML documents used by an <b>operation</b> 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]]
+
 
+
===Configuration===
+
A typical EclipseLink DBWS service is packaged in an archive (<tt>.jar</tt> or <tt>.war</tt> file) with a service descriptor file
+
<tt><b>eclipselink-dbws.xml</b></tt> in the META-INF directory (or WEB-INF/classes/META-INF when packaged in a <tt>.war</tt> file).
+
To bridge the relational database and XML worlds, an EclipseLink sessions.xml <tt><b>eclipselink-dbws-sessions.xml</b></tt> points
+
to two Eclipse projects - one for the ORM side, the other for the OXM side. The service also requires an XML Schema Definition file
+
<tt><b>eclipselink-dbws-schema.xsd</b></tt> which in conjunction with the OXM project, specifies how information from the database
+
is to be 'shaped' into XML documents.
+
 
+
<source lang="text" enclose="div">
+
root of archive
+
{not all files displayed ...}
+
  \---META-INF
+
    |  eclipselink-dbws.xml
+
    |  eclipselink-dbws-sessions.xml -- name can be overriden by <sessions-file> entry in eclipselink-dbws.xml
+
    |  eclipselink-dbws-or.xml
+
    |  eclipselink-dbws-ox.xml
+
    |  eclipselink-dbws-schema.xsd -- when deployed in a .war file, located in a different directory
+
</source>
+
The EclipseLink DBWS service descriptor file <tt><b>eclipselink-dbws.xml</b></tt> is easy to read, with minimum required information
+
and simple defaults for omitted fields, allowing for both auto-generation by tools or manual editing:
+
* <b>&lt;name&gt;</b> of EclipseLink DBWS service
+
* <b>&lt;sessions-file&gt;</b> name of sessions.xml file - if not present, then <tt><b>eclipselink-dbws-sessions.xml</b></tt> will be used
+
* <b>operation</b> definitions (see the four types mentioned above)
+
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>
+
  <sessions-file>example-dbws-sessions.xml</sessions-file>
+
  <query>
+
    <name>countEmployees
+
    <result>
+
      <type>xsd:int</type>
+
    </result>
+
    <sql><![CDATA[select count(*) from EMP]]></sql>
+
  </query>
+
</dbws>
+
</source>
+
The [[EclipseLink/UserGuide/DBWS/Overview/EclipseLink_DBWS_Service_Descriptor_File_(ELUG)|EclipseLink DBWS service descriptor file is described in full in the User Guide]].
+
 
+
===XML Schema Definition===
+
The EclipseLink DBWS service schema file <tt><b>eclipselink-dbws-schema.xsd</b></tt> can be created by hand, or auto-generated by the
+
design-time <tt>DBWSBuilder</tt> tool that derives XML element-tag names from Database metadata (column names, types, nullable, etc).
+
 
+
====Simple XML Format (SXF)====
+
The <tt>DBWSBuilder</tt> tool 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>
+
In these cases, the EclipseLink DBWS runtime provider uses information only available at the time of query execution to build the XML
+
document:
+
<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>
+
These XML documents are 'dumb' as they cannot be validated against any pre-determined schema - or more accurately, only the following
+
very <b>permissive</b> 'sequence-of-any' schema can validate such documents:
+
<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 element tags <tt><b>simple-xml-format</b></tt> and <tt><b>simple-xml</b></tt> can be customized by setting the appropriate properties
+
on an <tt><b>operation</b></tt>.
+
</onlyinclude>
+
----
+
[[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

Back to the top