|
|
| (82 intermediate revisions by 3 users not shown) |
| Line 1: |
Line 1: |
| − | <div style="margin:5px;float:right;border:1px solid #000000;padding:5px">__TOC__</div>
| + | __NOTOC__ |
| − | == EclipseLink Database Web Services == | + | == Welcome to the Development Home page for the <b>EclipseLink Database Web Services (DBWS)</b> component == |
| | + | This page displays information about the current state of DBWS development. |
| | + | {{:EclipseLink/Development/DBWS/RoadMap}} |
| | + | === Supported Use-Cases === |
| | + | * [[EclipseLink/Development/DBWS/JDBCUseCases|Supported Use-Cases for non-Oracle Platforms]] |
| | + | * [[EclipseLink/Development/DBWS/OracleUseCases|Supported Use-Cases for Oracle Platforms]] |
| | | | |
| − | == Document History == | + | === Features === |
| − | {|{{BMTableStyle}}
| + | Individual wiki pages for various DBWS features |
| − | |-{{BMTHStyle}} | + | * [[EclipseLink/Development/DBWS/NamingConventionTransformer|Custom Schema Naming with NamingConventionTransformer]] |
| − | ! Date
| + | ** [[EclipseLink/Development/DBWS/OptLock|Auto-detect Optimistic locking]] |
| − | ! Author
| + | * [[EclipseLink/Development/DBWS/AdvancedJDBCTypesThruJPub|Support advanced JDBC types]] |
| − | ! Version Description & Notes
| + | ** [[EclipseLink/Development/DBWS/ImprovedDataDictionaryQueries|Database Metadata Model classes]] |
| − | |- | + | * [[EclipseLink/Development/DBWS/DynamicPersistence|How DBWS uses Dynamic Persistence]] |
| − | | 080821 | + | * [[EclipseLink/Development/DBWS/PLSQLStoredFunctions|Support complex PL/SQL parameters (and return arg) for StoredFunctions]] |
| − | | Mike Norman | + | * [[EclipseLink/Development/DBWS/OSGi|Support DBWS in an OSGi environment]] |
| − | | 1.0 (brought over from TopLink FS 14737 wiki document) | + | |
| − | |} | + | |
| | | | |
| − | == Overview == | + | === [[EclipseLink/Development/Testing/DBWS|DBWS Testing]] === |
| − | 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. | + | === [[EclipseLink/Development/DBWS/FunctionalSpecification| Original DBWS Functional Specification and High-level Design documentation]] === |
| | | | |
| − | An DBWS service may be comprised of any number of '''operations''' of which there are 4 types:
| + | === [[EclipseLink/Development/DBWS/Oldstatuslogs| Old status logs]] === |
| − | # 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
| + | |
| − | #* EclipseLink 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="relational-class-mapping-descriptor">
| + | |
| − | <class>some.package.SomeClass</class>
| + | |
| − | <alias>SomeAlias</alias>
| + | |
| − | ...
| + | |
| − | <class-mapping-descriptor xsi:type="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 <code>DBWSBuilder</code> 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 JDBC 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;">
| + | |
| − | <code>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}</code>
| + | |
| − | </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
| + | |
| − | |-
| + | |
| − | | <b><tt>projectName</tt></b>
| + | |
| − | | the name of the EclipseLink DBWS service
| + | |
| − | | Yes
| + | |
| − | |-
| + | |
| − | | <b><tt>username</tt></b>
| + | |
| − | | username
| + | |
| − | | Yes
| + | |
| − | |-
| + | |
| − | | <b><tt>password</tt></b>
| + | |
| − | | Database password
| + | |
| − | | Yes
| + | |
| − | |-
| + | |
| − | | <b><tt>url</tt></b>
| + | |
| − | | Database connection url
| + | |
| − | | Yes
| + | |
| − | |-
| + | |
| − | | <b><tt>driver</tt></b>
| + | |
| − | | Class name of the jdbc driver
| + | |
| − | | Yes
| + | |
| − | |-
| + | |
| − | | <b><tt>contextRoot</tt></b>
| + | |
| − | | 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>
| + | |
| − | |-
| + | |
| − | | <b><tt>dataSource</tt></b>
| + | |
| − | | JNDI Datasource location to be inserted in DBWS <tt>sessions.xml</tt> file
| + | |
| − | | No
| + | |
| − | |-
| + | |
| − | | <b><tt>sessionsFileName</tt></b>
| + | |
| − | | 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>
| + | |
| − | |-
| + | |
| − | | <b><tt>platformClassname</tt></b>
| + | |
| − | | EclipseLink database platform classname
| + | |
| − | | No; default is <code>org.eclipse.persistence.platform.database.MySQLPlatform</code>
| + | |
| − | |-
| + | |
| − | | <b><tt>orSessionCustomizerClassName</tt></b>
| + | |
| − | | <code>eclipse.persistence.config.SessionCustomizer</code> classname to add to DBWS service <tt>sessions.xml</tt> file
| + | |
| − | | No
| + | |
| − | |-
| + | |
| − | | <b><tt>oxSessionCustomizerClassName</tt></b>
| + | |
| − | | <code>eclipse.persistence.config.SessionCustomizer</code> classname to add to DBWS service <tt>sessions.xml</tt> file
| + | |
| − | | No
| + | |
| − | |-
| + | |
| − | | <b><tt>wsdlLocationURI</tt></b>
| + | |
| − | | 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>
| + | |
| − | |-
| + | |
| − | | <b><tt>logLevel</tt></b>
| + | |
| − | | EclipseLink logging level to be inserted in DBWS <tt>sessions.xml</tt> file
| + | |
| − | | No; default is <tt>INFO</tt>
| + | |
| − | |-
| + | |
| − | | <b><tt>targetNamespace</tt></b>
| + | |
| − | | URI of targetNamespace to be inserted in DBWS schema
| + | |
| − | | No; default is <tt>urn: + projectName</tt>
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | <br/>
| + | |
| − | | + | |
| − | ==== 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
| + | |
| − | |-
| + | |
| − | | <b><tt>name</tt></b>
| + | |
| − | |
| + | |
| − | | name of operation
| + | |
| − | |-
| + | |
| − | | <b><tt>isCollection</tt></b>
| + | |
| − | | <tt>false</tt>
| + | |
| − | | the operation returns more than a single row
| + | |
| − | |-
| + | |
| − | | <b><tt>isSimpleXMLFormat</tt></b>
| + | |
| − | | <tt>false</tt>
| + | |
| − | | the operation returns rows formatted as Simple XML Format elements
| + | |
| − | |-
| + | |
| − | | <b><tt>simpleXMLFormatTag</tt></b>
| + | |
| − | | <tt><simple-xml-format></tt>
| + | |
| − | | name of root-level Simple XML Format element-tag
| + | |
| − | |-
| + | |
| − | | <b><tt>xmlTag</tt></b>
| + | |
| − | | <tt><simple-xml></tt>
| + | |
| − | | name of grouping XML element-tag for rows
| + | |
| − | |-
| + | |
| − | | <b><tt>binaryAttachment</tt></b>
| + | |
| − | | <tt>false</tt>
| + | |
| − | | the operation returns binary data as a SOAP attachment
| + | |
| − | |-
| + | |
| − | | <b><tt>returnType</tt></b>
| + | |
| − | | (optional)
| + | |
| − | | if the operation's returnType cannot be deduced from database metadata, this attribute allows the user to specify the schema returnType
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | <br/>
| + | |
| − | <tt><b><sql></b></tt> operation<br/>
| + | |
| − | The SQL <tt><text></tt> is a CDATA text element.
| + | |
| − | <br/>
| + | |
| − | <b>Nested Elements</b><br/>
| + | |
| − | <b><binding></b><br/>
| + | |
| − | Binds type information to JDBC argument markers in the SQL text.
| + | |
| − | {| 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
| + | |
| − | |-
| + | |
| − | | <b><tt>name</tt></b>
| + | |
| − | | name of bound variable
| + | |
| − | |-
| + | |
| − | | <b><tt>type</tt></b>
| + | |
| − | | XML Schema datatype
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | <br/>
| + | |
| − | <tt><b><procedure></b></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
| + | |
| − | |-
| + | |
| − | | <b><tt>catalogPattern</tt></b>
| + | |
| − | | pattern of matching catalogs (SQL-92 '%' wild-card supported)
| + | |
| − | |-
| + | |
| − | | <b><tt>schemaPattern</tt></b>
| + | |
| − | | pattern of matching schemas (SQL-92 '%' wild-card supported)
| + | |
| − | |-
| + | |
| − | | <b><tt>procedurePattern</tt></b>
| + | |
| − | | pattern of matching stored procedures(SQL-92 '%' wild-card supported)
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | <br/>
| + | |
| − | <tt><b><table></b></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
| + | |
| − | |-
| + | |
| − | | <b><tt>catalogPattern</tt></b>
| + | |
| − | | pattern of matching catalogs (SQL-92 '%' wild-card supported)
| + | |
| − | |-
| + | |
| − | | <b><tt>schemaPattern</tt></b>
| + | |
| − | | pattern of matching schemas (SQL-92 '%' wild-card supported)
| + | |
| − | |-
| + | |
| − | | <b><tt>tableNamePattern</tt></b>
| + | |
| − | | pattern of matching tables (SQL-92 '%' wild-card supported)
| + | |
| − | |-
| + | |
| − | |}
| + | |
| − | <br/>
| + | |
| − | <b>Nested Elements</b><br/>
| + | |
| − | A <tt><b><table></b></tt> operation can have nested <tt><b><sql></b></tt> or <tt><b><procedure></b></tt> operations associated with it; these operations can use the table's schema to return entities (usually <tt><b><sql></b></tt> or <tt><b><procedure></b></tt> operations only return Simple XML Format-ed rows).
| + | |
| − | | + | |
| − | <b>eclipselink-dbws-builder_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="operation-attrs">
| + | |
| − | <xsd:attribute name="name" type="xsd:string" />
| + | |
| − | <xsd:attribute name="simpleXMLFormatTag" type="xsd:string" />
| + | |
| − | <xsd:attribute name="xmlTag" type="xsd:string" />
| + | |
| − | <xsd:attribute name="isCollection" type="xsd:boolean" />
| + | |
| − | <xsd:attribute name="binaryAttachment" type="xsd:boolean" />
| + | |
| − | <xsd:attribute name="returnType" type="xsd:string" />
| + | |
| − | </xsd:complexType>
| + | |
| − | <xsd:complexType name="procedure-operation">
| + | |
| − | <xsd:simpleContent>
| + | |
| − | <xsd:extension base="operation-attrs">
| + | |
| − | <xsd:attribute name="catalogPattern" type="xsd:string" />
| + | |
| − | <xsd:attribute name="schemaPattern" type="xsd:string" />
| + | |
| − | <xsd:attribute name="procedurePattern" type="xsd:string" />
| + | |
| − | </xsd:extension>
| + | |
| − | </xsd:simpleContent>
| + | |
| − | </xsd:complexType>
| + | |
| − | <xsd:complexType name="sql-operation">
| + | |
| − | <xsd:complexContent mixed="false">
| + | |
| − | <xsd:extension base="operation-attrs">
| + | |
| − | <xsd:sequence>
| + | |
| − | <xsd:element name="text" type="xsd:string" />
| + | |
| − | </xsd:sequence>
| + | |
| − | </xsd:extension>
| + | |
| − | </xsd:complexContent>
| + | |
| − | </xsd:complexType>
| + | |
| − | <xsd:complexType name="table-operation">
| + | |
| − | <xsd:complexContent mixed="false">
| + | |
| − | <xsd:extension base="operation-attrs">
| + | |
| − | <xsd:sequence minOccurs="0" maxOccurs="unbounded">
| + | |
| − | <xsd:choice>
| + | |
| − | <xsd:element name="procedure" type="procedure-operation" />
| + | |
| − | <xsd:element name="sql" type="sql-operation" />
| + | |
| − | </xsd:choice>
| + | |
| − | </xsd:sequence>
| + | |
| − | <xsd:attribute name="catalogPattern" type="xsd:string" />
| + | |
| − | <xsd:attribute name="schemaPattern" type="xsd:string" />
| + | |
| − | <xsd:attribute name="tableNamePattern" type="xsd:string" />
| + | |
| − | </xsd:extension>
| + | |
| − | </xsd:complexContent>
| + | |
| − | </xsd:complexType>
| + | |
| − | <xsd:complexType name="builder-type">
| + | |
| − | <xsd:annotation>
| + | |
| − | <xsd:documentation><![CDATA[
| + | |
| − | This is the XML Schema for EclipseLink Database WebService (DBWS) Builder model.
| + | |
| − | ]]></xsd:documentation>
| + | |
| − | </xsd:annotation>
| + | |
| − | <xsd:sequence>
| + | |
| − | <xsd:element name="properties">
| + | |
| − | <xsd:complexType>
| + | |
| − | <xsd:sequence>
| + | |
| − | <xsd:element minOccurs="0" maxOccurs="unbounded" name="property">
| + | |
| − | <xsd:complexType>
| + | |
| − | <xsd:simpleContent>
| + | |
| − | <xsd:extension base="xsd:string">
| + | |
| − | <xsd:attribute name="name" type="xsd:string" />
| + | |
| − | </xsd:extension>
| + | |
| − | </xsd:simpleContent>
| + | |
| − | </xsd:complexType>
| + | |
| − | </xsd:element>
| + | |
| − | </xsd:sequence>
| + | |
| − | </xsd:complexType>
| + | |
| − | </xsd:element>
| + | |
| − | <xsd:sequence minOccurs="0" maxOccurs="unbounded">
| + | |
| − | <xsd:choice>
| + | |
| − | <xsd:element name="procedure" type="procedure-operation" />
| + | |
| − | <xsd:element name="sql" type="sql-operation" />
| + | |
| − | <xsd:element name="table" type="table-operation" />
| + | |
| − | </xsd:choice>
| + | |
| − | </xsd:sequence>
| + | |
| − | </xsd:sequence>
| + | |
| − | </xsd:complexType>
| + | |
| − | <xsd:element name="dbws-builder" type="builder-type" />
| + | |
| − | </xsd:schema>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | ==== Design-time Tool API ====
| + | |
| − | The class <b><code>org.eclipse.persistence.tools.dbws.DBWSBuilder</code></b> is public and can be populated programmatically through property setters (i.e. <b><code>setDriver()</code></b>, <b><code>setUrl()</code></b>) and adding table or procedure definitions via the public <b><code>addDbTable()</code></b> and <b><code>addDbStoredProcedure()</code></b> methods; SQL operations via <b><code>addSqlOperation()</code></b> (NB - before adding a table or procedure definition, it is recommended that the public <b><code>checkTables()</code></b> and <b><code>checkStoredProcedures()</code></b> methods be used to ensure that the definitions are supported). Once all the data and definitions have been set, the builder is invoked through the <b><code>build(...)</code></b> method:
| + | |
| − | | + | |
| − | <source lang="java">
| + | |
| − | public void build(OutputStream dbwsSchemaStream, OutputStream dbwsSessionsStream,
| + | |
| − | OutputStream dbwsServiceStream, OutputStream dbwsOrStream, OutputStream dbwsOxStream,
| + | |
| − | OutputStream indexHtmlStream, OutputStream swarefStream, OutputStream webXmlStream,
| + | |
| − | OutputStream platformWebservicesXmlStream, OutputStream wsdlStream, Logger logger)
| + | |
| − | throws IOException, WSDLException, SQLException, ClassNotFoundException
| + | |
| − | </source>
| + | |
| − | | + | |
| − | ==== Some Issues with JDBC metadata ====
| + | |
| − | The key to supporting multiple database platforms (Oracle, DB2, Sybase, MS SQLServer, etc.) lies in the ability to extract meta-data for Stored Procedures and Tables from the database. The standard JDBC meta-data APIs (available through the <b><code>java.sql.DatabaseMetaData</code></b> interface) unfortunately is not fully implemented across vendors, nor in a standard fashion.
| + | |
| − | For example, the simple act of getting the <b><i>names</i></b> of available databases is different across platforms: on Oracle the <b><code>getSchemas()</code></b> method is used while for DB2/Sybase/MS SQLServer the <b><code>getCatalogs()</code></b> method is used. Another example of cross-platform meta-data issues is the <b><code>getColumns</code></b> method: for PostgreSQL, the name of the table <u>must</u> be lower-case; for Oracle, it <u>must</u> be upper-case; others support mixed-case. [[http://www.sun.com/bigadmin/content/submitted/jdbc_drivers.html The following is a case-study that expands on these issues]].
| + | |
| − | | + | |
| − | <b>Oracle</b><br/>
| + | |
| − | * driver returns wrong value of column size (versions 9.2.0.6,10.0.1.4)<br/>When tables are created with NLS_LENGTH_SEMANTICS='CHAR', the method <code>ResultSet DatabaseMetaData.getColumns(....)</code> returns the maximum number of characters (for char/date types; for numeric/decimal types returns precision). In actual fact, the method returns the number of bytes, not the number of characters. This problem is solved by an updated version of <code>oracle.jdbc.driver.OracleDatabaseMetaData</code> available in version 10.2.0.2.0.
| + | |
| − | * <code>databaseMetaData.getColumns</code>
| + | |
| − | ** driver doesn't return INTEGER data type, instead it returns 3 ("NUMBER") with column precision of 22 and scale 0.
| + | |
| − | ** does not work for SYNONYMS unless the <code>setIncludeSynonyms(boolean)</code> method is used. Similar to <code>setRemarksReporting</code>, <code>getColumns</code> performs slowly if information about synonyms is to be included as it requires an expensive outer join. By default, the JDBC driver will not report information about table columns when you pass a synonym to <code>getColumns</code>. You can get synonym information by passing true to this method, and turn it off by passing false. You can also control this behavior by passing a property named "includeSynonyms" as "true" to <code>DriverManager.getConnection</code>.
| + | |
| − | * <code>databaseMetaData.getProcedureColumns</code> will not return the 'null' column for Stored Procedures that have no arguments, while the Oracle data dictionary view USER_PROCEDURES will (since 9.x).
| + | |
| − | * An exception is thrown when the size of an OUT parameter exceeds ~2000 characters.
| + | |
| − | ** a PL/SQL stored procedure with an OUT parameter of type VARCHAR2 with a NOCOPY hint (e.g. <code>param1 OUT NOCOPY VARCHAR2</code>).<br/> Workaround:<br/>
| + | |
| − | <source lang=java>
| + | |
| − | ...
| + | |
| − | // use Oracle-specific type
| + | |
| − | statement.registerOutParameter(i, oracle.jdbc.OracleTypes.VARCHAR);
| + | |
| − | </source>
| + | |
| − | * <code>databaseMetaData.getIndexInfo()</code> does not work for VIEWS. A SQLException with the following message is thrown: "ORA-01702: a view is not appropriate here: can't retrieve indexInfo"; other platforms just ignore.
| + | |
| − | | + | |
| − | <b>IBM AS/400 via JTOpen</b><br/>
| + | |
| − | * <code>databaseMetaData.getColumns</code>
| + | |
| − | ** the CHAR_OCTET_LENGTH and ORDINAL_POSITION columns of the result set are not supported in Toolbox versions prior to V5R1 (JTOpen 2.x).
| + | |
| − | ** possible workarounds:<br/>For CHAR_OCTET_LENGTH, which is supposed to indicate the maximum number of bytes in the column, use the value in the COLUMN_SIZE. Multiply this value by 2 if the column holds DBCS characters. For ORDINAL_POSITION, which is supposed to indicate the index of the column in a table, run a query for all columns in the table ("SELECT * FROM table where 1=0"), and then issue findColumn() on the result set to determine the column index from the column name.
| + | |
| − | * In the ResultSetMetaData object, the <code>getTableName()</code> and <code>getSchema()</code> methods are not supported in Toolbox versions prior to V5R2 (JTOpen 3.x).
| + | |
| − | ** In supported Toolbox versions, these methods work only if the "extended metadata" connection property has been set to True and only when the target server is at the V5R2 operating system or later. Because retrieving the additional information may incur a performance penalty, this property is set to False by default.
| + | |
| − | | + | |
| − | <b>ODBC-JDBC Bridge</b><br/>
| + | |
| − | * MS-ACCESS: <code>getPrimaryKeys</code> not supported
| + | |
| − | | + | |
| − | <b>Apache Derby (a.k.a. JavaDB)</b><br/>
| + | |
| − | * metadata for Stored Functions are only available with a JDBC 4 compliant driver (Oracle returns metadata for storedFunctions via <code>databaseMetaData.getProcedures()</code>)
| + | |
| − | | + | |
| − | == Use Cases ==
| + | |
| − | | + | |
| − | === Tables ===
| + | |
| − | At design-time, a table (or any artifact that can be treated de-facto as a table - view, synonym, materialized view/snapshot, etc.) is specified. All service metadata is auto-generated: XML Schema Definition (.xsd), service descriptor, EclipseLink OR/OX maps, WSDL, etc. The service exposes basic CRUD (<b><i><u>C</u></i>reate/<i><u>R</u></i>ead(findByPrimaryKey;readAll)/<i><u>U</u></i>pdate/<i><u>D</u></i>elete</b>) operations; the user may specify additional custom operations.
| + | |
| − | | + | |
| − | === Stored Procedures ===
| + | |
| − | Stored Procedure/Functions may form the selection criteria of query operations for a DBWS service whose returned data conforms to an XML schema. The design-time tooling will auto-generate (based on available database metadata) the service metadata as well as all other deployment artifacts necessary to deploy as an JAX-WS Web Service.
| + | |
| − | <blockquote style="padding:4px;border:1px solid black;">
| + | |
| − | Oracle: Stored Procedures can be specified as belonging to a package or at the 'root' level. Stored Procedures that are overloaded (the name is the same but the arguments differ) are also supported.
| + | |
| − | </blockquote>
| + | |
| − | | + | |
| − | === Custom SQL ===
| + | |
| − | SQL <tt>SELECT</tt> statements form the query operations for a DBWS service. JDBC argument markers (?) are supported. The data returned conforms to an XML schema or the SXF.
| + | |
| − | | + | |
| − | === Simple Use ===
| + | |
| − | * Goal: expose a table as a Web Service
| + | |
| − | ** use DBWSBuilder tool: specify <table> operation in dbws-builder.xml along with JDBC connection info, name of table
| + | |
| − | ** in addition to <b>CRUD</b> operations, optionally add nested <b><tt><sql></tt></b> or <b><tt><procedure></tt></b> operations
| + | |
| − | * Goal: expose a Stored Procedure as a Web Service
| + | |
| − | ** use DBWSBuilder tool: specify <b><tt><procedure></tt></b> operation in dbws-builder.xml along with JDBC connection info, name of Stored Procedure
| + | |
| − | * Goal: expose an Oracle Package as a Web Service
| + | |
| − | ** use DBWSBuilder tool: specify <b><tt><procedure></tt></b> operation in dbws-builder.xml along with JDBC connection info, name of Oracle Package as <b><tt>catalogPattern</tt></b> attribute
| + | |
| − | * Goal: change logging
| + | |
| − | ** use DBWSBuilder tool: set <b><tt><logLevel></tt></b> property in dbws-builder.xml
| + | |
| − | <source lang=xml>
| + | |
| − | <?xml version="1.0" encoding="UTF-8"?>
| + | |
| − | <dbws-builder xmlns:xsd="http://www.w3.org/2001/XMLSchema">
| + | |
| − | <properties>
| + | |
| − | <property name="logLevel">OFF</property>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | === Advanced Customizations ===
| + | |
| − | * Goal: change an auto-generated schema node from <element> to attribute (e.g. <name> becomes name="some value")
| + | |
| − | ** extract the eclipselink-dbws-schema.xsd from inside the <tt>.war</tt>; edit with an XML Schema tool to make appropriate change
| + | |
| − | ** extract the eclipselink-dbws-ox.xml from inside the <tt>.war</tt>; change
| + | |
| − | <source lang=xml>
| + | |
| − | <opm:field name="name/text()" xsi:type="node"/>
| + | |
| − | </source>
| + | |
| − | to
| + | |
| − | <source lang=xml>
| + | |
| − | <opm:field name="@name" xsi:type="node"/>
| + | |
| − | </source>
| + | |
| − | | + | |
| − | === Very Advanced Customizations ===
| + | |
| − | * Goal: handle multiple tables
| + | |
| − | ** use an XML Schema tool to generate an eclipselink-dbws-schema.xsd for the tables in question
| + | |
| − | ** using EclipseLink Mapping Workbench, create 2 Projects: one for the ORM side, the other for the OXM (Note: technical requirements w.r.t. naming, aliases, etc).
| + | |
| − | *** if the generated Projects do not save-to-disk as XML, save as Java source, compile and edit the eclipselink-dbws-sessions.xml, setting the <primary-project xsi:type="class"> entries
| + | |
| − | *** use the Mapping Workbench's Query Editor to create complex Named queries; edit the eclipselink-dbws.xml file, adding in the named-query operations:
| + | |
| − | <source lang=xml>
| + | |
| − | <query>
| + | |
| − | <name>name</name>
| + | |
| − | <parameter>
| + | |
| − | <name>something</name>
| + | |
| − | <type>xsd:int</type>
| + | |
| − | </parameter>
| + | |
| − | <parameter>
| + | |
| − | <name>orOther</name>
| + | |
| − | <type>xsd:String</type>
| + | |
| − | </parameter>
| + | |
| − | <result>
| + | |
| − | <type>someType</bar>
| + | |
| − | </result>
| + | |
| − | <named-query>
| + | |
| − | <name>name_of_Named_Query</name>
| + | |
| − | <descriptor>someDescriptorAlias</descriptor>
| + | |
| − | </named-query>
| + | |
| − | </query>
| + | |
| − | </source>
| + | |
| − | * Goal: handle advanced JDBC types
| + | |
| − | ** queries that used STRUCT/VARRAY's do not save-to-disk as XML; edit the eclipselink-dbws-sessions.xml file, adding a <session-customizer-class> entry; the full range of EclipseLink features and APIs are available (advanced query settings; use of ObjectRelationalDescriptor subclass, etc.)
| + | |
| − | | + | |
| − | == Open Issues ==
| + | |
| − | | + | |
| − | This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.
| + | |
| − | | + | |
| − | {|{{BMTableStyle}}
| + | |
| − | |-{{BMTHStyle}}
| + | |
| − | ! Issue #
| + | |
| − | ! Owner
| + | |
| − | ! Description / Notes
| + | |
| − | |-
| + | |
| − | | 1
| + | |
| − | | MWN
| + | |
| − | | Binary attachment handling finds first blob/image column, converts to base64; what about other columns, types?
| + | |
| − | |}
| + | |
The focus is on providing capabilities based upon the 3 types of database artifacts:
