|
|
| (3 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | <css>
| + | For the current version, see: |
| − | .source-sql {padding:1em;border:1px solid black; background-color: white;}
| + | '''[http://www.eclipse.org/eclipselink/documentation/2.4/dbws/toc.htm Developing Persistence Architectures Using EclipseLink Database Web Services, Release 2.4]''' |
| − | .source-java5 {padding:1em;border:1px solid black; background-color: white;}
| + | |
| − | .source-xml {padding:1em;border:1px solid black; background-color: white;}
| + | |
| − | .source-text {padding:1em;border:1px solid black; background-color: white;}
| + | |
| − | </css>
| + | |
| − | {{EclipseLink_UserGuide
| + | |
| − | |info=y
| + | |
| − | |toc=y
| + | |
| − | |eclipselink=y
| + | |
| − | |eclipselinktype=DBWS
| + | |
| − | }}
| + | |
| | | | |
| − | == EclipseLink DBWS Overview ==
| + | For EclispeLink DBWS Overview, see http://www.eclipse.org/eclipselink/documentation/2.4/dbws/overview.htm |
| − | <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.
| + | |
| − | | + | |
| − | === 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. <br/>
| + | |
| − | [[Image:XRRunTime.png]]<br/>
| + | |
| − | EclipseLink DBWS includes two parts
| + | |
| − | *[[EclipseLink/UserGuide/DBWS/Overview/Design time|<tt><b>DBWSBuilder</b></tt> command-line utility]] - the <tt><b>DBWSBuilder</b></tt> utility generates the deployment artifacts (while some of files can be created manually, it is <b>much</b> simpler to use the utility).
| + | |
| − | *[[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>:
| + | |
| − | # <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: can use the complete range of EclipseLink ORM Expression Framework APIs
| + | |
| − | | + | |
| − | === Configuration ===
| + | |
| − | A typical EclipseLink DBWS service is packaged in an archive (typically a <tt>.war</tt> file) with a service descriptor file in the META-INF directory. 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.
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws.xml</span> -- service descriptor file
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws-sessions.xml</span>
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws-or.xml</span> -- EclipseLink mapping file
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws-ox.xml</span> -- EclipseLink mapping file
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws-schema.xsd</span> -- XML Schema definition file
| + | |
| − | | + | |
| − | ===== EclipseLink DBWS Service descriptor file =====
| + | |
| − | 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. The [[EclipseLink/UserGuide/DBWS/Overview/EclipseLink_DBWS_Service_Descriptor_File_(ELUG)| service descriptor file is described in the User Guide]].
| + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <dbws xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
| + | |
| − | <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>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | ===== EclipseLink DBWS Service sessions.xml file =====
| + | |
| − | [[Creating_EclipseLink_Files_for_Deployment_%28ELUG%29#sessions.xml_File|The EclipseLink DBWS Service sessions.xml file (<tt><b>eclipselink-dbws-sessions.xml</b></tt>) is described in the User Guide]].
| + | |
| − | | + | |
| − | ===== EclipseLink DBWS mapping files =====
| + | |
| − | [[Creating_EclipseLink_Files_for_Deployment_%28ELUG%29#project.xml_File|The EclipseLink DBWS Service mapping files (<tt><b>eclipselink-dbws-or.xml,eclipselink-dbws-ox.xml</b></tt>) are described in the User Guide]].
| + | |
| − | | + | |
| − | ===== EclipseLink DBWS Service schema file =====
| + | |
| − | The EclipseLink DBWS Service schema file (<tt><b>eclipselink-dbws-schema.xsd</b></tt>) can be created by hand,
| + | |
| − | or auto-generated by the <tt>DBWSBuilder</tt> utility which derives XML element-tag names from Database metadata
| + | |
| − | (column names, types, nullable, etc).
| + | |
| − | | + | |
| − | ===== Simple XML Format (SXF) =====
| + | |
| − | The <tt>DBWSBuilder</tt> utility will not generate a schema file when the information returned by a <b>query operation</b> has no pre-determined structure:
| + | |
| − | * 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 the resultSet's metadata to build the XML element tag names:
| + | |
| − | <source lang="java5">
| + | |
| − | ResultSetMetaData rsmd = rs.getMetaData();
| + | |
| − | int colcount = rsmd.getColumnCount();
| + | |
| − | for (int i=1; i <= colcount; i++) {
| + | |
| − | String elementName = rsmd.getColumnName(i).toLower(); //empno, ename, job ...
| + | |
| − | }
| + | |
| − | </source>
| + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <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 a schema - or more accurately, only the following <b>very</b> permissive 'sequence-of-any' schema can validate such documents:
| + | |
| − | | + | |
| − | ===== Simple XML Format Schema =====
| + | |
| − | <source lang="xml" enclose="div">
| + | |
| − | <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>
| + | |
| − | </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:DBWS]] | | [[Category:DBWS]] |
