Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "EclipseLink/Development/DBWS"

(→‎DBWS metadata)
(→‎Features)
 
(191 intermediate revisions by the same user 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
+
−
#* 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>
+
−
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>
+
−
<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>&nbsp;or&nbsp;
+
−
<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>
+
−
<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>
+
−
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>
+
−
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.
+
−
 
+
−
<style type="text/css">
+
−
.source-xml {border: 1px solid #3c78b5;}
+
−
}</style>
+
−
 
+
−
== DBWS metadata ==
+
−
<b><font size="+1">eclipselink-dbws.xml</font size="-1"></b>
+
−
*  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: <tt>.../xsds/eclipselink-dbws_1.0.xsd</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: name-of-service-dbws-or-session
+
−
* name of OXM session: name-of-service-dbws-ox-session
+
−
 
+
−
<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
+
−
 
+
−
== 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
+
−
|-
+
−
|
+
−
|
+
−
|
+
−
|}
+

Latest revision as of 13:48, 11 August 2010

Welcome to the Development Home page for the EclipseLink Database Web Services (DBWS) component

This page displays information about the current state of DBWS development.

DBWS Road Map

Future

NB - some items not currently targetted to a specific release

  • bug 362585 - DBWS: Oracle DDL Parser should resolve types from other schemas
  • bug 406017 - DBWS: Should have option to packageAs EAR
  • bug 375558 - DBWS: Builder XML doesn't allow to specify a resource instead of a JNDI datasource
  • bug 300398 - Add "get(String, Class)" method to DynamicEntity
  • AQ Web Services (bug 322950)
    • Investigate how to support; add usecase to DBWS section of User Guide
    • Highlighted as lower priority
  • Development tooling support through IDEs

2.6

  • XMLEntityMappings generation from DDLParser meta-model
  • DBWSBuilder should bootstrap from XMLEntityMappings
  • Application Server Testing (note that the server tests are also run in 2.5)
    • The application server tests currently run are relatively simple. More complex tests should be added, such as:
      1. Advanced Oracle types, i.e. ObjectType, VArray, etc.
      2. PL/SQL Record & Collection
      3. Ref Cursor
      4.  %TYPE, %ROWTYPE
    • We currently test against the following application servers:
      1. WebLogic
      2. GlassFish
      3. JBoss
      4. WebSphere
    • The following server tests are run nightly:
      1. SimpleTable
      2. SimpleSQL
      3. SimpleSP
      4. SimplePLSQL
      5. Mtom
      6. InlineBinary
      7. AttachedBinary
      8. LegacySimpleTable (tests legacy deployment XML; not run against JBoss)

2.5

2.4

2.3

  • Build environment
    • Plan to include DBWS feature in SDK bundle made available in p2 repository

Completed in EclipseLink2.3

  • EclipseLink should support complex PL/SQL arguments for Stored Functions
  • bug 332221 Support Stored Procs returning multiple rowsets.
    • Brand new core capability. Only for those platforms (Sybase, MySQL) that support it
  • DBWS Server tests
    • expand existing WLS server tests to run on WAS, JBoss and Glassfish
    • TBD: expand test coverage - what additional tests are useful?
  • bug 344341 Support complex PL/SQL arguments for Stored Functions
  • bug 303333 Handle overloaded Stored Procedure/Functions as WSDL operations

2.2

2.1

  • accommodate internal changes for AttributeChangeTracking
  • support DBWSBuilder-generated JAX-WS Provider on JRockit
  • stop DBWSBuilder from truncating GROUP BY/ORDER BY clauses
  • DBWSBuilder supports Eclipse WTP Dynamic Web Project structure

2.0.1

  • align DBWS internal implementation with new Dynamic Persistence features
  • DBWSBuilder utility auto-detect Optimistic Lock field
  • fix issue with JDBC metadata and overloaded Stored Functions
  • Support MTOM attachments
  • fix Web service faults: contain better server-side root cause information

1.2

  • For OraclePlatform, support advanced PL/SQL datatypes (records, collections, mixture of the two) as arguments to Stored Procedures
    • need compatible JDBC 'shadow' types to align with PL/SQL types
  • For OraclePlatform, support complex JDBC datatypes (objects, varrays, mixture of the two) as arguments to Stored Procedures
  • Fix WSDL inline-schema to support above complex args
  • Add support for SOAP 1.2
  • Fix Delete operation (part of table-based CRUD): use only PK fields, not whole instance
  • Use nillable="true" to represent database null
  • DBWSBuilder utility to produce DDL for the compatible JDBC shadow types

1.1

  • Deploy to JAX-WS 2.n complaint server (WebLogic 10)
  • For OraclePlatform, support simple PL/SQL datatypes (PLSINTEGER, BOOLEAN, etc) as arguments to Stored Procedures
  • Improve server-side exception handling

1.0

The focus is on providing capabilities based upon the 3 types of database artifacts:

  1. table: CRUD lifecycle
  2. Stored Procedure: specialized queries
  3. Result set: returned from SQL SELECT queries

Supported Use-Cases

Features

Individual wiki pages for various DBWS features

DBWS Testing

Original DBWS Functional Specification and High-level Design documentation

Old status logs

Retrieved from "https://wiki.eclipse.org/index.php?title=EclipseLink/Development/DBWS&oldid=214746"

This page was last modified 13:48, 11 August 2010 by Eclipsepedia anonymous user Unnamed Poltroon.

Back to the top