Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "EclipseLink/UserGuide/DBWS/Overview"
Line 13: | Line 13: | ||
== EclipseLink DBWS Overview == | == EclipseLink DBWS Overview == | ||
− | |||
<onlyinclude> | <onlyinclude> | ||
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 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. | ||
Line 20: | Line 19: | ||
*[[EclipseLink/UserGuide/DBWS/Overview/Design time|A design-time component]] (<tt>DBWSBuilder</tt>) | *[[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. | *[[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 include any number of the following <b>operations</b>: | An EclipseLink DBWS service may include any number of the following <b>operations</b>: | ||
Line 30: | Line 28: | ||
#* 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) | ||
− | |||
− | |||
===XML-to-Relational Mapping (XRM)=== | ===XML-to-Relational Mapping (XRM)=== | ||
Line 40: | Line 36: | ||
A typical EclipseLink DBWS service is packaged in an archive (<tt>.jar</tt> or <tt>.war</tt> file) with a service descriptor file in the META-INF directory (or WEB-INF/classes/META-INF when packaged in a <tt>.war</tt> file). | A typical EclipseLink DBWS service is packaged in an archive (<tt>.jar</tt> or <tt>.war</tt> file) with a service descriptor file 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 file points | To bridge the relational database and XML worlds, an EclipseLink sessions.xml file 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 which in conjunction with the OXM project, specifies how information from the database is to be 'shaped' into XML. | + | 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>.xsd</tt>) which in conjunction with the OXM project, specifies how information from the database is to be 'shaped' into XML. |
− | + | ||
root of archive {not all files displayed ...} | 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 | |
− | + | ||
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 a utility or manual editing. The [[EclipseLink/UserGuide/DBWS/Overview/EclipseLink_DBWS_Service_Descriptor_File_(ELUG)| service descriptor file is described in full in the User Guide]]. | 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 a utility or manual editing. The [[EclipseLink/UserGuide/DBWS/Overview/EclipseLink_DBWS_Service_Descriptor_File_(ELUG)| service descriptor file is described in full in the User Guide]]. | ||
=====Example DBWS Service descriptor file===== | =====Example DBWS Service descriptor file===== | ||
Line 65: | Line 59: | ||
</query> | </query> | ||
</source> | </source> | ||
− | |||
===XML Schema Definition=== | ===XML Schema Definition=== | ||
The EclipseLink DBWS service schema file (<tt><b>eclipselink-dbws-schema.xsd</b></tt>) can be created by hand, | The EclipseLink DBWS service schema file (<tt><b>eclipselink-dbws-schema.xsd</b></tt>) can be created by hand, |
Revision as of 12:16, 7 December 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
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)
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 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 file 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 (.xsd) which in conjunction with the OXM project, specifies how information from the database is to be 'shaped' into XML.
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
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. The service descriptor file is described in full in the User Guide.
Example DBWS Service descriptor file
<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>
</name>
</query>
XML Schema Definition
The EclipseLink DBWS service schema file (eclipselink-dbws-schema.xsd) can be created by hand, or auto-generated by the DBWSBuilder utility which derives XML element-tag names from Database metadata (column names, types, nullable, etc).
Simple XML Format (SXF)
The DBWSBuilder utility will not generate a schema file when the information returned by a query operation has no pre-determined structure, such as a resultSet from a custom SQL query, the results from a Stored Procedure or 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 (element tag names are direct copies of table's column names):
<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>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:complextype name="simple-xml-format"> <xsd:sequence> <xsd:any minoccurs="0"></xsd:any> </xsd:sequence> </xsd:complextype>
</xsd:schema> fckLRThe element tags <tt><b>simple-xml-format</b></tt> and <tt><b>simple-xml</b></tt> can be customized by setting the appropriate propertiesfckLRon an <tt><b>operation</b></tt>.fckLR</dbws></sessions-file>