Difference between revisions of "EclipseLink/UserGuide/DBWS/Creating EclipseLink DBWS Services (ELUG)"

Revision as of 11:00, 6 April 2009

Note: A basic overview of EclipseLink Database Web Services (DBWS) can be found here

Creating EclipseLink DBWS Services

You can generate a WAR file containing the EclipseLink DBWS service descriptor along with all required deployment artifacts for a JAX-WS 2.0 Web service (WSDL, XML schema, web.xml, EclipseLink object-relational mapping (ORM) and object-XML mapping (OXM) native project XML files, and so on).

Note that the files swaref.xsd and web.xml have names and content determined by their roles in Web deployment and cannot be changed.

The deployable .war file has been verified to work with the Oracle WebLogic Server 10.3 JavaEE container.

An alternate deployable JAR file has been verified to work as a JavaSE 6 'container-less' EndPoint (see
the example EclipseLink DBWS Service deployed as a JavaSE 6 'containerless' EndPoint for details).

This section describes how to create EclipseLink DBWS services using the DBWSBuilder utility.

How to Create EclipseLink DBWS Services Using the DBWSBuilder Utility

You can use the EclipseLink DBWS design-time utility DBWSBuilder to create deployment files. DBWSBuilder is a Java application that processes the operations described in an EclipseLink DBWS builder XML file to produce all the required deployment artifacts.

Be sure to set the following environment variables in the <ECLIPSELINK_HOME>\utils\dbws\setenv.cmd (or setenv.sh file) before invoking DBWSBuilder:

• $JAVA_HOME
• $DRIVER_CLASSPATH

There are script files provided for invoking DBWSBuilder. They are located in <ECLIPSELINK_HOME>\utils\dbws. The scripts are dbwsbuilder.cmd for Windows usage, and dbwsbuilder.sh for other operating systems.

DBWSBuilder usage - [] indicates optional argument:
prompt > dbwsbuilder.cmd -builderFile {path_to_builder.xml} -stageDir {path_to_stageDir} -packageAs[:archive_flag] {packager} [additional args]
Available packagers:
  -packageAs:[default=archive] javase [jarFilename]
  -packageAs:[default=archive] wls [warFilename]

Using DBWSBuilder, you can generate an EclipseLink DBWS service from the following sources:

• an existing relational database table;
• one or more SQL SELECT statements;
• a stored procedure.

Creating an EclipseLink DBWS Service from a Database Table

Create an EclipseLink DBWS builder XML file with a <table> query operation:

For more information, see the basic example Creating EclipseLink DBWS Service based on Database Table.

Creating an EclipseLink DBWS Service from a SQL Statement

Create an EclipseLink DBWS builder XML file with a <sql> query operation:

Parameter Binding

The SQL SELECT statement for a <sql> operation may have parameters that must be bound to a datatype from the eclipselink-dbws-schema.xsd, or to any of the basic XSD datatypes. The SQL SELECT string uses JDBC-style '?' markers to indicate the position of the argument. The <sql> operation uses nested <binding> elements to match the datatype to the parameters. The order in which <binding> elements are defined must match the order of '?' markers in the SQL string:

The argument named "EMPNO" is bound to an integer type, while the argument named "LAST_NAME" is bound to a string type.
For more information, see the basic example Creating EclipseLink DBWS Service based on Results Sets from custom SQL SELECT statements.

Creating an EclipseLink DBWS Service from a Stored Procedure

Create an EclipseLink DBWS builder XML File with a <procedure> query operation:

For more information, see the basic example Creating EclipseLink DBWS Service based on Stored Procedure.

Customizing an EclipseLink DBWS Service

There are a number use-cases that require an EclipseLink DBWS Service to be customized. The use-cases can be subdivided into the following categories:

• simple - changing an <element-tag> to an "attribute";
• intermediate - customizing the EclipseLink ORM or OXM Projects;
• advanced - manually generating all required deployment artifacts.

How to Perform Simple Customization

See the example Changing an <element-tag> to an "attribute".

How to Perform Intermediate Customization

The primary reason to use an EclipseLink SessionCustomizer is to enable programmatic access to the EclipseLink API. Using this API, you can retrieve the object-relational (ORM) or object-XML mapping (OXM) descriptors from the session, and from these descriptors add, change or delete mappings. You could also consider turning off the session cache, or changing the transaction isolation level of the database connection, as the following example shows:

Implement a org.eclipse.persistence.config.SessionCustomizer:

In the DBWSBuilder builder XML file, specify if the customization applies to the ORM project or the OXM project:

or

For details, see Session Customization.

How to Perform Advanced Customization

You can customize an EclipseLink DBWS service by creating your own project.xml and sessions.xml files. Using your preferred utility, you can do the following:

• map your objects to your relational database in an EclipseLink relational project;
• map your objects to your XML schema in an EclipseLink XML project:
• create an EclipseLink sessions.xml file that references both projects.

In this way, you can control all aspects of the relational and XML mapping. This approach is best when you want to customize most or all details. See the advanced example Creating EclipseLink DBWS Service based upon existing ORM and OXM Projects.

Using DBWSBuilder API

The EclipseLink DBWS design-time utility, DBWSBuilder, is a Java application that generates EclipseLink DBWS files and assembles them into deployable archives. YOu can also set the DBWSBuilder’s properties, add table or procedure definitions and SQL operations programmatically through DBWSBuilder’s API.

Information pending

Copyright Statement