|
|
(94 intermediate revisions by the same user not shown) |
Line 1: |
Line 1: |
− | <div style="float:right;border:1px solid #000000;padding:5px;max-width:500px;">__TOC__</div>
| + | For the current version, see: |
− | ==EclipseLink DBWS Overview==
| + | '''[http://www.eclipse.org/eclipselink/documentation/2.4/dbws/toc.htm Developing Persistence Architectures Using EclipseLink Database Web Services, Release 2.4]''' |
− | <onlyinclude>
| + | |
− | The goal of EclipseLink DBWS is to enable simple and efficient access to relational database artifacts via a Web service, extending 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.
| + | For EclispeLink DBWS Overview, see http://www.eclipse.org/eclipselink/documentation/2.4/dbws/overview.htm |
| | | |
− | An EclipseLink DBWS service may be comprised of any number of '''operations''' of which there are 4 types:
| + | [[Category:DBWS]] |
− | # '''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. <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)
| + | |
− | | + | |
− | The XML documents used by an '''operation''' conform to an XML Schema Definition (<tt>.xsd</tt> 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.
| + | |
− | [[Image:XRRunTime.png]]
| + | |
− | </onlyinclude>
| + | |
− | | + | |
− | ===Configuration===
| + | |
− | The metadata for an EclipseLink DBWS service is contained in an easy-to-read service descriptor file <b>eclipselink-dbws.xml</b>:
| + | |
− | * contains <b><i>name of EclipseLink DBWS service</i></b>
| + | |
− | * contains <b><i>name of sessions.xml</i></b> - if not present, then <tt>'eclipselink-dbws-sessions.xml'</tt> will be used
| + | |
− | * operation definitions
| + | |
− | Example DBWS Service descriptor file
| + | |
− | <source lang="xml">
| + | |
− | <?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>
| + | |
− | </source>
| + | |
− | The information required by the EclipseLink DBWS service descriptor file is kept to a minimum and omitted fields have simple defaults, allowing for both auto-generation by tools or manual editing.
| + | |
− | | + | |
− | ===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):
| + | |
− | {| border="1" cellpadding="5" cellspacing="1"
| + | |
− | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|OWNER
| + | |
− | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|TABLE_NAME
| + | |
− | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|COLUMN_NAME
| + | |
− | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|DATA_TYPE
| + | |
− | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|DATA_LENGTH
| + | |
− | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|DATA_PRECISION
| + | |
− | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|DATA_SCALE
| + | |
− | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|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
| + | |
− | |}
| + | |
− | <source lang="xml">
| + | |
− | <?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>
| + | |
− | </source>
| + | |
− | | + | |
− | ====Simple XML Format (SXF)====
| + | |
− | The design-time tools will not generate an XML Schema Definition when the information returned by a <b>query operation</b> has no pre-determined structure, such as:
| + | |
− | * 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>
| + | |
− | | + | |
− | <source lang="xml" border="1">
| + | |
− | <?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>
| + | |
− | </source>
| + | |
− | The EclipseLink DBWS runtime provider uses information only available 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 'sequence-of-any' schema above can validate the documents.
| + | |
− | <source lang="xml">
| + | |
− | 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>
| + | |
− | </source>
| + | |
− | | + | |
− | | + | |
− | ----
| + | |
− | [[Category: Release 1.1]]
| + | |
− | [[Category: DBWS]] | + | |