|
|
| (16 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.
| + | |
| − | | + | |
| − | EclipseLink DBWS includes two parts
| + | |
| − | *[[EclipseLink/UserGuide/DBWS/Overview/Design time|A design-time component]] (<tt><b>DBWSBuilder</b></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 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 (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. <br/>
| + | |
| − | [[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 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 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.
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws.xml</span>
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws-sessions.xml</span> -- name can be overriden by <sessions-file> entry in eclipselink-dbws.xml
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws-or.xml</span>
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws-ox.xml</span>
| + | |
| − | <span style="font-weight: bold;">eclipselink-dbws-schema.xsd</span>
| + | |
| − | While the files above can be created manually, it is simpler for the user to use the <tt><b>DBWSBuilder</b></tt> utility to generate them.
| + | |
| − | ===== 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.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]] |
