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

Description of "Figure 1-1 EclipseLink XR Architecture"

Configuration

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

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

Note:

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"?>
<dbws
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  >
  <name>example</name>
  <sessions-file>example-dbws-sessions.xml</sessions-file>
  <query>
    <name>countEmployees
    <result>
      <type>xsd:int</type>
    </result>
    <sql><!--[CDATA[select count(*) from EMP]]--></sql>
  </query>
</dbws>

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

Element	Description	Required?	Default
`name`	Name of the EclipseLink DBWS service.	Yes, set by the `projectName` property in the `DBWSBuilder`.	None
`sessions-file`	Name of the EclipseLink `sessions.xml` file.	No	`eclipselink-dbws-sessions.xml`
Any of the following: `insert` `update` `delete` `query`	Service operations	At least one operation	None

name

Name of the EclipseLink DBWS service.

Yes, set by the projectName property in the DBWSBuilder.

None

sessions-file

Name of the EclipseLink sessions.xml file.

eclipselink-dbws-sessions.xml

Any of the following:

insert
update
delete
query

Service operations

At least one operation

None

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'?>
<simple-xml-format>
  <simple-xml>
    <EMPNO>7788</EMPNO>
    <ENAME>SCOTT</ENAME>
    <JOB>ANALYST</JOB>
    <MGR>7566</MGR>
    <HIREDATE>1987-04-19T00:00:00.000-0400</HIREDATE>
    <SAL>3000</SAL>
    <DEPTNO>20</DEPTNO>
  </simple-xml>
  <simple-xml>
    <EMPNO>7369</EMPNO>
    <ENAME>SMITH</ENAME>
    <JOB>CLERK</JOB>
    <MGR>7902</MGR>
    <HIREDATE>1980-12-17T00:00:00.000-0400</HIREDATE>
    <SAL>800</SAL>
    <DEPTNO>20</DEPTNO>
  </simple-xml>
</simple-xml-format>

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:schema
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  >
  <xsd:complexType name="simple-xml-format">
    <xsd:sequence>
      <xsd:any minOccurs="0"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

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