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.
Difference between revisions of "EclipseLink/UserGuide/DBWS/Overview"
m |
|||
| Line 1: | Line 1: | ||
| − | + | {{EclipseLink_UserGuide | |
| + | |info=y | ||
| + | |toc=y | ||
| + | |eclipselink=y | ||
| + | |eclipselinktype=DBWS | ||
| + | }} | ||
| + | |||
==EclipseLink DBWS Overview== | ==EclipseLink DBWS Overview== | ||
<onlyinclude> | <onlyinclude> | ||
| − | The | + | The EclipseLink DBWS provides Java EE-compliant, client-neutral access to relational database artifacts via a Web service. EclipseLink DBWS extends EclipseLink's core capabilities while leveraging its existing ORM and OXM components. |
| + | |||
| + | EclipseLink DBWS includes two parts | ||
| + | *[[EclipseLink/UserGuide/DBWS/Overview/Design time|A design-time component]] (<tt>DBWSBuilder</tt>) | ||
| + | *[[EclipseLink/UserGuide/DBWS/Overview/Runtime|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. | ||
| − | |||
| − | An EclipseLink DBWS service may | + | An EclipseLink DBWS service may include any number of the following <b>operations</b>: |
# <b>insert</b> - inserts into the database persistent entities described by an XML document. | # <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>update</b> - updates database persistent entities described by an XML document. | ||
| Line 14: | Line 23: | ||
#* Stored Procedure invocation | #* Stored Procedure invocation | ||
#* EclipseLink Named Query (that can use the complete range of EclipseLink ORM Expression Framework APIs) | #* EclipseLink Named Query (that can use the complete range of EclipseLink ORM Expression Framework APIs) | ||
| − | #* | + | #* JP-QL |
The XML documents used by an <b>operation</b> conform to an XML Schema Definition (<tt>.xsd</tt> file). | The XML documents used by an <b>operation</b> conform to an XML Schema Definition (<tt>.xsd</tt> file). | ||
| Line 45: | Line 54: | ||
* <b><sessions-file></b> name of sessions.xml file - if not present, then <tt><b>eclipselink-dbws-sessions.xml</b></tt> will be used | * <b><sessions-file></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) | * <b>operation</b> definitions (see the four types mentioned above) | ||
| + | |||
=====Example DBWS Service descriptor file===== | =====Example DBWS Service descriptor file===== | ||
<source lang="xml" enclose="div"> | <source lang="xml" enclose="div"> | ||
| Line 102: | Line 112: | ||
These XML documents are 'dumb' as they cannot be validated against any pre-determined schema - or more accurately, only the following | 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: | very <b>permissive</b> 'sequence-of-any' schema can validate such documents: | ||
| + | |||
====Simple XML Format Schema==== | ====Simple XML Format Schema==== | ||
<source lang="xml" enclose="div"> | <source lang="xml" enclose="div"> | ||
| Line 118: | Line 129: | ||
on an <tt><b>operation</b></tt>. | on an <tt><b>operation</b></tt>. | ||
</onlyinclude> | </onlyinclude> | ||
| − | + | ||
| − | + | ||
[[Category: DBWS]] | [[Category: DBWS]] | ||
Revision as of 12:41, 28 September 2011
EclipseLink DBWS
| EclipseLink | |
| Website | |
| Download | |
| Community | |
| Mailing List • Forums • IRC • mattermost | |
| Issues | |
| Open • Help Wanted • Bug Day | |
| Contribute | |
| Browse Source |
Contents
EclipseLink DBWS Overview
The EclipseLink DBWS provides Java EE-compliant, client-neutral access to relational database artifacts via a Web service. EclipseLink DBWS extends EclipseLink's core capabilities while leveraging its existing ORM and OXM components.
EclipseLink DBWS includes two parts
- A design-time component (DBWSBuilder)
- 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.
An EclipseLink DBWS service may include any number of the following operations:
- 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.
Selection criteria for Query operations can be specified by:- custom SQL SELECT statement
- Stored Procedure invocation
- EclipseLink Named Query (that can use the complete range of EclipseLink ORM Expression Framework APIs)
- JP-QL
The XML documents used by an operation conform to an XML Schema Definition (.xsd 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.
Configuration
A typical EclipseLink DBWS service is packaged in an archive (.jar or .war file) with a service descriptor file eclipselink-dbws.xml in the META-INF directory (or WEB-INF/classes/META-INF when packaged in a .war file). To bridge the relational database and XML worlds, an EclipseLink sessions.xml eclipselink-dbws-sessions.xml 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 eclipselink-dbws-schema.xsd which in conjunction with the OXM project, specifies how information from the database is to be 'shaped' into XML documents.
{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
The EclipseLink DBWS service descriptor file eclipselink-dbws.xml is easy to read, with minimum required information and simple defaults for omitted fields, allowing for both auto-generation by a utility or manual editing:
- <name> of EclipseLink DBWS service
- <sessions-file> name of sessions.xml file - if not present, then eclipselink-dbws-sessions.xml will be used
- operation definitions (see the four types mentioned above)
Example DBWS Service descriptor file
<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>
The EclipseLink DBWS service descriptor file is described in full in the User Guide.
XML Schema Definition
The EclipseLink DBWS service schema file eclipselink-dbws-schema.xsd can be created by hand, or auto-generated by the design-time DBWSBuilder utility that derives XML element-tag names from Database metadata (column names, types, nullable, etc).
Example Simple XML Format (SXF) document
The DBWSBuilder utility will not generate an XML Schema Definition when the information returned by a query operation has no pre-determined structure, such as:
- a resultSet from a custom SQL query operation
- the results from a Stored Procedure query operation
- the row-count from an update operation
In these cases, the EclipseLink DBWS runtime provider uses information only available at the time of query execution to build the XML document:
<?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>
These XML documents are 'dumb' as they cannot be validated against any pre-determined schema - or more accurately, only the following very permissive 'sequence-of-any' schema can validate such documents:
Simple XML Format Schema
<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>
The element tags simple-xml-format and simple-xml can be customized by setting the appropriate properties on an operation.