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

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:

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

<?xmlversion="1.0"encoding="UTF-8"?><dbws-builderxmlns:xsd="http://www.w3.org/2001/XMLSchema"><properties><propertyname="projectName">test</property><propertyname="driver">oracle.jdbc.OracleDriver</property><propertyname="password">tiger</property><propertyname="url">jdbc:oracle:thin:@localhost:1521:ORCL</property><propertyname="username">scott</property></properties><tablecatalogPattern="%"schemaPattern="SCOTT"tableNamePattern="XR_EMP"><procedurereturnType="dfdf"catalogPattern="SOME_PKG"schemaPattern="SCOTT"procedurePattern="GetEmployeeByEMPNO_DEPTNO"/><sqlname="findXREmpByName"isCollection="true"returnType="xr_empType"><text><![CDATA[select * from XR_EMP where ENAME like ?]]></text><bindingname="ENAME"type="xsd:string"/></sql></table><sqlname="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

Nested Elements
A <table> 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 Simple XML Format-ed rows).

Design-time Utility API

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 (Create/Read(findByPrimaryKey;readAll)/Update/Delete) 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.

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.

Custom SQL

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