Difference between revisions of "EclipseLink/Development/DBWS/Overview"

Revision as of 11:52, 14 April 2014

High-level Overview of EclipseLink DBWS

The purpose of this document is to provide a high-level overview of the design and runtime portions of the DBWS component. In addition, notable pain points and an outline of relevant changes from version to version will be provided.

Design time Component

The DBWS builder is responsible for processing input from the user (or tooling, such as JDeveloper), then scraping the database DDL based on this input. The information retrieved from the database is used to construct a meta-model, which is in turn used to generate a number of artifacts required by the DBWS runtime in order to service SOAP message requests.

The following artifacts will be generated by the builder:

• WSDL (JAX-WS 2.0)
• JPA metadata
• JAXB metadata
• XML Schema
• Sessions XML
• DBWS XML-Relational (XR) file (defines querie operations used by the XR runtime)
• web.xml
• DBWSProvider (Web service provider)
• ProviderListener (servlet)

Supported Operations

Following are the types of operations DBWS supports:

• SQL
  • generate operations based on SQL statement(s)
• DB Table
  • CRUD operations generated by default
  • Custom SQL statements can be applied as well
• Custom SQL
  • Allows additional operations to be defined on a given table
• Secondary SQL
  • Allows separate design/runtime SQL statements to be defined
  • Design time SQL used to build operations and runtime SQL executed at runtime
• Stored function/procedure
• Oracle Object and Object table types
• PL/SQL stored function/procedure
• PL/SQL records and collections

User/Tooling Input

At a minimum, DBWS builder requires database connectivity information and one or more database targets as listed in Supported Operations above. The input can be passed to the builder as an XML file or as Java objects (builder creates the Java model based on the input XML, but this model can be created and handed to the builder).

Following is sample input XML:

<?xml version="1.0" encoding="UTF-8"?>
<dbws-builder xmlns:xsd=\http://www.w3.org/2001/XMLSchema\>
  <properties>
    <property name="projectName">tabletype</property>
    <property name="logLevel">off</property>
    <property name="username">scott</property>
    <property name="password">tiger</property>
    <property name="url">jdbc:oracle:thin:@localhost:1521:ORCL</property>
    <property name="driver">oracle.jdbc.OracleDriver</property>
    <property name="platformClassname">org.eclipse.persistence.platform.database.oracle.Oracle11Platform</property>
  </properties>
  <table
     schemaPattern="SCOTT"
     tableNamePattern="EMPLOYEE"
  />
</dbws-builder>

And the equivalent Java code:

DBWSBuilder builder = new DBWSBuilder();
builder.setProjectName("tabletype");
builder.setLogLevel("off");
builder.setUsername("scott");
builder.setPassword("tiger");
builder.setUrl("jdbc:oracle:thin:@localhost:1521:ORCL");
builder.setDriver("oracle.jdbc.OracleDriver");
builder.setPlatformClassname("org.eclipse.persistence.platform.database.oracle.Oracle11Platform");
 
TableOperationModel tableOpModel = new TableOperationModel();
tableOpModel.setSchemaPattern("SCOTT");
tableOpModel.setTablePattern("EMPLOYEE");
builder.addOperation(tableOpModel);

Note: the 'projectName' property will be used as the default namespace.

Evolution of DBWS

EclipseLink 2.4

EclipseLink 2.4 was the first release containing the Oracle DDL parser. This string parser was designed to handle parsing Oracle-specific DDL, providing the ability to process PL/SQL and advanced Oracle JDBC types, such as Object and Object table types.

EclipseLink 2.5

The major change in this release was removal of the legacy EclipseLink deployment XML project files in favor of JPA/JAXB metadata. In addition, much of the code was reworked to accommodate generation of the metadata vs. deployment XML artifacts.

It is important to note that 2.5 and 2.6 DBWS code bases are virtually identical.