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"
(→Configuration) |
(→Configuration) |
||
Line 22: | Line 22: | ||
===Configuration=== | ===Configuration=== | ||
− | A typical EclipseLink DBWS service is packaged in an archive (<tt>.jar</tt> or <tt>.war</tt> file) with | + | A typical EclipseLink DBWS service is packaged in an archive (<tt>.jar</tt> or <tt>.war</tt> file) with a service descriptor file |
− | 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). | + | <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). |
+ | |||
+ | |||
+ | The service also requires an XML Schema Definition (<tt>.xsd</tt>) file <tt><b>eclipselink-dbws-schema.xsd</b></tt> to specify how returned information from the database is shaped. | ||
+ | |||
+ | |||
+ | The EclipseLink OXM map handles converting information from the database to XML, giving the user access to the complete range of EclipseLink Object-to-XML mapping capabilities. If no schema is provided by the user, a pre-defined Simple XML Format (SXF) can be used. | ||
+ | |||
The service also needs an XML Schema Definition (<tt>.xsd</tt>) file <tt><b>eclipselink-dbws-schema.xsd</b></tt> and an EclipseLink | The service also needs an XML Schema Definition (<tt>.xsd</tt>) file <tt><b>eclipselink-dbws-schema.xsd</b></tt> and an EclipseLink | ||
− | sessions.xml <tt><b>eclipselink-dbws-sessions.xml</b></tt>. The sessions.xml file points to two Eclipse projects - one for the ORM side, | + | sessions.xml <tt><b>eclipselink-dbws-sessions.xml</b></tt>. |
− | the other for the OXM side. | + | |
+ | The sessions.xml file points to two Eclipse projects - one for the ORM side, the other for the OXM side. | ||
Revision as of 13:41, 19 March 2009
EclipseLink DBWS Overview
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 components (ORM, OXM).
EclipseLink DBWS has two parts: a design-time tooling component (DBWSBuilder) 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.
An EclipseLink DBWS service may be comprised of any number of operations of which there are 4 types:
- 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)
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).
The service also requires an XML Schema Definition (.xsd) file eclipselink-dbws-schema.xsd to specify how returned information from the database is shaped.
The EclipseLink OXM map handles converting information from the database to XML, giving the user access to the complete range of EclipseLink Object-to-XML mapping capabilities. If no schema is provided by the user, a pre-defined Simple XML Format (SXF) can be used.
The service also needs an XML Schema Definition (.xsd) file eclipselink-dbws-schema.xsd and an EclipseLink sessions.xml eclipselink-dbws-sessions.xml.
The sessions.xml file points to two Eclipse projects - one for the ORM side, the other for the OXM side.
- EclipseLink metadata in the form of a EclipseLink Project (either deployment XML located
in the META-INF/ directory or Java classes
The metadata for an EclipseLink DBWS service is contained in :
- contains name of EclipseLink DBWS service
- contains name of sessions.xml - if not present, then 'eclipselink-dbws-sessions.xml' will be used
- operation definitions
Example DBWS Service descriptor file
<?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> <query> <name>countEmployees <result> <type>xsd:int</type> </result> <sql><![CDATA[select count(*) from EMP]]></sql> </query> </dbws>
The information required in the eclipselink-dbws.xml is kept to a minimum and omitted fields have simple defaults, allowing for both auto-generation by tools or manual editing.
The EclipseLink DBWS service descriptor file is described in full in the User Guide.
XML Schema Definition
An EclipseLink DBWS service requires an XML Schema Definition file to specify how information returned from the database is to be shaped. All EclipseLink Object-to-XML mapping capabilities are available to describe how objects are converted to XML (and vice-versa). The design-time tool can auto-generate an XML Schema.
An example of an auto-generated XML Schema
The design-time tool derives element-tag names from Database table metadata (column names, types, nullable, etc):
OWNER | TABLE_NAME | COLUMN_NAME | DATA_TYPE | DATA_LENGTH | DATA_PRECISION | DATA_SCALE | NULLABLE |
---|---|---|---|---|---|---|---|
SCOTT | EMP | EMPNO | NUMBER | 22 | 4 | 0 | N |
SCOTT | EMP | ENAME | VARCHAR2 | 10 | (null) | (null) | Y |
SCOTT | EMP | JOB | VARCHAR2 | 9 | (null) | (null) | Y |
SCOTT | EMP | MGR | NUMBER | 22 | 4 | 0 | Y |
SCOTT | EMP | HIREDATE | DATE | 7 | (null) | (null) | Y |
SCOTT | EMP | SAL | NUMBER | 22 | 7 | 2 | Y |
SCOTT | EMP | COMM | NUMBER | 22 | 7 | 2 | Y |
SCOTT | EMP | DEPTNO | NUMBER | 22 | 2 | 0 | Y |
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" > <xsd:complexType name="empType"> <xsd:sequence> <xsd:element name="empno" type="xsd:int" xsi:nil="false"/> <xsd:element name="ename" type="xsd:string" xsi:nil="true"/> <xsd:element name="job" type="xsd:string" xsi:nil="true"/> <xsd:element name="mgr" type="xsd:int" minOccurs="0" xsi:nil="true"/> <xsd:element name="hiredate" type="xsd:dateTime" xsi:nil="true"/> <xsd:element name="sal" type="xsd:decimal" xsi:nil="true"/> <xsd:element name="comm" type="xsd:int" minOccurs="0" xsi:nil="true"/> <xsd:element name="deptno" type="xsd:int" xsi:nil="true"/> </xsd:sequence> </xsd:complexType> </xsd:schema>
Simple XML Format (SXF)
The design-time tools 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
<?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>
The EclipseLink DBWS runtime provider uses information gathered at the time of query execution to build XML element-tag names; thus, these XML documents are 'dumb' as they cannot be validated against any schema - or more accurately, only the 'anything' schema above can validate such documents.
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>
The element tags simple-xml-format and simple-xml can be customized.