Difference between revisions of "EclipseLink/Development/DBWS"

Revision as of 13:38, 22 August 2008

EclipseLink Database Web Services

Document History

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:

1. Insert - inserts into the database persistent entities described by an XML document.
2. Update - updates database persistent entities described by an XML document.
3. Delete - removes from the database persistent entities described by an XML document.
4. 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

<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>

 or 

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.

<style type="text/css"> .source-xml {border: 1px solid #3c78b5;} }</style>

DBWS metadata

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>

Open Issues

This section lists the open issues that are still pending that must be decided prior to fully implementing this project's requirements.