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.
Difference between revisions of "EclipseLink/Development/DBWS/Overview"
(→ANT) |
(→Overview of EclipseLink DBWS) |
||
Line 145: | Line 145: | ||
* eclipselink.dbws.builder.test.oracle | * eclipselink.dbws.builder.test.oracle | ||
* eclipselink.dbws.builder.test.oracle.server | * eclipselink.dbws.builder.test.oracle.server | ||
− | |||
− | |||
− | |||
==== Configuration ==== | ==== Configuration ==== | ||
Line 165: | Line 162: | ||
# server.port | # server.port | ||
# server.datasource | # server.datasource | ||
+ | |||
+ | Following is a sample <code>test.properties</code> file | ||
+ | <css> | ||
+ | .source-xml {padding:4px;border:1px solid black;} | ||
+ | </css> | ||
+ | <source lang="xml"> | ||
+ | # Testing environment properties | ||
+ | |||
+ | # | ||
+ | # Database properties | ||
+ | # | ||
+ | db.user=SCOTT | ||
+ | db.pwd=toger | ||
+ | db.driver=oracle.jdbc.OracleDriver | ||
+ | db.url=jdbc:oracle:thin:@ottvm000.ca.oracle.com:1521:ORCL | ||
+ | db.platform=org.eclipse.persistence.platform.database.oracle.Oracle11Platform | ||
+ | jdbc.driver.jar=D:/extension.oracle.lib.external/ojdbc6.jar | ||
+ | |||
+ | # | ||
+ | # WLS properties | ||
+ | # | ||
+ | server.platform=wls | ||
+ | server.host=localhost | ||
+ | server.port=7001 | ||
+ | server.datasource=jdbc/DBWStestDS | ||
+ | |||
+ | # | ||
+ | # TopLink properties | ||
+ | # | ||
+ | # Logging option for debugging - 'info' for light logging, 'fine' for SQL stmts, 'finest' for everything | ||
+ | logging.level=off | ||
+ | |||
+ | support.test=true | ||
+ | </source> | ||
+ | ==== ANT ==== | ||
+ | The XR/Builder tests can be run by executing <code>ant -f antbuild.xml run-tests</code>. For the server tests, the following two targets can be executed: <code>ant -f antbuild.xml test-builder</code> and (after deploying the generated .war files) <code>ant -f antbuild.xml test-service</code>. |
Revision as of 14:20, 24 April 2014
Contents
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, an outline of relevant changes from version to version will be provided. The EclipseLink DBWS documentation can be found here: http://www.eclipse.org/eclipselink/documentation/2.5/dbws/toc.htm.
Design time Component
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 are 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 - deployed in a servlet container)
- ProviderListener (servlet listener impl.)
Typical .war file structure
\---web-inf | | web.xml | +---classes | +---META-INF | | eclipselink-dbws.xml | | eclipselink-dbws-or.xml | | eclipselink-dbws-ox.xml | | eclipselink-dbws-sessions.xml | | | \---_dbws | DBWSProvider.class -- auto-generated JAX-WS 2.0 Provider | ProviderListener.class -- auto-generated Servlet implementation | \---wsdl eclipselink-dbws-schema.xsd eclipselink-dbws.wsdl swaref.xsd -- optionally generated is swaRef is being utilized
Basic Flow
The basic flow of DBWS builder is as follows:
- User input --> Scrape DB & build meta-model
- Generate OR/OX projects
- Generate XML schema (uses OX project)
- Generate XR Service Model (uses OR project)
- Generate WSDL (uses service model)
- Generate Web app and WebService impl.
- Generate JAXB and JPA metadata files (uses OR/OX projects)
- Package generated artifacts
User input --> Scrape DB & build meta-model --> Build OR/OX projects, XR query operations, and WSDL based on meta-model --> Generate XML schema based on OR/OR projects --> Generate Web app and WebService impl. --> Generate JAXB/JPA metadata based on OR/OX projects --> Package results
Supported Input
Following are the types of input DBWS supports:
- DB Table
- CRUD operations generated by default
- Custom SQL statements can be applied as well
- Nested procedures are supported
- Custom SQL
- Allows additional operations to be defined on a given table, for example, the ability to search for one or more entries based on a field other than the PK field
- 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
- PL/SQL stored function/procedure
Simple XML Format
DBWS provides the ability to wrap results in custom XML tags; this is useful where the structure of the results are not known, such as in the case of a ref cursor. If the 'isSimpleXmlFormat' flag is set to true, the results will look like the following:
<?xml version="1.0" encoding="UTF-8"?> <simple-xml-format> <simple-xml> <ID>1</ID> <NAME>Joe Oracle</NAME> </simple-xml> <simple-xml> <ID>2</ID> <NAME>Jane Oracle</NAME> </simple-xml> </simple-xml-format>
Note that both the simple-xml-format
and simple-xml
element names are customizable.
Shadow Types & Anonymous PL/SQL Generation
JDBC does not support transporting Oracle PL/SQL types. In order for DBWS to handle PL/SQL input and output arguments, two tasks are required. First, for each PL/SQL type (record/collection) there must be an equivalent JDBC type. DBWS will generate 'shadow' create/drop DDL for each PL/SQL type; this DDL can be executed on the DB to add and remove these required types. The second thing that is required are PL/SQL functions that covert PL/SQL types to equavalent JDBC types and vice versa. To support this, anonymous PL/SQL is generated and executed on the database at runtime.
DDL Parser
To provide more complete handling of Oracle PL/SQL and 'advanced' JDBC types (Object and Object table types), the DDLParser was created. This JavaCC constructed parser is responsible for building database meta-model objects from a given string of Oracle DDL.
More information regarding the DDLParser can be found here:
- http://wiki.eclipse.org/EclipseLink/Development/DBWS/ParseDDLFS
- http://wiki.eclipse.org/EclipseLink/Development/DBWS/ParseDDLDS
Git repo:
JavaCC plugin for Eclipse:
JPA Metadata Generation
- JPA now better supports PL/SQL based queries and structures via JPA
JAXB Metadata Generation
- TBD
Legacy Deployment XML Support
- TBD
Runtime Component
The DBWS runtime component is responsible for fulfilling SOAP message requests, and makes use of Eclipselink JAXB, JPA and XR to accomplish this.
Basic Flow
The basic flow of the DBWS runtime is as follows:
SOAP message received --> SOAP body is unmarshaled into an XR Invocation object --> Query Operation is retrieved based on the invocation name --> Query operation is invoked --> Query results are used to generate a SOAP response message --> response is returned to the caller
Evolution of DBWS
EclipseLink 2.4
EclipseLink 2.4 was the first release containing the Oracle DDL parser. This JavaCC based parser was designed to better handle parsing Oracle-specific DDL, providing the ability to process PL/SQL and advanced Oracle JDBC types, such as Object and Object table types. Another major change was abandoning the visitor pattern that was used to create projects and descriptors based on the types discovered in the DDL. As of 2.4, a database type meta-model is constructed based on results of the DDLParser parse or JDBC driver metadata, and this meta-model is used to build the various required artifacts.
Information about the DDLParser's design and functionality can be found here: http://wiki.eclipse.org/index.php?title=EclipseLink/Development/DBWS/ParseDDLDS . In particular, the "Parsing Technology" section is worth reviewing.
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.
Tests
There are tests in two different projects; dbws
and utils
. The tests in the dbws
project focus on XR runtime testing, whereas the tests in the utils
project are end-to-end tests. Additionally, there are server tests in the utils
project that allow the builder to be executed, then the generated .war can be deployed to an app server and the service tested (via SOAP).
XR (dbws
project)
- eclipselink.dbws.test
- eclipselink.dbws.test.oracle
DBWS builder (utils
project)
- eclipselink.dbws.builder.test
- eclipselink.dbws.builder.test.oracle
- eclipselink.dbws.builder.test.oracle.server
Configuration
The following properties need to be set for the tests to run successfully (typically via test.properties in user_home
):
- db.user
- db.pwd
- db.driver
- db.url
- db.platform
- jdbc.driver.jar
- logging.level
- support.test (should set this to
true
)
For server tests, the following additional properties need to be set:
- server.platform
- server.host
- server.port
- server.datasource
Following is a sample test.properties
file
# Testing environment properties # # Database properties # db.user=SCOTT db.pwd=toger db.driver=oracle.jdbc.OracleDriver db.url=jdbc:oracle:thin:@ottvm000.ca.oracle.com:1521:ORCL db.platform=org.eclipse.persistence.platform.database.oracle.Oracle11Platform jdbc.driver.jar=D:/extension.oracle.lib.external/ojdbc6.jar # # WLS properties # server.platform=wls server.host=localhost server.port=7001 server.datasource=jdbc/DBWStestDS # # TopLink properties # # Logging option for debugging - 'info' for light logging, 'fine' for SQL stmts, 'finest' for everything logging.level=off support.test=true
ANT
The XR/Builder tests can be run by executing ant -f antbuild.xml run-tests
. For the server tests, the following two targets can be executed: ant -f antbuild.xml test-builder
and (after deploying the generated .war files) ant -f antbuild.xml test-service
.