Developing Persistence Architectures Using EclipseLink Database Web Services, Release 2.5
  Go To Table Of Contents

Beta Draft: 2013-04-15

Understanding XML-to-Relational Mapping (XRM)

EclipseLink's ORM and OXM features provides the basis for a powerful bridge between a database's relational structure(s) and XML's hierarchical structure.

Figure 1-1 EclipseLink XR Architecture


A typical EclipseLink DBWS service is packaged in an archive (.jar or .war file) with a service descriptor file eclipselink-dbws.xml in the META-INF directory (or WEB-INF/classes/META-INF when packaged in a .war file). To bridge the relational database and XML worlds, an EclipseLink sessions.xml (eclipselink-dbws-sessions.xml) points to two Eclipse projects: one for the ORM side, the other for the OXM side. The service also requires an XML Schema Definition file eclipselink-dbws-schema.xsd which in conjunction with the OXM project, specifies how information from the database is to be "shaped" into XML documents.

Figure 1-2 Typical EclipseLink DBWS Service Files

Typical EclipseLink DBWS Service Files
Description of "Figure 1-2 Typical EclipseLink DBWS Service Files"


Not all files are displayed.

The EclipseLink DBWS service descriptor file, eclipselink-dbws.xml, is easy to read, with minimal required information and simple defaults for omitted fields. This allows for auto-generation by a utility or manual editing. Example 1-1 illustrates a sample DBWS service descriptor file.

Example 1-1 Example DBWS Service descriptor file

<?xml version="1.0" encoding="UTF-8"?>
    <sql><!--[CDATA[select count(*) from EMP]]--></sql>

Table 1-1 describes the elements of the EclipseLink DBWS service descriptor file.

Table 1-1 EclipseLink DBWS Service Descriptor File Elements

Element Description Required? Default


Name of the EclipseLink DBWS service.

Yes, set by the projectName property in the DBWSBuilder.



Name of the EclipseLink sessions.xml file.



Any of the following:

  • insert

  • update

  • delete

  • query

Service operations

At least one operation


XML Schema Definition

The EclipseLink DBWS service schema file eclipselink-dbws-schema.xsd can be created by hand, or auto-generated by the design-time DBWSBuilder utility that derives XML element-tag names from Database metadata (column names, types, nullable, and so on).

The DBWSBuilder utility will not generate an XML Schema Definition when the information returned by a query operation has no pre-determined structure, such as:

  • a resultSet from a custom SQL query operation

  • the results from a Stored Procedure query operation

  • the row-count from an update operation

In these cases, the EclipseLink DBWS runtime provider uses information only available at the time of query execution to build the XML document:

Example 1-2 Example Simple XML Format (SXF) document

Element tag names are direct copies of table's column names.

<?xml version = '1.0' encoding = 'UTF-8'?>

These XML documents are "dumb," as they cannot be validated against any pre-determined schema - or more accurately, only the following very permissive "sequence-of-any" schema can validate such documents:

Example 1-3 Simple XML Format Schema

<?xml version="1.0" encoding="UTF-8"?>
  <xsd:complexType name="simple-xml-format">
      <xsd:any minOccurs="0"/>

The element tags simple-xml-format and simple-xml can be customized by setting the appropriate properties on an operation.