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/Development/DBWS"
(→Builder operations have common attributes:) |
|||
Line 576: | Line 576: | ||
==== Builder operations common attributes: ==== | ==== Builder operations common attributes: ==== | ||
+ | {| 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;"|Name | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Description | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Required | ||
+ | |- | ||
+ | | <tt>name</tt> | ||
+ | | | ||
+ | | name of operation | ||
+ | |- | ||
+ | | <tt>isCollection </tt> | ||
+ | | <tt>false</tt> | ||
+ | | the operation returns more than a single row | ||
+ | |- | ||
+ | | <tt>isSimpleXMLFormat </tt> | ||
+ | | <tt>false</tt> | ||
+ | | the operation returns rows formatted as Simple XML Format elements | ||
+ | |- | ||
+ | | <tt>simpleXMLFormatTag </tt> | ||
+ | | <tt><simple-xml-format></tt> | ||
+ | | name of root-level Simple XML Format element-tag | ||
+ | |- | ||
+ | | <tt>xmlTag </tt> | ||
+ | | <tt><simple-xml></tt> | ||
+ | | name of grouping XML element-tag for rows | ||
+ | |- | ||
+ | | <tt>binaryAttachment </tt> | ||
+ | | <tt>false</tt> | ||
+ | | the operation returns binary data as a SOAP attachment | ||
+ | |- | ||
+ | | <tt>returnType </tt> | ||
+ | | (optional) | ||
+ | | if the operation's returnType cannot be deduced from database metadata, this attribute allows the user to specify the schema returnType | ||
+ | |- | ||
+ | |} | ||
− | + | <tt><u><sql></u></tt> operation | |
− | + | The SQL text is a CDATA text element. | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | +<sql>+ operation | + | <b>Nested Elements</b> |
+ | <u>binding</u> | ||
+ | Binds type information to JDBC argument markers in the SQL text. | ||
+ | |||
+ | <tt><u><procedure></u></tt> operation | ||
+ | {| 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;"|Attribute | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Description | ||
+ | |- | ||
+ | | catalogPattern | ||
+ | | pattern of matching catalogs (SQL-92 '%' wild-card supported) | ||
+ | |- | ||
+ | | schemaPattern | ||
+ | | pattern of matching schemas (SQL-92 '%' wild-card supported) | ||
+ | |- | ||
+ | | procedurePattern | ||
+ | | pattern of matching stored procedures(SQL-92 '%' wild-card supported) | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | <tt><u><table></u></tt> operation | ||
+ | {| 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;"|Attribute | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Description | ||
+ | |- | ||
+ | | catalogPattern | ||
+ | | pattern of matching catalogs (SQL-92 '%' wild-card supported) | ||
+ | |- | ||
+ | | schemaPattern | ||
+ | | pattern of matching schemas (SQL-92 '%' wild-card supported) | ||
+ | |- | ||
+ | | tableNamePattern | ||
+ | | pattern of matching tables (SQL-92 '%' wild-card supported) | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | <b>Nested Elements</b> | ||
+ | A | ||
+ | == Document History == | ||
+ | {|{{BMTableStyle}} | ||
+ | |-{{BMTHStyle}} | ||
+ | ! Date | ||
+ | ! Author | ||
+ | ! Version Description & Notes | ||
+ | |- | ||
+ | | 080821 | ||
+ | | Mike Norman | ||
+ | | 1.0 (brought over from TopLink FS 14737 wiki document) | ||
+ | |} | ||
+ | |||
+ | == Overview == | ||
+ | The goal of DBWS is to enable simple and efficient access to relational database artifacts via a Web Service. DBWS extends EclipseLink's core capabilities while leveraging existing components (ORM, OXM). | ||
+ | |||
+ | EclipseLink DBWS has two parts: a design-time tooling component 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 a Web Service client. | ||
+ | |||
+ | An 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. <br>Selection criteria for Query operations can be specified by: | ||
+ | #* custom <tt>SQL</tt> | ||
+ | #* Stored Procedures | ||
+ | #* TopLink Expressions | ||
+ | #* JP-QL | ||
+ | |||
+ | The XML documents used by operations conform to an XML Schema Definition <tt>.xsd</tt> document auto-generated by the design-time tooling. Alternatively, if no <tt>.xsd</tt> is available, a pre-defined simple XML format (SXF) can be used. | ||
+ | |||
+ | == Concepts == | ||
+ | XML-to-Relational | ||
+ | |||
+ | A flexible component that maps between a database's relational structure(s) and XML's hierarchical structure{excerpt}. The use of EclipseLink's ORM and OXM features provides the basis for a powerful '''bridge''' between the two. To date, the only concrete realization of an XRM bridge is EclipseLink DBWS. | ||
+ | |||
+ | [[Image:XRRunTime.png]] | ||
+ | |||
+ | == Requirements == | ||
+ | The requirements of this feature are focused around the simple and efficient access to relational database artifact(s) via a Web Service. The use of EclipseLink ORM provides cross-database support and caching for performance; the use of EclipseLink OXM provides XML mapping flexibility. The goal is to simply realize a Web Service while allowing expert users to use advanced EclipseLink features. | ||
+ | |||
+ | === Configuration === | ||
+ | The metadata for an DBWS service is contained in an easy-to-read service descriptor XML file. The internal configuration requirements are minimal and omitted fields have simple defaults, allowing for both auto-generation by tools or manual editing. Additional EclipseLink metadata - ORM and OXM maps, customizations - will be handled using existing EclipseLink <tt>sessions.xml</tt> capabilities. | ||
+ | |||
+ | === XML Schema Definition (.xsd) === | ||
+ | A DBWS service requires an XML Schema Definition <tt>.xsd</tt> file 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. | ||
+ | <blockquote style="padding:4px;border:1px solid black;"> | ||
+ | SXF uses information only available at the time of query execution to build the XML element-tag names; thus, these XML documents cannot be validated against any schema. | ||
+ | </blockquote> | ||
+ | |||
+ | === Auto-generation of a DBWS service === | ||
+ | The design-time tooling will auto-generate a DBWS service, creating the service descriptor and all required deployment artifacts (see section [[tbd]] for more details). | ||
+ | |||
+ | === Use of pre-existing EclipseLink ORM and OXM maps === | ||
+ | A DBWS service may be constructed using pre-existing EclipseLink ORM and OXM maps (both Project classes and Project deployment XML are supported) with the following naming convention: | ||
+ | : 1. identical case-sensitive Project names | ||
+ | <blockquote style="padding:4px;border:1px solid black;"> | ||
+ | <source lang="xml"> | ||
+ | <xml version="1.0" encoding="UTF-8"?> | ||
+ | <object-persistence version="Eclipse Persistence Services - @VERSION@ (Build @BUILD_NUMBER@)" | ||
+ | xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
+ | xmlns="http://www.eclipse.org/eclipselink/xsds/persistence" | ||
+ | > | ||
+ | <name>Example</name> | ||
+ | </source> or | ||
+ | <source lang="java"> | ||
+ | import org.eclipse.persistence.sessions.Project; | ||
+ | public class SomeORProject extends Project { | ||
+ | public SomeORProject () { | ||
+ | setName("Example"); | ||
+ | ... | ||
+ | } | ||
+ | public class SomeOXProject extends Project { | ||
+ | public SomeOXProject () { | ||
+ | setName("Example"); | ||
+ | ... | ||
+ | } | ||
+ | </source></blockquote> | ||
+ | : 2. identical case-sensitive aliases for Descriptors that are common between the projects | ||
+ | <blockquote style="padding:4px;border:1px solid black;"> | ||
+ | <source lang="xml"> | ||
+ | <class-mapping-descriptor xsi:type="eclipselink:relational-class-mapping-descriptor"> | ||
+ | <class>some.package.SomeClass</class> | ||
+ | <alias>SomeAlias</alias> | ||
+ | ... | ||
+ | <class-mapping-descriptor xsi:type="eclipselink:xml-class-mapping-descriptor"> | ||
+ | <class>some.package.SomeClass</class> | ||
+ | <alias>SomeAlias</alias> | ||
+ | </source> | ||
+ | </blockquote> | ||
+ | Any existing named queries from the EclipseLink ORM map may be exposed as query operations for the EclipseLink DBWS service; additional Insert/Update/Delete/Query operations can be added. Pre-existing domain classes can be bundled with the service so that they are available at runtime. | ||
+ | |||
+ | === Tables === | ||
+ | Special case of auto-generation: provide only JDBC connection info + table name ==> a DBWS service with <b>CRUD</b> (<b><i><u>C</u></i>reate/<i><u>R</u></i>ead</b>(findByPK,findAll)<b>/<i><u>U</u></i>pdate/<i><u>D</u></i>elete</b>) operations. | ||
+ | |||
+ | === Stored Procedures === | ||
+ | The user will be able to specify the use of Stored Procedure/Functions as the selection criteria for query operations. The design-time tooling will auto-generate (based on available database metadata) the required argument and return type information. | ||
+ | <blockquote style="padding:4px;border:1px solid black;"> | ||
+ | If the database metadata is not available, custom Java classes + manual editing of the service metadata will allow the desired Stored Procedure to be supported. | ||
+ | </blockquote> | ||
+ | |||
+ | === Advanced Types === | ||
+ | A Stored Procedure may used advanced JDBC types - STRUCTs and VARRAYs - as arguments or return types, or even datatypes that have no JDBC equivalent (i.e. PL/SQL types). These use-cases are supported using custom Java classes + manual editing of the service's metadata. | ||
+ | <blockquote style="padding:4px;border:1px solid black;"> | ||
+ | The DBWSBuilder command-line tool does not (yet) support extracting the required database metadata for Advanced Types. | ||
+ | </blockquote> | ||
+ | |||
+ | === Dynamic Domain Model === | ||
+ | Domain model classes are not required either in source form or <tt>.class</tt> files. At runtime, Eclipse will use bytecode weaving techniques to dynamically generate in-memory versions of compatible classes. | ||
+ | |||
+ | == Public API == | ||
+ | The Public API for DBWS is its metadata and the <tt>DBWSBuilder</tt> design-time tool. | ||
+ | |||
+ | === DBWS metadata === | ||
+ | Packaging required for deployment as a Web Service <tt><b>xxx.war</b></tt> | ||
+ | <pre style="padding:4px;border:1px solid black;"> | ||
+ | root of war file | ||
+ | \---web-inf | ||
+ | | | ||
+ | | web.xml | ||
+ | | | ||
+ | +---classes | ||
+ | | +---foo -- optional domain classes | ||
+ | | | \---bar | ||
+ | | | Address.class | ||
+ | | | Employee.class | ||
+ | | | PhoneNumber.class | ||
+ | | | | ||
+ | | +---META-INF | ||
+ | | | eclipselink-dbws-or.xml | ||
+ | | | eclipselink-dbws-ox.xml | ||
+ | | | eclipselink-dbws-sessions.xml -- name can be overriden by <sessions-file> entry in eclipselink-dbws.xml | ||
+ | | | eclipselink-dbws.xml | ||
+ | | | | ||
+ | | \---_dbws | ||
+ | | DBWSProvider.class -- auto-generated JAX-WS 2.x Provider 'stub' | ||
+ | | DBWSProvider.java | ||
+ | | | ||
+ | \---wsdl | ||
+ | eclipselink-dbws-schema.xsd | ||
+ | eclipselink-dbws.wsdl | ||
+ | swaref.xsd -- optional to handle attachements | ||
+ | </pre> | ||
+ | The files <tt>swaref.xsd</tt> and <tt>web.xml</tt> have names+content determined by their roles in web deployment and cannot be changed. | ||
+ | |||
+ | <b>eclipselink-dbws.xml</b> | ||
+ | * contains <b><i>name-of-service</i></b> | ||
+ | * contains <b><i>name-of-sessions.xml</i></b> - if not present, then <tt><b>eclipselink-dbws-sessions.xml</b></tt> will be used | ||
+ | * operation definitions | ||
+ | * schema for this file is: <tt><b>.../xsds/eclipselink-dbws_1.0.xsd</b></tt> | ||
+ | |||
+ | <b>Example DBWS Service descriptor file</b> | ||
+ | <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> | ||
+ | <sessions-file>example-dbws-sessions.xml</sessions-file> | ||
+ | <query> | ||
+ | <name>countEmployees | ||
+ | <result> | ||
+ | <type>xsd:int</type> | ||
+ | <simple-xml-format> | ||
+ | <simple-xml-format-tag>employee-info | ||
+ | <simple-xml-tag>aggregate-info | ||
+ | </simple-xml-format> | ||
+ | </result> | ||
+ | <sql><![CDATA[select count(*) from EMP]]></sql> | ||
+ | </query> | ||
+ | <query> | ||
+ | <name>findAllEmployees | ||
+ | <result isCollection="true"> | ||
+ | <type>empType</type> | ||
+ | </result> | ||
+ | <sql><![CDATA[select * from EMP]]></sql> | ||
+ | </query> | ||
+ | </dbws> | ||
+ | </source> | ||
+ | <b>eclipselink-dbws_1.0.xsd</b> | ||
+ | <source lang="xml"> | ||
+ | <?xml version="1.0" encoding="utf-8"?> | ||
+ | <xsd:schema version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
+ | <xsd:complexType name="simple-xml-format-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element minOccurs="0" name="simple-xml-format-tag" type="xsd:string" /> | ||
+ | <xsd:element minOccurs="0" name="simple-xml-tag" type="xsd:string" /> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="procedure-argument-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element name="name" type="xsd:string" /> | ||
+ | <xsd:element name="parameterName" type="xsd:string" /> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="out-procedure-argument-type"> | ||
+ | <xsd:complexContent mixed="false"> | ||
+ | <xsd:extension base="procedure-argument-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element minOccurs="0" name="type" type="xsd:QName" /> | ||
+ | </xsd:sequence> | ||
+ | </xsd:extension> | ||
+ | </xsd:complexContent> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="xql-query-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element name="text" type="xsd:string" /> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="named-query-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element name="name" type="xsd:string" /> | ||
+ | <xsd:element name="descriptor" type="xsd:string" /> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="stored-procedure-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element name="name" type="xsd:string" /> | ||
+ | <xsd:sequence minOccurs="0" maxOccurs="unbounded"> | ||
+ | <xsd:element name="in-argument" type="procedure-argument-type" /> | ||
+ | </xsd:sequence> | ||
+ | <xsd:sequence minOccurs="0" maxOccurs="unbounded"> | ||
+ | <xsd:element name="inout-argument" type="out-procedure-argument-type" /> | ||
+ | </xsd:sequence> | ||
+ | <xsd:sequence minOccurs="0" maxOccurs="unbounded"> | ||
+ | <xsd:element name="out-argument" type="out-procedure-argument-type" /> | ||
+ | </xsd:sequence> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="attachment-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element name="mime-type" type="xsd:string" /> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="result-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element minOccurs="0" name="type" type="xsd:QName" /> | ||
+ | <xsd:element minOccurs="0" name="attachment" type="attachment-type" /> | ||
+ | <xsd:element minOccurs="0" name="simple-xml-format" type="simple-xml-format-type" /> | ||
+ | </xsd:sequence> | ||
+ | <xsd:attribute name="isCollection" type="xsd:boolean" use="optional" /> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="parameter-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element name="name" type="xsd:string" /> | ||
+ | <xsd:element name="type" type="xsd:QName" /> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="query-operation"> | ||
+ | <xsd:complexContent mixed="false"> | ||
+ | <xsd:extension base="operation-with-parameters-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element minOccurs="0" name="result" type="result-type" /> | ||
+ | <xsd:sequence minOccurs="0" maxOccurs="unbounded"> | ||
+ | <xsd:choice> | ||
+ | <xsd:element name="jpql" type="xql-query-type" /> | ||
+ | <xsd:element name="named-query" type="named-query-type" /> | ||
+ | <xsd:element name="sql" type="xql-query-type" /> | ||
+ | <xsd:element name="stored-procedure" type="stored-procedure-type" /> | ||
+ | <xsd:element name="stored-function" type="stored-procedure-type" /> | ||
+ | </xsd:choice> | ||
+ | </xsd:sequence> | ||
+ | </xsd:sequence> | ||
+ | </xsd:extension> | ||
+ | </xsd:complexContent> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="operation-with-parameters-type"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element name="name" type="xsd:string" /> | ||
+ | <xsd:sequence minOccurs="0" maxOccurs="unbounded"> | ||
+ | <xsd:element name="parameter" type="parameter-type" /> | ||
+ | </xsd:sequence> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:complexType name="dbws-type"> | ||
+ | <xsd:annotation> | ||
+ | <xsd:documentation><![CDATA[ | ||
+ | This is the XML Schema for EclipseLink Database WebService (DBWS) model. | ||
+ | ]]></xsd:documentation> | ||
+ | </xsd:annotation> | ||
+ | <xsd:sequence> | ||
+ | <xsd:element name="name" type="xsd:string" /> | ||
+ | <xsd:element minOccurs="0" name="sessions-file" type="xsd:string" /> | ||
+ | <xsd:sequence minOccurs="0" maxOccurs="unbounded"> | ||
+ | <xsd:choice> | ||
+ | <xsd:element name="insert" type="operation-with-parameters-type" /> | ||
+ | <xsd:element name="query" type="query-operation" /> | ||
+ | <xsd:element name="update" type="operation-with-parameters-type" /> | ||
+ | <xsd:element name="delete" type="operation-with-parameters-type" /> | ||
+ | </xsd:choice> | ||
+ | </xsd:sequence> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:element name="dbws" type="dbws-type" /> | ||
+ | </xsd:schema> | ||
+ | </source> | ||
+ | <b>eclipselink-dbws-sessions.xml</b> | ||
+ | * contains references to the EclipseLink ORM and OXM maps (either Java classes or deployment XML) | ||
+ | ** supports all other features of EclipseLink <tt>sessions.xml</tt> file: platform declaration, logging, login/datasource info, session customization, etc. | ||
+ | * name of ORM map: <b>eclipselink-dbws-or.xml</b> | ||
+ | * name of OXM map: <b>eclipselink-dbws-ox.xml</b> | ||
+ | * name of ORM session: <b><i>name-of-service</i>-dbws-or-session</b> | ||
+ | * name of OXM session: <b><i>name-of-service</i>-dbws-ox-session</b> | ||
+ | |||
+ | <b>eclipselink-dbws-schema.xsd</b> | ||
+ | * contains XML type definitions used by operation arguments and return types | ||
+ | |||
+ | <b>eclipselink-dbws.wsdl</b> | ||
+ | * required for deployment as a Web Service | ||
+ | * contains equivalent entries for each operation for the specified EclipseLink DBWS service | ||
+ | |||
+ | === SXF (Simple XML Format) === | ||
+ | Commonly used when the persistent entities returned by a query operation have no structure: | ||
+ | * resultSet from custom SQL <tt>SELECT</tt> statement | ||
+ | * results from a Stored Procedure/Function, updated-rows count from Update operation | ||
+ | <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="sxfType"> | ||
+ | <xsd:sequence> | ||
+ | <xsd:any minOccurs="0"/> | ||
+ | </xsd:sequence> | ||
+ | </xsd:complexType> | ||
+ | <xsd:element name="simple-xml-format" type="sxfType"/> | ||
+ | </xsd:schema> | ||
+ | </source> | ||
+ | The EclipseLink DBWS runtime will produce documents that are simple and are 'human-readable'; however, these documents are 'dumb' as they cannot be validated against any schema: | ||
+ | <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> | ||
+ | The element-tags <tt><simple-xml-format></tt> and <tt><xml></tt> can be customized: | ||
+ | <source lang="xml"> | ||
+ | <?xml version = '1.0' encoding = 'UTF-8'?> | ||
+ | <employee-info> | ||
+ | <aggregate-info> | ||
+ | <count>14</count> | ||
+ | <max-salary>3000</max-salary> | ||
+ | </aggregate-info> | ||
+ | </employee-info> | ||
+ | </source> | ||
+ | |||
+ | === Auto-generated XML Schema Definition <tt>.xsd</tt> === | ||
+ | An <tt>.xsd</tt> file is auto-generated by the design-time tooling, deriving 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:element name="emp" type="empType"/> | ||
+ | </xsd:schema> | ||
+ | </source> | ||
+ | <b>Database Metadata</b><br> | ||
+ | The design-time tooling relies on database metadata pertaining to: | ||
+ | * tables: column name, type, precision/scale, nullable | ||
+ | * Stored Procedures: argument and return types, names | ||
+ | <blockquote style="padding:4px;border:1px solid black;"> | ||
+ | not yet supported - JDBC metadata for <tt>STRUCT</tt>'s, <tt>VARRAY</tt>'s, and PL/SQL records | ||
+ | </blockquote> | ||
+ | |||
+ | === Design-time Tool === | ||
+ | The DBWS design-time tool is a Java application that processes the operations described in a DBWS builder .xml file to produce the requisite files (described previously). | ||
+ | <blockquote style="padding:4px;border:1px solid black;"> | ||
+ | <tt>prompt> java -cp eclipselink.jar:eclipselink-dbwsutil.jar:your_favourite_jdbc_driver.jar org.eclipse.persistence.tools.dbws.DBWSBuilder -builderFile {path_to_dbws_builder.xml_file} -packageAs {how_to_package_output} -stageDir {path_to_staging_directory}</tt> | ||
+ | </blockquote> | ||
+ | <source lang="xml"> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
+ | <properties> | ||
+ | <property name="projectName">test</property> | ||
+ | <property name="driver">oracle.jdbc.OracleDriver</property> | ||
+ | <property name="password">tiger</property> | ||
+ | <property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property> | ||
+ | <property name="username">scott</property> | ||
+ | </properties> | ||
+ | <table catalogPattern="%" schemaPattern="SCOTT" tableNamePattern="XR_EMP"> | ||
+ | <procedure returnType="dfdf" catalogPattern="SOME_PKG" schemaPattern="SCOTT" procedurePattern="GetEmployeeByEMPNO_DEPTNO"/> | ||
+ | <sql name="findXREmpByName" isCollection="true" returnType="xr_empType"> | ||
+ | <text> | ||
+ | <![CDATA[select * from XR_EMP where ENAME like ?]]> | ||
+ | </text> | ||
+ | <binding name="ENAME" type="xsd:string"/> | ||
+ | </sql> | ||
+ | </table> | ||
+ | <sql name="employeeInfo" simpleXMLFormatTag="employee-info" xmlTag="aggregate-counts" > | ||
+ | <text> | ||
+ | <![CDATA[select count(*) as "COUNT", max(SAL) as "MAX-Salary" from EMP]]> | ||
+ | </text> | ||
+ | </sql> | ||
+ | </dbws-builder> | ||
+ | </source> | ||
+ | |||
+ | ==== Properties ==== | ||
+ | {| 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;"|Name | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Description | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Required | ||
+ | |- | ||
+ | | <tt>projectName</tt> | ||
+ | | the name of the EclipseLink DBWS service | ||
+ | | Yes | ||
+ | |- | ||
+ | | <tt>username</tt> | ||
+ | | username | ||
+ | | Yes | ||
+ | |- | ||
+ | | <tt>password</tt> | ||
+ | | Database password | ||
+ | | Yes | ||
+ | |- | ||
+ | | <tt>url</tt> | ||
+ | | Database connection url | ||
+ | | Yes | ||
+ | |- | ||
+ | | <tt>driver</tt> | ||
+ | | Class name of the jdbc driver | ||
+ | | Yes | ||
+ | |- | ||
+ | | <tt>contextRoot</tt> | ||
+ | | the Web Services Provider servlet requires a <tt><url-pattern></tt> for its <tt><servlet-mapping></tt> element in the <tt>web.xml</tt> file | ||
+ | | No; default is <tt>/ + projectName</tt> | ||
+ | |- | ||
+ | | <tt>dataSource</tt> | ||
+ | | JNDI Datasource location to be inserted in DBWS <tt>sessions.xml</tt> file | ||
+ | | No | ||
+ | |- | ||
+ | | <tt>sessionsFileName</tt> | ||
+ | | name of EclipseLink <tt>sessions.xml</tt> file to add to DBWS service <tt>.war</tt> file | ||
+ | | No; default is <tt>eclipselink-dbws-sessions.xml</tt> | ||
+ | |- | ||
+ | | <tt>platformClassname</tt> | ||
+ | | EclipseLink database platform classname | ||
+ | | No; default is <tt>org.eclipse.persistence.platform.database.MySQLPlatform</tt> | ||
+ | |- | ||
+ | | <tt>orSessionCustomizerClassName</tt> | ||
+ | | <tt>eclipse.persistence.config.SessionCustomizer</tt> classname to add to DBWS service <tt>sessions.xml</tt> file | ||
+ | | No | ||
+ | |- | ||
+ | | <tt>oxSessionCustomizerClassName</tt> | ||
+ | | <tt>eclipse.persistence.config.SessionCustomizer</tt> classname to add to DBWS service <tt>sessions.xml</tt> file | ||
+ | | No | ||
+ | |- | ||
+ | | <tt>wsdlLocationURI</tt> | ||
+ | | URI of this DBWS service's WSDL (used by Web Service tools to generate client code) | ||
+ | | No; default is <nowiki>http://localhost:7001/</nowiki><tt>projectName</tt> | ||
+ | |- | ||
+ | | <tt>logLevel</tt> | ||
+ | | EclipseLink logging level to be inserted in DBWS <tt>sessions.xml</tt> file | ||
+ | | No; default is <tt>INFO</tt> | ||
+ | |- | ||
+ | | <tt>targetNamespace</tt> | ||
+ | | URI of targetNamespace to be inserted in DBWS schema | ||
+ | | No; default is <tt>urn: + projectName</tt> | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | ==== Builder operations common attributes: ==== | ||
+ | {| 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;"|Name | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Description | ||
+ | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Required | ||
+ | |- | ||
+ | | <tt>name</tt> | ||
+ | | | ||
+ | | name of operation | ||
+ | |- | ||
+ | | <tt>isCollection </tt> | ||
+ | | <tt>false</tt> | ||
+ | | the operation returns more than a single row | ||
+ | |- | ||
+ | | <tt>isSimpleXMLFormat </tt> | ||
+ | | <tt>false</tt> | ||
+ | | the operation returns rows formatted as Simple XML Format elements | ||
+ | |- | ||
+ | | <tt>simpleXMLFormatTag </tt> | ||
+ | | <tt><simple-xml-format></tt> | ||
+ | | name of root-level Simple XML Format element-tag | ||
+ | |- | ||
+ | | <tt>xmlTag </tt> | ||
+ | | <tt><simple-xml></tt> | ||
+ | | name of grouping XML element-tag for rows | ||
+ | |- | ||
+ | | <tt>binaryAttachment </tt> | ||
+ | | <tt>false</tt> | ||
+ | | the operation returns binary data as a SOAP attachment | ||
+ | |- | ||
+ | | <tt>returnType </tt> | ||
+ | | (optional) | ||
+ | | if the operation's returnType cannot be deduced from database metadata, this attribute allows the user to specify the schema returnType | ||
+ | |- | ||
+ | |} | ||
+ | |||
+ | <tt><u><sql></u></tt> operation | ||
The SQL text is a CDATA text element. | The SQL text is a CDATA text element. | ||
− | + | ||
− | + | <b>Nested Elements</b> | |
+ | <u>binding</u> | ||
Binds type information to JDBC argument markers in the SQL text. | Binds type information to JDBC argument markers in the SQL text. | ||
− | + | <tt><u><procedure></u></tt> operation | |
− | ||Attribute | + | {| border="1" cellpadding="5" cellspacing="1" |
− | | catalogPattern | pattern of matching catalogs (SQL-92 '%' wild-card supported) | | + | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Attribute |
− | | schemaPattern | pattern of matching schemas (SQL-92 '%' wild-card supported) | | + | ! style="border-width: 1px;border-style: solid;border-color: #ccc;padding: 5px;background-color: #f0f0f0;text-align: left;vertical-align: top;color: #003366;"|Description |
− | | procedurePattern | pattern of matching stored procedures (SQL-92 '%' wild-card supported) | | + | |- |
+ | | catalogPattern | ||
+ | | pattern of matching catalogs (SQL-92 '%' wild-card supported) | ||
+ | |- | ||
+ | | schemaPattern | ||
+ | | pattern of matching schemas (SQL-92 '%' wild-card supported) | ||
+ | |- | ||
+ | | procedurePattern | ||
+ | | pattern of matching stored procedures(SQL-92 '%' wild-card supported) | ||
+ | |- | ||
+ | |} | ||
− | + | <tt><u><table></u></tt> operation can have nested +<sql>+ or +<procedure>+ operations associated with it; these operations can use the table's schema to return entities (usually +<sql>+ or +<procedure>+ operations only return simpleXMLFormat'd rows). | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
<b>eclipselink-dbws-builder_1.0.xsd</b> | <b>eclipselink-dbws-builder_1.0.xsd</b> |
Revision as of 14:18, 25 August 2008
EclipseLink Database Web Services
Document History
Date | Author | Version Description & Notes |
---|---|---|
080821 | Mike Norman | 1.0 (brought over from TopLink FS 14737 wiki document) |
Overview
The goal of DBWS is to enable simple and efficient access to relational database artifacts via a Web Service. DBWS extends EclipseLink's core capabilities while leveraging existing components (ORM, OXM).
EclipseLink DBWS has two parts: a design-time tooling component 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 a Web Service client.
An 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
- Stored Procedures
- TopLink Expressions
- JP-QL
The XML documents used by operations conform to an XML Schema Definition .xsd document auto-generated by the design-time tooling. Alternatively, if no .xsd is available, a pre-defined simple XML format (SXF) can be used.
Concepts
XML-to-Relational
A flexible component that maps between a database's relational structure(s) and XML's hierarchical structure{excerpt}. The use of EclipseLink's ORM and OXM features provides the basis for a powerful bridge between the two. To date, the only concrete realization of an XRM bridge is EclipseLink DBWS.
Requirements
The requirements of this feature are focused around the simple and efficient access to relational database artifact(s) via a Web Service. The use of EclipseLink ORM provides cross-database support and caching for performance; the use of EclipseLink OXM provides XML mapping flexibility. The goal is to simply realize a Web Service while allowing expert users to use advanced EclipseLink features.
Configuration
The metadata for an DBWS service is contained in an easy-to-read service descriptor XML file. The internal configuration requirements are minimal and omitted fields have simple defaults, allowing for both auto-generation by tools or manual editing. Additional EclipseLink metadata - ORM and OXM maps, customizations - will be handled using existing EclipseLink sessions.xml capabilities.
XML Schema Definition (.xsd)
A DBWS service requires an XML Schema Definition .xsd file 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.
SXF uses information only available at the time of query execution to build the XML element-tag names; thus, these XML documents cannot be validated against any schema.
Auto-generation of a DBWS service
The design-time tooling will auto-generate a DBWS service, creating the service descriptor and all required deployment artifacts (see section tbd for more details).
Use of pre-existing EclipseLink ORM and OXM maps
A DBWS service may be constructed using pre-existing EclipseLink ORM and OXM maps (both Project classes and Project deployment XML are supported) with the following naming convention:
- 1. identical case-sensitive Project names
or<xml version="1.0" encoding="UTF-8"?> <object-persistence version="Eclipse Persistence Services - @VERSION@ (Build @BUILD_NUMBER@)" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.eclipse.org/eclipselink/xsds/persistence" > <name>Example</name>import org.eclipse.persistence.sessions.Project; public class SomeORProject extends Project { public SomeORProject () { setName("Example"); ... } public class SomeOXProject extends Project { public SomeOXProject () { setName("Example"); ... }
- 2. identical case-sensitive aliases for Descriptors that are common between the projects
<class-mapping-descriptor xsi:type="eclipselink:relational-class-mapping-descriptor"> <class>some.package.SomeClass</class> <alias>SomeAlias</alias> ... <class-mapping-descriptor xsi:type="eclipselink:xml-class-mapping-descriptor"> <class>some.package.SomeClass</class> <alias>SomeAlias</alias>
Any existing named queries from the EclipseLink ORM map may be exposed as query operations for the EclipseLink DBWS service; additional Insert/Update/Delete/Query operations can be added. Pre-existing domain classes can be bundled with the service so that they are available at runtime.
Tables
Special case of auto-generation: provide only JDBC connection info + table name ==> a DBWS service with CRUD (Create/Read(findByPK,findAll)/Update/Delete) operations.
Stored Procedures
The user will be able to specify the use of Stored Procedure/Functions as the selection criteria for query operations. The design-time tooling will auto-generate (based on available database metadata) the required argument and return type information.
If the database metadata is not available, custom Java classes + manual editing of the service metadata will allow the desired Stored Procedure to be supported.
Advanced Types
A Stored Procedure may used advanced JDBC types - STRUCTs and VARRAYs - as arguments or return types, or even datatypes that have no JDBC equivalent (i.e. PL/SQL types). These use-cases are supported using custom Java classes + manual editing of the service's metadata.
The DBWSBuilder command-line tool does not (yet) support extracting the required database metadata for Advanced Types.
Dynamic Domain Model
Domain model classes are not required either in source form or .class files. At runtime, Eclipse will use bytecode weaving techniques to dynamically generate in-memory versions of compatible classes.
Public API
The Public API for DBWS is its metadata and the DBWSBuilder design-time tool.
DBWS metadata
Packaging required for deployment as a Web Service xxx.war
root of war file \---web-inf | | web.xml | +---classes | +---foo -- optional domain classes | | \---bar | | Address.class | | Employee.class | | PhoneNumber.class | | | +---META-INF | | eclipselink-dbws-or.xml | | eclipselink-dbws-ox.xml | | eclipselink-dbws-sessions.xml -- name can be overriden by <sessions-file> entry in eclipselink-dbws.xml | | eclipselink-dbws.xml | | | \---_dbws | DBWSProvider.class -- auto-generated JAX-WS 2.x Provider 'stub' | DBWSProvider.java | \---wsdl eclipselink-dbws-schema.xsd eclipselink-dbws.wsdl swaref.xsd -- optional to handle attachements
The files swaref.xsd and web.xml have names+content determined by their roles in web deployment and cannot be changed.
eclipselink-dbws.xml
- contains name-of-service
- contains name-of-sessions.xml - if not present, then eclipselink-dbws-sessions.xml will be used
- operation definitions
- schema for this file is: .../xsds/eclipselink-dbws_1.0.xsd
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> <sessions-file>example-dbws-sessions.xml</sessions-file> <query> <name>countEmployees <result> <type>xsd:int</type> <simple-xml-format> <simple-xml-format-tag>employee-info <simple-xml-tag>aggregate-info </simple-xml-format> </result> <sql><![CDATA[select count(*) from EMP]]></sql> </query> <query> <name>findAllEmployees <result isCollection="true"> <type>empType</type> </result> <sql><![CDATA[select * from EMP]]></sql> </query> </dbws>
eclipselink-dbws_1.0.xsd
<?xml version="1.0" encoding="utf-8"?> <xsd:schema version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:complexType name="simple-xml-format-type"> <xsd:sequence> <xsd:element minOccurs="0" name="simple-xml-format-tag" type="xsd:string" /> <xsd:element minOccurs="0" name="simple-xml-tag" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="procedure-argument-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:element name="parameterName" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="out-procedure-argument-type"> <xsd:complexContent mixed="false"> <xsd:extension base="procedure-argument-type"> <xsd:sequence> <xsd:element minOccurs="0" name="type" type="xsd:QName" /> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="xql-query-type"> <xsd:sequence> <xsd:element name="text" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="named-query-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:element name="descriptor" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="stored-procedure-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="in-argument" type="procedure-argument-type" /> </xsd:sequence> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="inout-argument" type="out-procedure-argument-type" /> </xsd:sequence> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="out-argument" type="out-procedure-argument-type" /> </xsd:sequence> </xsd:sequence> </xsd:complexType> <xsd:complexType name="attachment-type"> <xsd:sequence> <xsd:element name="mime-type" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="result-type"> <xsd:sequence> <xsd:element minOccurs="0" name="type" type="xsd:QName" /> <xsd:element minOccurs="0" name="attachment" type="attachment-type" /> <xsd:element minOccurs="0" name="simple-xml-format" type="simple-xml-format-type" /> </xsd:sequence> <xsd:attribute name="isCollection" type="xsd:boolean" use="optional" /> </xsd:complexType> <xsd:complexType name="parameter-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:element name="type" type="xsd:QName" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="query-operation"> <xsd:complexContent mixed="false"> <xsd:extension base="operation-with-parameters-type"> <xsd:sequence> <xsd:element minOccurs="0" name="result" type="result-type" /> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:choice> <xsd:element name="jpql" type="xql-query-type" /> <xsd:element name="named-query" type="named-query-type" /> <xsd:element name="sql" type="xql-query-type" /> <xsd:element name="stored-procedure" type="stored-procedure-type" /> <xsd:element name="stored-function" type="stored-procedure-type" /> </xsd:choice> </xsd:sequence> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="operation-with-parameters-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="parameter" type="parameter-type" /> </xsd:sequence> </xsd:sequence> </xsd:complexType> <xsd:complexType name="dbws-type"> <xsd:annotation> <xsd:documentation><![CDATA[ This is the XML Schema for EclipseLink Database WebService (DBWS) model. ]]></xsd:documentation> </xsd:annotation> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:element minOccurs="0" name="sessions-file" type="xsd:string" /> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:choice> <xsd:element name="insert" type="operation-with-parameters-type" /> <xsd:element name="query" type="query-operation" /> <xsd:element name="update" type="operation-with-parameters-type" /> <xsd:element name="delete" type="operation-with-parameters-type" /> </xsd:choice> </xsd:sequence> </xsd:sequence> </xsd:complexType> <xsd:element name="dbws" type="dbws-type" /> </xsd:schema>
eclipselink-dbws-sessions.xml
- contains references to the EclipseLink ORM and OXM maps (either Java classes or deployment XML)
- supports all other features of EclipseLink sessions.xml file: platform declaration, logging, login/datasource info, session customization, etc.
- name of ORM map: eclipselink-dbws-or.xml
- name of OXM map: eclipselink-dbws-ox.xml
- name of ORM session: name-of-service-dbws-or-session
- name of OXM session: name-of-service-dbws-ox-session
eclipselink-dbws-schema.xsd
- contains XML type definitions used by operation arguments and return types
eclipselink-dbws.wsdl
- required for deployment as a Web Service
- contains equivalent entries for each operation for the specified EclipseLink DBWS service
SXF (Simple XML Format)
Commonly used when the persistent entities returned by a query operation have no structure:
- resultSet from custom SQL SELECT statement
- results from a Stored Procedure/Function, updated-rows count from Update operation
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" > <xsd:complexType name="sxfType"> <xsd:sequence> <xsd:any minOccurs="0"/> </xsd:sequence> </xsd:complexType> <xsd:element name="simple-xml-format" type="sxfType"/> </xsd:schema>
The EclipseLink DBWS runtime will produce documents that are simple and are 'human-readable'; however, these documents are 'dumb' as they cannot be validated against any schema:
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 <xml> can be customized:
<?xml version = '1.0' encoding = 'UTF-8'?> <employee-info> <aggregate-info> <count>14</count> <max-salary>3000</max-salary> </aggregate-info> </employee-info>
Auto-generated XML Schema Definition .xsd
An .xsd file is auto-generated by the design-time tooling, deriving 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:element name="emp" type="empType"/> </xsd:schema>
Database Metadata
The design-time tooling relies on database metadata pertaining to:
- tables: column name, type, precision/scale, nullable
- Stored Procedures: argument and return types, names
not yet supported - JDBC metadata for STRUCT's, VARRAY's, and PL/SQL records
Design-time Tool
The DBWS design-time tool is a Java application that processes the operations described in a DBWS builder .xml file to produce the requisite files (described previously).
prompt> java -cp eclipselink.jar:eclipselink-dbwsutil.jar:your_favourite_jdbc_driver.jar org.eclipse.persistence.tools.dbws.DBWSBuilder -builderFile {path_to_dbws_builder.xml_file} -packageAs {how_to_package_output} -stageDir {path_to_staging_directory}
<?xml version="1.0" encoding="UTF-8"?> <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <properties> <property name="projectName">test</property> <property name="driver">oracle.jdbc.OracleDriver</property> <property name="password">tiger</property> <property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property> <property name="username">scott</property> </properties> <table catalogPattern="%" schemaPattern="SCOTT" tableNamePattern="XR_EMP"> <procedure returnType="dfdf" catalogPattern="SOME_PKG" schemaPattern="SCOTT" procedurePattern="GetEmployeeByEMPNO_DEPTNO"/> <sql name="findXREmpByName" isCollection="true" returnType="xr_empType"> <text> <![CDATA[select * from XR_EMP where ENAME like ?]]> </text> <binding name="ENAME" type="xsd:string"/> </sql> </table> <sql name="employeeInfo" simpleXMLFormatTag="employee-info" xmlTag="aggregate-counts" > <text> <![CDATA[select count(*) as "COUNT", max(SAL) as "MAX-Salary" from EMP]]> </text> </sql> </dbws-builder>
Properties
Name | Description | Required |
---|---|---|
projectName | the name of the EclipseLink DBWS service | Yes |
username | username | Yes |
password | Database password | Yes |
url | Database connection url | Yes |
driver | Class name of the jdbc driver | Yes |
contextRoot | the Web Services Provider servlet requires a <url-pattern> for its <servlet-mapping> element in the web.xml file | No; default is / + projectName |
dataSource | JNDI Datasource location to be inserted in DBWS sessions.xml file | No |
sessionsFileName | name of EclipseLink sessions.xml file to add to DBWS service .war file | No; default is eclipselink-dbws-sessions.xml |
platformClassname | EclipseLink database platform classname | No; default is org.eclipse.persistence.platform.database.MySQLPlatform |
orSessionCustomizerClassName | eclipse.persistence.config.SessionCustomizer classname to add to DBWS service sessions.xml file | No |
oxSessionCustomizerClassName | eclipse.persistence.config.SessionCustomizer classname to add to DBWS service sessions.xml file | No |
wsdlLocationURI | URI of this DBWS service's WSDL (used by Web Service tools to generate client code) | No; default is http://localhost:7001/projectName |
logLevel | EclipseLink logging level to be inserted in DBWS sessions.xml file | No; default is INFO |
targetNamespace | URI of targetNamespace to be inserted in DBWS schema | No; default is urn: + projectName |
Builder operations common attributes:
Name | Description | Required |
---|---|---|
name | name of operation | |
isCollection | false | the operation returns more than a single row |
isSimpleXMLFormat | false | the operation returns rows formatted as Simple XML Format elements |
simpleXMLFormatTag | <simple-xml-format> | name of root-level Simple XML Format element-tag |
xmlTag | <simple-xml> | name of grouping XML element-tag for rows |
binaryAttachment | false | the operation returns binary data as a SOAP attachment |
returnType | (optional) | if the operation's returnType cannot be deduced from database metadata, this attribute allows the user to specify the schema returnType |
<sql> operation The SQL text is a CDATA text element.
Nested Elements binding Binds type information to JDBC argument markers in the SQL text.
<procedure> operation
Attribute | Description |
---|---|
catalogPattern | pattern of matching catalogs (SQL-92 '%' wild-card supported) |
schemaPattern | pattern of matching schemas (SQL-92 '%' wild-card supported) |
procedurePattern | pattern of matching stored procedures(SQL-92 '%' wild-card supported) |
Attribute | Description |
---|---|
catalogPattern | pattern of matching catalogs (SQL-92 '%' wild-card supported) |
schemaPattern | pattern of matching schemas (SQL-92 '%' wild-card supported) |
tableNamePattern | pattern of matching tables (SQL-92 '%' wild-card supported) |
Nested Elements A
Document History
Date | Author | Version Description & Notes |
---|---|---|
080821 | Mike Norman | 1.0 (brought over from TopLink FS 14737 wiki document) |
Overview
The goal of DBWS is to enable simple and efficient access to relational database artifacts via a Web Service. DBWS extends EclipseLink's core capabilities while leveraging existing components (ORM, OXM).
EclipseLink DBWS has two parts: a design-time tooling component 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 a Web Service client.
An 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
- Stored Procedures
- TopLink Expressions
- JP-QL
The XML documents used by operations conform to an XML Schema Definition .xsd document auto-generated by the design-time tooling. Alternatively, if no .xsd is available, a pre-defined simple XML format (SXF) can be used.
Concepts
XML-to-Relational
A flexible component that maps between a database's relational structure(s) and XML's hierarchical structure{excerpt}. The use of EclipseLink's ORM and OXM features provides the basis for a powerful bridge between the two. To date, the only concrete realization of an XRM bridge is EclipseLink DBWS.
Requirements
The requirements of this feature are focused around the simple and efficient access to relational database artifact(s) via a Web Service. The use of EclipseLink ORM provides cross-database support and caching for performance; the use of EclipseLink OXM provides XML mapping flexibility. The goal is to simply realize a Web Service while allowing expert users to use advanced EclipseLink features.
Configuration
The metadata for an DBWS service is contained in an easy-to-read service descriptor XML file. The internal configuration requirements are minimal and omitted fields have simple defaults, allowing for both auto-generation by tools or manual editing. Additional EclipseLink metadata - ORM and OXM maps, customizations - will be handled using existing EclipseLink sessions.xml capabilities.
XML Schema Definition (.xsd)
A DBWS service requires an XML Schema Definition .xsd file 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.
SXF uses information only available at the time of query execution to build the XML element-tag names; thus, these XML documents cannot be validated against any schema.
Auto-generation of a DBWS service
The design-time tooling will auto-generate a DBWS service, creating the service descriptor and all required deployment artifacts (see section tbd for more details).
Use of pre-existing EclipseLink ORM and OXM maps
A DBWS service may be constructed using pre-existing EclipseLink ORM and OXM maps (both Project classes and Project deployment XML are supported) with the following naming convention:
- 1. identical case-sensitive Project names
or<xml version="1.0" encoding="UTF-8"?> <object-persistence version="Eclipse Persistence Services - @VERSION@ (Build @BUILD_NUMBER@)" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.eclipse.org/eclipselink/xsds/persistence" > <name>Example</name>import org.eclipse.persistence.sessions.Project; public class SomeORProject extends Project { public SomeORProject () { setName("Example"); ... } public class SomeOXProject extends Project { public SomeOXProject () { setName("Example"); ... }
- 2. identical case-sensitive aliases for Descriptors that are common between the projects
<class-mapping-descriptor xsi:type="eclipselink:relational-class-mapping-descriptor"> <class>some.package.SomeClass</class> <alias>SomeAlias</alias> ... <class-mapping-descriptor xsi:type="eclipselink:xml-class-mapping-descriptor"> <class>some.package.SomeClass</class> <alias>SomeAlias</alias>
Any existing named queries from the EclipseLink ORM map may be exposed as query operations for the EclipseLink DBWS service; additional Insert/Update/Delete/Query operations can be added. Pre-existing domain classes can be bundled with the service so that they are available at runtime.
Tables
Special case of auto-generation: provide only JDBC connection info + table name ==> a DBWS service with CRUD (Create/Read(findByPK,findAll)/Update/Delete) operations.
Stored Procedures
The user will be able to specify the use of Stored Procedure/Functions as the selection criteria for query operations. The design-time tooling will auto-generate (based on available database metadata) the required argument and return type information.
If the database metadata is not available, custom Java classes + manual editing of the service metadata will allow the desired Stored Procedure to be supported.
Advanced Types
A Stored Procedure may used advanced JDBC types - STRUCTs and VARRAYs - as arguments or return types, or even datatypes that have no JDBC equivalent (i.e. PL/SQL types). These use-cases are supported using custom Java classes + manual editing of the service's metadata.
The DBWSBuilder command-line tool does not (yet) support extracting the required database metadata for Advanced Types.
Dynamic Domain Model
Domain model classes are not required either in source form or .class files. At runtime, Eclipse will use bytecode weaving techniques to dynamically generate in-memory versions of compatible classes.
Public API
The Public API for DBWS is its metadata and the DBWSBuilder design-time tool.
DBWS metadata
Packaging required for deployment as a Web Service xxx.war
root of war file \---web-inf | | web.xml | +---classes | +---foo -- optional domain classes | | \---bar | | Address.class | | Employee.class | | PhoneNumber.class | | | +---META-INF | | eclipselink-dbws-or.xml | | eclipselink-dbws-ox.xml | | eclipselink-dbws-sessions.xml -- name can be overriden by <sessions-file> entry in eclipselink-dbws.xml | | eclipselink-dbws.xml | | | \---_dbws | DBWSProvider.class -- auto-generated JAX-WS 2.x Provider 'stub' | DBWSProvider.java | \---wsdl eclipselink-dbws-schema.xsd eclipselink-dbws.wsdl swaref.xsd -- optional to handle attachements
The files swaref.xsd and web.xml have names+content determined by their roles in web deployment and cannot be changed.
eclipselink-dbws.xml
- contains name-of-service
- contains name-of-sessions.xml - if not present, then eclipselink-dbws-sessions.xml will be used
- operation definitions
- schema for this file is: .../xsds/eclipselink-dbws_1.0.xsd
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> <sessions-file>example-dbws-sessions.xml</sessions-file> <query> <name>countEmployees <result> <type>xsd:int</type> <simple-xml-format> <simple-xml-format-tag>employee-info <simple-xml-tag>aggregate-info </simple-xml-format> </result> <sql><![CDATA[select count(*) from EMP]]></sql> </query> <query> <name>findAllEmployees <result isCollection="true"> <type>empType</type> </result> <sql><![CDATA[select * from EMP]]></sql> </query> </dbws>
eclipselink-dbws_1.0.xsd
<?xml version="1.0" encoding="utf-8"?> <xsd:schema version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <xsd:complexType name="simple-xml-format-type"> <xsd:sequence> <xsd:element minOccurs="0" name="simple-xml-format-tag" type="xsd:string" /> <xsd:element minOccurs="0" name="simple-xml-tag" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="procedure-argument-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:element name="parameterName" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="out-procedure-argument-type"> <xsd:complexContent mixed="false"> <xsd:extension base="procedure-argument-type"> <xsd:sequence> <xsd:element minOccurs="0" name="type" type="xsd:QName" /> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="xql-query-type"> <xsd:sequence> <xsd:element name="text" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="named-query-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:element name="descriptor" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="stored-procedure-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="in-argument" type="procedure-argument-type" /> </xsd:sequence> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="inout-argument" type="out-procedure-argument-type" /> </xsd:sequence> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="out-argument" type="out-procedure-argument-type" /> </xsd:sequence> </xsd:sequence> </xsd:complexType> <xsd:complexType name="attachment-type"> <xsd:sequence> <xsd:element name="mime-type" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="result-type"> <xsd:sequence> <xsd:element minOccurs="0" name="type" type="xsd:QName" /> <xsd:element minOccurs="0" name="attachment" type="attachment-type" /> <xsd:element minOccurs="0" name="simple-xml-format" type="simple-xml-format-type" /> </xsd:sequence> <xsd:attribute name="isCollection" type="xsd:boolean" use="optional" /> </xsd:complexType> <xsd:complexType name="parameter-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:element name="type" type="xsd:QName" /> </xsd:sequence> </xsd:complexType> <xsd:complexType name="query-operation"> <xsd:complexContent mixed="false"> <xsd:extension base="operation-with-parameters-type"> <xsd:sequence> <xsd:element minOccurs="0" name="result" type="result-type" /> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:choice> <xsd:element name="jpql" type="xql-query-type" /> <xsd:element name="named-query" type="named-query-type" /> <xsd:element name="sql" type="xql-query-type" /> <xsd:element name="stored-procedure" type="stored-procedure-type" /> <xsd:element name="stored-function" type="stored-procedure-type" /> </xsd:choice> </xsd:sequence> </xsd:sequence> </xsd:extension> </xsd:complexContent> </xsd:complexType> <xsd:complexType name="operation-with-parameters-type"> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:element name="parameter" type="parameter-type" /> </xsd:sequence> </xsd:sequence> </xsd:complexType> <xsd:complexType name="dbws-type"> <xsd:annotation> <xsd:documentation><![CDATA[ This is the XML Schema for EclipseLink Database WebService (DBWS) model. ]]></xsd:documentation> </xsd:annotation> <xsd:sequence> <xsd:element name="name" type="xsd:string" /> <xsd:element minOccurs="0" name="sessions-file" type="xsd:string" /> <xsd:sequence minOccurs="0" maxOccurs="unbounded"> <xsd:choice> <xsd:element name="insert" type="operation-with-parameters-type" /> <xsd:element name="query" type="query-operation" /> <xsd:element name="update" type="operation-with-parameters-type" /> <xsd:element name="delete" type="operation-with-parameters-type" /> </xsd:choice> </xsd:sequence> </xsd:sequence> </xsd:complexType> <xsd:element name="dbws" type="dbws-type" /> </xsd:schema>
eclipselink-dbws-sessions.xml
- contains references to the EclipseLink ORM and OXM maps (either Java classes or deployment XML)
- supports all other features of EclipseLink sessions.xml file: platform declaration, logging, login/datasource info, session customization, etc.
- name of ORM map: eclipselink-dbws-or.xml
- name of OXM map: eclipselink-dbws-ox.xml
- name of ORM session: name-of-service-dbws-or-session
- name of OXM session: name-of-service-dbws-ox-session
eclipselink-dbws-schema.xsd
- contains XML type definitions used by operation arguments and return types
eclipselink-dbws.wsdl
- required for deployment as a Web Service
- contains equivalent entries for each operation for the specified EclipseLink DBWS service
SXF (Simple XML Format)
Commonly used when the persistent entities returned by a query operation have no structure:
- resultSet from custom SQL SELECT statement
- results from a Stored Procedure/Function, updated-rows count from Update operation
<?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" > <xsd:complexType name="sxfType"> <xsd:sequence> <xsd:any minOccurs="0"/> </xsd:sequence> </xsd:complexType> <xsd:element name="simple-xml-format" type="sxfType"/> </xsd:schema>
The EclipseLink DBWS runtime will produce documents that are simple and are 'human-readable'; however, these documents are 'dumb' as they cannot be validated against any schema:
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 <xml> can be customized:
<?xml version = '1.0' encoding = 'UTF-8'?> <employee-info> <aggregate-info> <count>14</count> <max-salary>3000</max-salary> </aggregate-info> </employee-info>
Auto-generated XML Schema Definition .xsd
An .xsd file is auto-generated by the design-time tooling, deriving 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:element name="emp" type="empType"/> </xsd:schema>
Database Metadata
The design-time tooling relies on database metadata pertaining to:
- tables: column name, type, precision/scale, nullable
- Stored Procedures: argument and return types, names
not yet supported - JDBC metadata for STRUCT's, VARRAY's, and PL/SQL records
Design-time Tool
The DBWS design-time tool is a Java application that processes the operations described in a DBWS builder .xml file to produce the requisite files (described previously).
prompt> java -cp eclipselink.jar:eclipselink-dbwsutil.jar:your_favourite_jdbc_driver.jar org.eclipse.persistence.tools.dbws.DBWSBuilder -builderFile {path_to_dbws_builder.xml_file} -packageAs {how_to_package_output} -stageDir {path_to_staging_directory}
<?xml version="1.0" encoding="UTF-8"?> <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <properties> <property name="projectName">test</property> <property name="driver">oracle.jdbc.OracleDriver</property> <property name="password">tiger</property> <property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property> <property name="username">scott</property> </properties> <table catalogPattern="%" schemaPattern="SCOTT" tableNamePattern="XR_EMP"> <procedure returnType="dfdf" catalogPattern="SOME_PKG" schemaPattern="SCOTT" procedurePattern="GetEmployeeByEMPNO_DEPTNO"/> <sql name="findXREmpByName" isCollection="true" returnType="xr_empType"> <text> <![CDATA[select * from XR_EMP where ENAME like ?]]> </text> <binding name="ENAME" type="xsd:string"/> </sql> </table> <sql name="employeeInfo" simpleXMLFormatTag="employee-info" xmlTag="aggregate-counts" > <text> <![CDATA[select count(*) as "COUNT", max(SAL) as "MAX-Salary" from EMP]]> </text> </sql> </dbws-builder>
Properties
Name | Description | Required |
---|---|---|
projectName | the name of the EclipseLink DBWS service | Yes |
username | username | Yes |
password | Database password | Yes |
url | Database connection url | Yes |
driver | Class name of the jdbc driver | Yes |
contextRoot | the Web Services Provider servlet requires a <url-pattern> for its <servlet-mapping> element in the web.xml file | No; default is / + projectName |
dataSource | JNDI Datasource location to be inserted in DBWS sessions.xml file | No |
sessionsFileName | name of EclipseLink sessions.xml file to add to DBWS service .war file | No; default is eclipselink-dbws-sessions.xml |
platformClassname | EclipseLink database platform classname | No; default is org.eclipse.persistence.platform.database.MySQLPlatform |
orSessionCustomizerClassName | eclipse.persistence.config.SessionCustomizer classname to add to DBWS service sessions.xml file | No |
oxSessionCustomizerClassName | eclipse.persistence.config.SessionCustomizer classname to add to DBWS service sessions.xml file | No |
wsdlLocationURI | URI of this DBWS service's WSDL (used by Web Service tools to generate client code) | No; default is http://localhost:7001/projectName |
logLevel | EclipseLink logging level to be inserted in DBWS sessions.xml file | No; default is INFO |
targetNamespace | URI of targetNamespace to be inserted in DBWS schema | No; default is urn: + projectName |
Builder operations common attributes:
Name | Description | Required |
---|---|---|
name | name of operation | |
isCollection | false | the operation returns more than a single row |
isSimpleXMLFormat | false | the operation returns rows formatted as Simple XML Format elements |
simpleXMLFormatTag | <simple-xml-format> | name of root-level Simple XML Format element-tag |
xmlTag | <simple-xml> | name of grouping XML element-tag for rows |
binaryAttachment | false | the operation returns binary data as a SOAP attachment |
returnType | (optional) | if the operation's returnType cannot be deduced from database metadata, this attribute allows the user to specify the schema returnType |
<sql> operation The SQL text is a CDATA text element.
Nested Elements binding Binds type information to JDBC argument markers in the SQL text.
<procedure> operation
Attribute | Description |
---|---|
catalogPattern | pattern of matching catalogs (SQL-92 '%' wild-card supported) |
schemaPattern | pattern of matching schemas (SQL-92 '%' wild-card supported) |
procedurePattern | pattern of matching stored procedures(SQL-92 '%' wild-card supported) |
Issue # | Owner | Description / Notes |
---|---|---|