SOA Appendix B XML Fundamentals August 2010

Oracle 11g SOA Suite Handbook: Appendix B - XML Fundamentals August 1, 2010

15-1

Appendix B - XML Fundamentals

XML is the acronym for eXtensible Markup Language. XML was derived from SGML –

starting life around 1996. XML‟s primary purpose has become to share structured data across

organizations and technologies. As such it forms the foundation for almost anything we do in the

SOA Suite. A solid understanding of XML and some of its associates - XML Schema Definition,

XPath, XSLT - is required to make the most (and sometimes even the smallest bit) of the SOA

Suite 11g.

This chapter gives some introduction and background on XML and friends. Note

however that is merely a very superficial overview and that if these concepts are entirely new to

you, you will probably have to consult other resources to crank up your understanding of XML,

namespaces, XPath, XSD and XSLT. Also note that this appendix continues where the

discussion in chapter 4 stops.

For good measure we also throw in some examples of how XML cs. can be used and

manipulated in Java and PL/SQL, our favorite programming languages. We conclude by making

some inroads into the domain of WebServices, the other pillar of the SOA Suite and itself resting

on the XML and XSD underpinnings introduced early on in this appendix.

Introducing XML

Clearly XML is an essential ingredient of Service Oriented Architecture. Service

definitions are expressed via XML documents, the data structure of messages is defined through

XML documents, configuration for the run time infrastructure is by and large in XML, the

contents of messages sent between Services and Service Consumers is XML based and the

SOAP envelop that wraps the message itself is also – you guessed it – an XML document. In

order to delve into doing SOA, there are a few things that you should know about XML. For now


8-2

we will assume you have dealt with XML in the past. For a basic introduction into XML as well

as a list of other resources with in depth information on XML, see Appendix 2.

Much of the attraction of XML lies in the fact that in all major application development

technologies, tools and platforms, facilities are available for performing the most frequently

needed operations on XML. Whether you develop in JavaScript, PHP, Java, C# or PL/SQL, for

the JEE, .NET or Oracle platform, you will have native language facilities that help you process

XML documents. These operations performed on XML documents are:

Parsing – read the XML and turn it into a native data object for the programming

language at hand

Data Binding – go one step beyond parsing and make the data from the XML document

available as a custom, strongly typed programming language data structure, aka domain

model

Validating – verifying the validity of the XML document against rules specified in a

schema such as XSD or Schematron

Querying – retrieving specific information from the XML document by applying search

questions

Transforming – convert the XML document based on a particular schema into an XML

document based on a different schema by applying a transformation template or

stylesheet

While some of the operations listed above are handled transparently for us by the tools

we will be using for building the SOA, others will be discussed in more detail later in this

chapter and also make frequent appearances throughout the book. Especially the use of XML

Schema Definitions for describing the rules against which XML documents should be validated,

the use of XPath for performing queries to retrieve specific information from XML documents

and the application of XSLT stylesheets for transforming XML documents will be fairly familiar

by the time you are done with this book.


15-3

XML is the acronym for eXtensible Markup Language. XML was derived from SGML –

starting life around 1996. XML‟s primary purpose has become to share structured data across

organizations and technologies. XML is intended to be readable by humans as well as software.

XML documents are expressed in plain text, with many different encodings supported. The most

important encoding is Unicode (UTF-8 or UTF-16), while ISO-8859 is also frequently used. An

XML document will typically look like an over-structured text-document, that contains both data

and meta-data. XML documents are often called verbose – as they tend to contain a lot of text

compared to the actual data content.

The extensibility of XML lies in the fact that anyone can use the basic XML lexical

grammar rules and create custom markup languages by defining new elements element

hierarchies. A lot of specific application languages have been defined based on XML. These

include XHTML, RSS, Scalable Vector Graphics (SVG) and the Open Document Format(ODF)

and its counterpart OfficeOpen XML (OOXML).

XML Documents

An XML document consists of tagged elements organized in a tree-like structure. An

XML document contains various types of nodes:

document node (the entire document)

element node

text node (the literal values contained in element nodes)

attribute node

comment node

These nodes can be accessed in various ways in XPath Queries and XSLT

Transformations, as we have seen through this book.

An XML document usually starts with the XML declaration, a single line stating that it is

indeed an XML document, based on version 1.0 of the XML specification. This line also

8-4

specifies the encoding used for the document – frequently this will be UTF-8, although ISO-

8859-1 is fairly common as well.

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

The real content of the XML document is in a tree structure, rooted in a single element.

Note how an element consists of a start-tag and an end-tag with possibly attributes, a literal data

value and child elements in between. An element tag starts with < (the less-than character) and

ends with > (the greater-than character). The end-tag has a virgule immediately following the <

character. Note: forward slash is the more common word for virgule. Elements need to be

correctly nested: a child element starts and ends within its parent. The name of an element is case

sensitive. That means that <Patient> is not the same element type as <patient>.

In this example, patient is the root element. It contains two child elements: personal and

doctorVisits. Comments can be inserted in an XML document using the  end

enclosure.


<patient>

<personal>

<firstName>Mildred</firstName>

<lastName>Huston</lastName>

</personal>



<doctorVisits>

<doctorVisit dateOfVisit="2008-12-31" >

<treatingPhysician>Dr. Solomon</treatingPhysician>

<prescription/>

<charge>243.32</charge>

</doctorVisit>

</doctorVisits>


15-5

</patient>

The prescription element is empty: it does not have child elements nor does it have attributes.

Such empty elements can be abbreviated using a single tag that includes the virgule:

<prescription/>

Attributes are key-value pairs, separated from each other by whitespace characters, with the

value between quotes, like

attributeName1="value" attributeName2="value"

Attribute names, like element names, are case sensitive.

There is some debate about whether to use attributes in XML elements – such as the dateOfVisit

attribute in the doctorVisit element – or stick to child elements to associate data values with

elements. At the end of the day, it seems largely a matter of personal preference. Tools are

typically capable of handling both child elements and attributes. Two clear distinctions between

attributes and child elements is that child elements can have nested child elements of their own

(and attributes for that matter) and can have multiple occurrences. Attributes in contrast are

unique within their element and contain only simple values.


8-6

The tree structure of the Patient XML document

Special Characters

Characters such as < and > are part of the infrastructure of an XML document. However, there

may be occasions when you want to use these characters in the actual content. XML defines a

number of special characters that you can use in those situations:

Entity Used for

& &


15-7

< <

> >

" “

' „

For the occasional appearance of a lone < or & character, it is okay to have to resort to

these somewhat cumbersome entities. However, with frequent occurrences for example in longer

text fragment, it can become quite a nuisance. And incorporating data from XML unaware

sources can be somewhat difficult because of these special characters.

XML allows us to include CDATA sections. Any text inside a CDATA section is ignored

by XML parsers and contributes no structure to the document, just content. That means that a

CDATA section can have <, >, & and “ in abundance: to tools processing the document, they are

plain text. A CDATA section is used in a text node like this:

<treatingPhysician><![CDATA[Dr. Solomon & Dr. Burke]]></treatingPhysician>

One other special type of reference you may encounter in XML documents is &#nnnn; or

&#hhhh;. These signify exact Unicode codepoints in either decimal (nnnn) or hexadecimal

(hhhh) format.

The true identity of XML elements - introducing Namespaces

One of the interesting questions we frequently should ask when we encounter an element

in an XML document is: what element definition is this element based on? What exactly is meant

with this element? Patient can refer to a person needing doctor‟s attention but could also describe

a characteristic. A table element could signify an HTML layout structure or a piece of furniture.


8-8

And one organization‟s customer can be quite different from another organization‟s, say when

comparing a prison with a hospital. We need to identify those XML element more accurately

than by just using a simple name!

Uniquely Identifying XML Elements

Let‟s take a brief step away from XML. When we speak about objects in the database, it

is easy to see that instructing a database developer to write a SQL query against Table

CUSTOMERS in a specific database, is not a good enough instruction: there can be dozens of

tables called CUSTOMER. A full identification of the table requires the schema in which it

resides. In Java programs, classes are used to construct objects that contain data and execute

application logic. Anyone class usually calls upon other classes to perform some task. For

example class PageRenderer may call upon class ButtonRenderer to render an instance of a

Button. Again, using the indication ButtonRenderer is not good enough, as there may be several

classes called ButtonRenderer. The fully qualified name for a class includes not just the name of

the class, but also the package in which it resides, for example org.superui.renderers. Thus

programmers – and the JVM class loader – can distinguish between

org.superui.renderers.ButtonRenderer and my.sandbox.ButtonRenderer.

With XML, we have the same thing. Without further indication, we could easily

misinterpret element names. From the context of the document, we can derive that the charge

element does not specify electrical information or the light brigade storming in but most likely

the bill presented to the patient for this particular visit. However, we should not rely on such

subjective, context based interpretations, but clearly state our intentions. So in XML too we use

fully qualified names.

A fully qualified name is composed from a local name and a namespace. In Java the

namespace is the package name, in the Oracle database it is the name of the schema. In XML the

namespace simply put is a unique string. Slightly less simply put: the namespace identifier is a

URI (Uniform Resource Identifier) according to the specifications laid down by the IETF

(Internet Engineering Task Force, RFC3986). These are quite simple, for our purpose at least:


15-9

A URI is a - case sensitive - sequence of characters from a very limited set: the letters of

the basic Latin alphabet, digits, and a few special characters.

The IETF also remarks: A URI often has to be remembered by people, and it is easier for

people to remember a URI when it consists of meaningful or familiar components. URI do not

specifically refer to a resource that is accessible at a location that the URI seems to describe.

URIs are used to uniquely identifying resources, not for accessing them.

One straightforward way of making unique the elements you define in your XML

documents is by using a namespace identifier that contains something unique to your

organization or even to yourself. Many namespace identifiers in XML - just like package names

in Java - therefore include the URL for the website of the organization. However, any unique

string will do:

http://ourhospital.com/patient

http://ourhospital.com/staff

com.ourhospital.patients

PATIENT:UUID673215631265GEE

A Namespace provides a container in which to collect names that for some reason belong

together. These names frequently share an owning organization, a domain or knowledge area or

an industry.


8-10

Namespaces for elements in different domains

The URI syntax is commonly organized hierarchically, with components listed in order

of decreasing significance from left to right. This does not really mean anything - at least not to

software parsing the URI definitions; it is just a convenient way of showing weak links at various

levels. The http://ourhospital.com/patient and http://ourhospital.com/staff namespace identifiers

are both defined in “Our Hospital”, and describe various sub domains in that hospital. There is

no other connection between names in those two namespaces and the fact that their URIs have a

partial overlap is meaningless to XML parsers and processors.

We associate an XML element name with a namespace with this syntax:

<patient xmlns="http://ourhospital.com/patient">

Instead of just patient, we should now speak about this element as

{http://ourhospital.com/patients}patient. This is the Qualified Name of the element, often

referred to as the QName. The patient is the local name. Note: XML elements do not have to be

in a namespace. The local name of such unqualified elements is equal to their QName.


15-11

Having to qualify every XML name in this way would be dramatic: the document inflates

even further, the work involved is almost painful and the readability is negatively impacted- to

put it mildly. So instead, we can work with simple prefixes and rely on several inheritance rules.

Prefixes allow us to use friendlier ways of associating names with namespaces. Our

patient element could be fully qualified with syntax like:

<hospital:patient … >

The prefix can be anything you like. It is up to the XML parser to associate each element via its

prefix with the real namespace identifier. The linking pin to make that possible is the namespace

binding, the declaration somewhere in the XML document that associates the prefix - again, any

string you fancy - with the namespace URI:

<hospital:patient xmlns:hospital="http://ourhospital.com/patient">

Some prefixes are reserved - such as xml and xmlns - and some have become so

commonly used for specific namespaces - for example xsl

(http://www.w3.org/1999/XSL/Transform), xsd (for http://www.w3.org/2001/XMLSchema) and

xhtml (for http://www.w3.org/1999/xhtml) - that you would better refrain from using them for

other purposes.

The namespace prefix, unless it is “xml” or “xmlns”, MUST have been declared in a

namespace declaration attribute in either the start-tag of the element where the prefix is used or

in an ancestor element (i.e. an element in whose content the prefixed markup occurs). Once a

prefix has been associated with a namespace inside some element tag, it can be used in all child

elements.

<hospital:patient xmlns:hospital="http://ourhospital.com/patient">

<hospital:personal>

<hospital:firstName>


8-12

We can also use the concept of the default namespace: any element that is not specifically

prefixed or associated with a namespace through the xmlns attribute is in the default namespace -

if it has been defined. The default namespace is defined through a variation on the declaration we

saw before:

<patient xmlns="http://ourhospital.com/patient">

By simply using xmlns, without the colon and prefix, we state that for this element and

all its descendants the default namespace is set to http://ourhospital.com/patient. Since many

XML documents contain only elements from a single namespace, the default namespace

simplifies things considerably. A single namespace declaration in the root element of the

document is all we need to associate all elements with the appropriate namespace.

<patient xmlns ="http://ourhospital.com/patient">

<personal>

<firstName>

Of course, an XML document may very well contain elements from different

namespaces. We can select one as the (global) default namespace - typically the source of the

largest portion of elements. The other namespaces can be associated with prefixes or be used as

local default namespaces. The declaration of namespace bindings is usually done in the root

element, but can be done in any element.

Namespace visibility in the XML instance document

Through the import of the WHO-medic.xsd we have made the bloodPressureReading

element available in the VeryPatient.xsd document. It allows us to specify how instance XML

documents can define bloodReadings inside the bloodReadings child in the patient element. At

this point, we have a choice to make. We know that bloodReading is from the

{http://who.org/medical} namespace. We can choose to leave it like that and add the knowledge

and burden of both namespaces to the instance XML documents, or we can decide to hide that

complexity. If we choose to do the latter, the {http://who.org/medical} namespace is not visible

in the XML documents. In fact, only the root element will need to be associated with the target


15-13

namespace of the schema document in that case, and all other elements are without namespace

qualification.

The outcome of our decision is declared using the elementFormDefault attribute in the

schema element of all participating XSD documents. When this attribute is set to unqualified,

only the root element is namespace qualified and all other elements based on the schema are free

of namespace qualifiers. The namespaces for the imported XSDs are not visible in the instance

document. With the attribute set to qualified, all elements in the instance document are

namespace qualified. That means that the namespace of each of the XSDs may be needed in the

XML instance document. Note: all related XSD documents - both the base document and all

XSDs it imports - need to have the same value set for this attribute.

With the elementFormDefault set to unqualified in all XSD documents

<?xml version="1.0" encoding="windows-1252" ?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="http://ourhospital.com/patient"

xmlns:medic="http://who.org/medical"

targetNamespace="http://ourhospital.com/patient"

elementFormDefault="unqualified">

...

The instance documents will have no default namespace and only the root element

patient is namespace qualified:


<hospital:patient xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://ourhospital.com/patient VeryPatient.xsd"

xmlns:hospital="http://ourhospital.com/patient">

<personal>

<firstName>John</firstName>

...


8-14

</personal>

<bloodpressureReadings>

<bloodpressureReading>...</bloodpressureReading >

...

And with the Schema set to elementFormDefault qualified






elementFormDefault="qualified">

...

the instance document has all elements namespace qualified, partly through the default

namespace:


<patient xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://ourhospital.com/patient VeryPatient.xsd"


xmlns="http://ourhospital.com/patient">

<personal>

<firstName>John</firstName>

</personal>


<medic:bloodPressureReading>


15-15

<medic:dateOfReading>2008-12-29</medic:dateOfReading>

The default value for the elementFormQualified is unqualified. In the XSD documents

used in the Oracle SOA Suite we usually will see this attribute set to qualified.

The schema element in XSDs also has the attributeFormQualified attribute, which

similarly specifies for the attributes in the instance document whether or not they are namespace

qualified. Again, as for elementFormQualified, the default is unqualified. This default is not

overridden very frequently.

Multiple Namespaces in an XML instance document

Of course, an XML document may very well contain elements from different

namespaces. We can select one as the (global) default namespace - typically the source of the

largest portion of elements. The other namespaces can be associated with prefixes or be used as

local default namespaces. The declaration of namespace bindings is usually done in the root

element, but can be done in any element.

In this next example, we see an XML document with a global default namespace

http://ourhospital.com/patient. A secondary namespace is http://www.hospital.org/hrm bound to

the prefix hrm. All unprefixed elements are in the default namespace. However, the

bloodPressureReading element defines a new (local) default namespace:

http://who.org/medical. This element and all of its children are in this namespace.


<patient xmlns="http://ourhospital.com/patient"

xmlns:hrm="http://www.hospital.org/hrm">

<personal>

<firstName>Mildred</firstName>

<lastName>Huston</lastName>

8-16

</personal>

<mailAddress>

<hrm:city>Redwood Shores</hrm:city>

<hrm:state>CA</hrm:state>

<hrm:country>us</hrm:country>

<hrm:street>Pancake Boulevard</hrm:street>

<hrm:houseNumber>12</hrm:houseNumber>

</mailAddress>


<bloodPressureReading xmlns="http://who.org/medical">

<dateOfReading>2008-12-31</dateOfReading>

<systolicPressure>125</ systolicPressure>

<diastolicPressure>85</diastolicPressure>

<hospital:age xmlns:hospital="http://ourhospital.com/patients">

58</hospital:age>



<hrm:employeeId>64736</hrm:employeeId>

</bloodPressureReading>

</bloodpressureReadings>

</patient>

The child element age from the global default namespace that lives under

bloodPressureReading, has to be explicitly associated with the http://ourhospital.com/patient

namespace, as inside bloodPressureReading this namespace is no longer known as the default

namespace. The prefix hrm that was defined in the root element of the document is available

everywhere in the document and can therefore be used inside bloodPressureReading.

A namespace can be bound multiple times to different prefixes in the same document:


15-17


<patient xmlns="http://ourhospital.com/patient"

xmlns:hrm="http://www.hospital.org/hrm"

xmlns:staff="http://www.hospital.org/hrm">

...

<hrm:city></hrm:city>

<staff:city></staff:city>

The two city elements in this document have the exact same fully qualified name, as hrm

and staff both resolve to same URI. Prefixes are nothing but shortcuts for the full URI.

The concept of qualified names and namespaces not only applies to elements but to attributes as

well. An attribute not explicitly associated with a namespace via a namespace prefix is not in any

namespace (which is amounts to more or less the same thing as a big universal namespace with

an empty string as identifier). Most attributes are in this unqualified state. However, by prefixing

its name, an attribute can be associated with any namespace, potentially different from the

namespace of its owning element.

<hospital:doctorVisit priority="normal" calendar:dateOfVisit="2008-12-31"

xmlns:calendar="http://www.InternationalCalendarTaskForce.org">

Here we see a doctorVisit element from a namespace bound to the prefix hospital. It has

two attributes: priority and dateOfVisit. The first is not in any namespace. The dateOfVisit

attribute is associated with some specific namespace apparently linked to the fictitious

International Calendar Task Force.

XSD - XML Schema Definition

The provisional service interface definition specifies an input and an output parameter. It is

implied that these are both XML messages.


8-18

<operation name="getPatientRecord">

<input message="PatientIdentificationInputMessage"/>

<output message="PatientDataRecordOutputMessage"/>

However, we have not yet determined how these messages are to be constructed. In general,

when we deal with XML documents, we know that they will follow the XML grammar rules.

Any well-formed XML document has a single root element, a tree structure with properly opened

and closed element tags, text content and attributes. But this is too little specific to start

exchanging meaningful information or build software to process the XML documents. We need

more specific rules to describe the structure, the data types and other constraints for the XML

document. Without them, we know little more than a database developer who knows a relational

database is used, but does not have a database design.

The data model for XML documents is created using XML Schema Definitions - or XSDs. An

XSD is an XML document - readable to humans and software - that describes the vocabulary for

XML elements and attributes. Once we have the XSD for the XML documents we will be

dealing with, we can:

determine the validity of XML messages

start building the software that needs to process the XML - as we know what information

to expect and where to find it in the document

Most (SOA) development tools can interpret XSDs. Based on these designs for the XML

documents, they can do things like:

Generate XML documents according to the Schema Definitions

Support editing XML documents (with Code Completion and Instant Validation)

Generate a User Interface for presenting and manipulating the content of XML

documents


15-19

Generate PL/SQL records or Java Classes that provide the native representation of the

XML document - as well as the code to unmarshall and marshall the XML documents to

and from these native objects

Support creation of XPath queries for extracting information from XML documents

based on the XSD

Allow visual construction of XSLT transformations from one XSD to another

XSD documents define for a specific collection of XML Elements

Structure: elements, child elements, attributes and the order of all of these

Types: primitive (built in) and user defined

Rules or Constraints: default values, number of occurrences of child elements, valid

value range or allowable values for attributes, optionality and updateability

The table below lists the most important primitive data types define in the XSD

specification (see XML Schema Part 2: Datatypes Second Edition

http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/datatypes.html for all

details):

String date

boolean time

Float timeinstant

Double timeduration

Decimal recurringinstant

Integer uri-reference

non-positive integer byte

negative integer long


8-20

Int binary

Short token

XML Schema Definitions

Let‟s look at a simple XSD document. It specifies the address element in the

http://www.hospital.org/hrm namespace - defined through the targetNamespace attribute in the

schema element. This means that any occurrence of this {http://www.hospital.org/hrm }address

element, should conform to the rules in this XSD. The XML elements in this document that are

part of the XSD vocabulary itself are all from the namespace

http://www.w3.org/2001/XMLSchema, bound to the xsd prefix.

<?xml version="1.0" encoding="utf-8" ?>


xmlns="http://www.hospital.org/hrm"

targetNamespace="http://www.hospital.org/hrm"


<xsd:element name="address" type="physicalAddress"/>

<xsd:complexType name="physicalAddress">

<xsd:sequence>

<xsd:element name="postalCode" type="xsd:string"/>

<xsd:element name="city" type="xsd:string"/>

<xsd:element name="state" type="xsd:string" minOccurs="0"/>

<xsd:element name="country" type="countryCode"/>

<xsd:choice>

<xsd:sequence>

<xsd:element name="street" type="xsd:string"/>

<xsd:element name="houseNumber" type="xsd:string"/>


15-21

</xsd:sequence>

<xsd:element name="poBox" type="xsd:string" />

</xsd:choice>

</xsd:sequence>

<xsd:attribute name="typeOfAddress" type="xsd:string" />

</xsd:complexType>

<xsd:simpleType name="countryCode">

<xsd:restriction base="xsd:string">

<xsd:maxLength value="2"/>

<xsd:enumeration value="nl"/>

<xsd:enumeration value="us"/>

<xsd:enumeration value="de"/>

<xsd:enumeration value="be"/>

<xsd:enumeration value="mx"/>

<xsd:enumeration value="it"/>

<xsd:enumeration value="dk"/>

</xsd:restriction>

</xsd:simpleType>

</xsd:schema>


8-22

XSD compared to UML Class Model and Entity Relationship Diagram

The XSD declares the address element, based on the physicalAddress type. Next comes the

definition of this complex type. It contains a number of child elements such as postalCode, city,

state and country. These must occur in this order. However, the state element is optional. The

country element is based on a simpleType, countryCode. The countryCode type is based on the

built in simpleType string. Two restrictions are defined: the countryCode is a string of no more

than two characters and the value of countryCode must be one of the values defined in the

enumerations. Note: the first restriction is not very meaningful considering this second rule…

The physcialAddressType then contains either a poBox element or a street and houseNumber .

The xsd:choice element specifies this mutual exclusiveness. Finally, the physicalAddressType

also declares an attribute called typeOfAddress, a string.


15-23

An XML instance document with the {http://www.hospital.org/hrm }address element has to

abide by the rules laid down in the XSD definition - to be considered valid by XML processors

that are aware of that schema:


<address typeOfAddress="emergencyContact" xmlns="http://www.hospital.org/hrm">

<postalCode>3456</postalCode>

<city>Luik</city>

<country>be</country>

<street>Waffle Avenue</street>

<houseNumber>123</houseNumber>

</address>

A very special element we can use in an XSD document is the any element. We use it to specify

the occurrence of a block of well-formed XML - XML content that conforms to the XML syntax

rules - about which we otherwise almost nothing.

The next snippet specifies that inside the patientType there can be an attachment element that

contains well formed XML. What the structure or vocabulary for that content is unknown - it can

be anything.

<xsd:complexType name="patientType">

<xsd:sequence>

<xsd:element name="attachment" minOccurs="0">

<xsd:complexType>

<xsd:sequence>

<xsd:any minOccurs="1"/>

</xsd:sequence>

</xsd:complexType>

</xsd:element>


8-24

In addition to the any element, there is the anyType type that can be used to specify both

elements and attributes. This type does not constrain values in any way - and can be used for

example when we have too little information or control to enforce a more specific type.

A complex type can be defined as an extension of an existing complex type - adding new

elements to the set already defined in the base type. For example:

<xsd:complexType name="geoAddress">

<xsd:complexContent>

<xsd:extension base="physicalAddress">

<xsd:sequence>

<xsd:element name="geoCode" type="xsd:string"/>

</xsd:sequence>

</xsd:extension>

</xsd:complexContent>

</xsd:complexType>

Creating an element based on another element

We have seen how an element can be based on a simpleType or complexType definition

through the type attribute. The type needs to be a global type - that means a direct child of the

schema element. Instead of basing an element on a type, we can also define an element as the

image of another element. Suppose for example the imported Administration.xsd document

contains a global element called bankAccount with embedded complexType. Now we want to

define a child element bankAccount for the patientType, that has the exact same structure. We do

not have to replicate the element from the imported schema, we can refer to that element, like

this:


15-25





targetNamespace="http://ourhospital.com/patient">

<xsd:import schemaLocation="Administration.xsd"

namespace="http://www.hospital.org/hrm"/>

<xsd:element name="patient" type="patientType" />


<xsd:sequence>

...

<xsd:element name="primaryBankAccount" ref="hrm:bankAccount" minOccurs="0"

maxOccurs="3"/>

The ref attribute declares for the element it belongs to a reference to another element on whose

definition it is based.

Defining Constraints in Schema Definitions

The XSD specification provides a number of ways in which we can define constraints -

the XML counterparts of Unique Key, Foreign Key and Check Constraints as we know them in

the Oracle database. For elements we can specify the minOccurs and maxOccurs - defining thus

the optionality and cardinality. We can also indicate a default value for elements. The fixed

attribute can be used on an element to indicate that its value cannot be changed.

We have seen how the simpleType countryCode was declared to create a restricted

variation on the string type. We can define new simpleType elements that are based on existing

type and add constraints to it. Such constraints include a set of allowable values (such as is the

case for countryCode), a valid range, a regular pattern expression, the minimum and maximum

length and the total number of digits.

We can for example define a new type to base email address elements on:


8-26

<xsd:element name="emailAddress" type="emailAddressType"/>

...

<xsd:simpleType name="emailAddressType">

<xsd:restriction base="xsd:token">

<xsd:pattern value="([\.a-zA-Z0-9_-])+@([a-zA-Z0-9_-])+(([a-zA-Z0-9_-

])*\.([a-zA-Z0-9_-])+)+"/>

</xsd:restriction>

</xsd:simpleType>

The key, unique and keyref elements allow us to declare identity, uniqueness and

referential constraints. Through a key we can specify for an element which of its fields provide(s)

an identifying, referenceable value. With unique we declare uniqueness for one field or a

combination of fields. With keyref we can indicate a reference from an element to the key of

another (or the same) element.

<xsd:unique name="patientUniquenessConstraint">

<xsd:selector xpath=".//patient"/>

<xsd:field xpath="firstName"/>

<xsd:field xpath="lastName"/>

</xsd:unique>

This snippet declares a uniqueness constraint for the patient element on the combination

of the firstName and lastName child elements. With the frequent use of John Doe for otherwise

hitherto unidentified patients, this constraint will probably not turn out to be a realistic one. Note

that XPath is an XML query language that we discuss later in this book.

A complex type can be defined as an extension of an existing complex type - adding new

elements to the set already defined in the base type. For example:


15-27

<xsd:complexType name="geoAddress">

<xsd:complexContent>

<xsd:extension base="physicalAddress">

<xsd:sequence>

<xsd:element name="geoCode" type="xsd:string"/>

</xsd:sequence>

</xsd:extension>

</xsd:complexContent>

</xsd:complexType>

Associating XML document with XSDs

The XML processor will typically know of one or multiple XSD document that have been

registered with it. These XSDs describe elements in namespaces - with each XSD providing the

specification for one or more fully qualified elements. When processing an XML instance

document, the QName of the elements in the document is compared with this list of registered

schema based elements. Any element in the XML instance document that can be matched will be

validated against the schema definition.


8-28

XSD documents describing elements in Namespaces - implicitly referenced by XML

instance documents

Alternatively, the XML instance document can contain an explicit reference to one or more XSD

definitions. Some tools seem to prefer this explicit association

<address xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://www.hospital.org/hrm Administration.xsd"

xmlns="http://www.hospital.org/hrm">

<postalCode>...

The hint about the schema location is passed in the form of a schemaLocation attribute

that is defined in the http://www.w3.org/2001/XMLSchema-instance namespace. The attribute is


15-29

included in the root element of the instance document, and has to be preceded by a namespace

binding - usually to the prefix xsi.

Managing XSDs and XSD dependencies

We use XSD documents to describe the XML vocabulary we want to use in a specific

business domain. Of course, such domains can be quite large with substantial numbers of

elements. Fortunately, we do not have stick to single XSD document with all elements in any

single domain in a single file. The XSD specification describes the include and import elements

that allow us to manage element and type definitions in multiple documents. For example, we

can create an XSD document VeryPatient.xsd which contains the patient element that forms the

basis for the PatientDataRecordOutputMessage used in the getPatientRecord service operation.

...

<xsd:element name="patient" type="patientType" />



8-30

<xsd:sequence>

<xsd:element name="personal" type="personNameType" maxOccurs="1"

minOccurs="1"/>

<xsd:element name="mailAddress" type="hrm:physicalAddress" minOccurs="1"

maxOccurs="3"/>

...

The patient element is based on the patientType complexType that contains among

others the mailAddress element which is based on hrm:physicalAddress type - from a different

namespace and defined in a different XSD document.

The physicalAddress type is bound to the {http://www.hospital.org/hrm} namespace (its

prefix hrm is declared at the top of the XSD document:




The definition for this type is in a separate XSD document, that is imported into the

VeryPatient.xsd schema:

<xsd:import schemaLocation="Administration.xsd"

namespace="http://www.hospital.org/hrm"/>

The import element tells any processor interpreting the XSD document in which it is

contained that it should read the contents of the imported XSD document and merge it with the

current XSD‟s definitions. This means that it is transparent to anyone using the VeryPatient.xsd

whether the physicalAddress type was in that XSD itself or in some imported XSD.

Similar to the xsd:import, the xsd:include instruction also instructs XSD processors to

read XSD element and type definitions from the indicated external XSD document. However,

include is used for XSDs with the same targetNamespace as the base XSD, while import is used

with external schema definitions describing elements from a different namespace.


15-31

Managing XSD documents is very important, much like the management of the corporate

data model. The XSD documents form an important asset for an organization that adopts SOA.

Together the XSDs describe all business data of interest - at the very least the data that is

interchanged between systems and published by (web) services.

The ability to link XSDs is essential in building a structure of Schema Definitions that is

manageable. Many organizations use hierarchies of XSD documents. At the root you will find

entities or business objects from specific business domains. The namespace associated with the

Schema Definition derives its name from the business domain.

Extension, refinement and composition of elements and types is done at lower levels in the

XSD hierarchy in XSD documents that import the business objects. More specific type and

element definitions that are used for particular applications and services are defined in yet

lower levels, again importing from the more generic Schema Definitions. This approach

allows for OO like reuse and inheritance of business object definitions. Namespace visibility in

the XML instance document

Through the import of the WHO-medic.xsd we have made the bloodPressureReading

element available in the VeryPatient.xsd document. It allows us to specify how instance XML

documents can define bloodReading elements inside the bloodReadings child in the patient

element.

JDeveloper has support for the creation of XSD documents. From the New Gallery,

Category XML, the option XML Schema can be used to create an XSD. The XSD editor is fully

aware of the structure of an XSD document and provides instant validation and code completion,

among other features. The editor offers a design view in addition to the source view.

When you create a new XML document in JDeveloper, you can base it off an XSD file

and have JDeveloper generate the document structure with all elements and attributes already

inserted. It will provide instant validation, drag & drop from component pallet support and code

completion, making the XML editing a productive task. Note that these features are available for

any XML document that is associated with XSD documents, either explicitly through the

xsi:schemaLocation attribute or because of namespaces in the XML document that are described

in XSD documents that have been registered with JDeveloper.


8-32

The XML Schema Definition is to XML what the Class Diagram is to Java and the ERD

or logical data design to relational databases. Most of the same logic and steps are involved with

each of these data design techniques. In fact, it is fairly easy to largely convert data designs

created in one technique into one of the others. And this is needed on a regular basis, for example

when we go from one domain - the implementation of a service in Java or SQL & PL/SQL - to

the other - service calls in XML.

Creating and Editing XML documents in JDeveloper 11g

Creating XML documents is a task usually performed for us by automated means. Such

means include text-file to XML converters, use of SQL/XML queries, Java programs that

construct XML documents from string data or Word processors that save files in XML format.

However, manually creating XML files is occasionally required of us, for example for testing

purposes, management of configuration files and the development of XML documents that .

In addition to specialized XML editors of which there are plenty available, most IDEs

including JDeveloper have fairly advanced XML editing capabilities. JDeveloper 11g‟s XML

Editor has useful features such a checks on well-formedness (does the document comply with the

XML syntax rules) and validity (does the document satisfy the rules laid down in the XML

Schema Definition, see next section) and productivity enhancers like XML element tag

completion, reformat and code completion.

JDeveloper can also create an XML document based on what is called an XML Schema

Definition (XSD), a document that describes the data design of XML elements. JDeveloper

creates such an XML document will all required structure (elements and attributes) already in

place - though without actual content and values. The next section introduces the XSD

phenomenon.

Create XML Document

From the New Gallery, choose XML Document and press OK.


15-33

Enter the name for the XML Document: Calendar.xml and press OK.

The XML Editor opens with an (almost) empty XML Document.

Now create a small XML Document that contains some birthdays:


8-34

Note: the XML Editor can help us a little. We can make it add the end tag for any

element we add to the document, saving some typing. We activate that behavior from the

Preferences window:


15-35

Note: if you do not like the layout of your XML document, you can quickly have it

reformatted using the Reformat option in the Right Mouse Button Menu:

The result:

The XML Editor has one other quite important feature: it checks the correctness of the XML

document. It will inform you in the structure window (or when you build the file or the project)

of violations against rules of Well-Formedness.


8-36

At this point, the editor does not know about Validity, since we have not specified what

valid is.

Demo: Round Trip Data Design - Java to XSD to Database and vice

versa

We will make a round trip, from a Java Class model to an XSD and an Oracle Database Design.

Then, from the Database Design we will create another XSD document that finally is used to

produce Java class definitions. Note: this round trip is not something you would knowingly do -

it merely goes to show the similarities between the three data design approaches involved.

Step one: from Java to XSD

First we create the Java class model - a simple variation on the Patient data record. A Patient

class with two private collection properties - bloodPressureReadings and doctorVisits. The

BloodPressureReading class contains some properties pertaining individual blood pressure


15-37

readings, and the same applies to the DoctorVisit class. Finally there is a Service class -

GetPatientDataRecordService that has a getPatientDataRecord() method that returns a Patient

object.

Simplified Patient Java Class Model

There are several automated ways to turn a class model into an XSD document. Let‟s use a very

simple one: the Create Web Service wizard in JDeveloper. Simply select Create Web Service

from the Right Mouse Button (RMB) Menu. In the wizard that opens, select the first Deployment

Platform option (J2EE 1.4 with support for JSR 181 JAX-RPC Annotations). Accept the default

Service and Port-name - we do not care about those at this point. Ensure that in the step Message

Format the checkbox Generate Schema with Qualified Elements is checked. Press Finish.

JDeveloper will now generate a number of files to construct a Web Service based on

GetPatientDataRecordService class. The one we are interested in is called

GetPatientDataRecordService.wsdl. When you open that file, the types element contains the

XSD definition for elements called Patient, BloodPressureReading and DoctorVisit - as well as

types list and collection for a fairly complex implementation of the collections

bloodPressureReadings and doctorVisits, that tries to do full justice to the List interface.


8-38

An alternative way is using the JAXB facilities. With the next Java code snippet, you can also

generate an XSD document for the classes in the Simplified Java Class Model:

public static void main(String[] args) throws JAXBException, IOException {

class MySchemaOutputResolver extends SchemaOutputResolver {

File baseDir = new File(".");

public Result createOutput(String namespaceUri,

String suggestedFileName) throws

IOException {

return new StreamResult(new File(baseDir, suggestedFileName));

}

}

JAXBContext context = JAXBContext.newInstance(Patient.class,

BloodPressureReading.class, DoctorVisit.class);

context.generateSchema(new MySchemaOutputResolver());

}

We can easily create an isolated XSD document based on the types section in the WSDL.


15-39

Graphical view of the Simplified Patient XSD document


8-40

Registering the XSD with the database

For our next stage we go to the database. The Oracle RDBMS comes with XMLDB, a rich

infrastructure for dealing with XML. One of the things XMLDB knows how to do is store and

retrieve XML based data and bridge the gap between the world of SQL and relational data on the

one hand and XML based data and querying (XPath and XQuery) on the other.

XML documents can be stored by XMLDB as documents - or can be shredded into individual

relational bits and pieces - with basically mapping an XML Element to a relational Table. In

order to be able to store XML in this latter, relational way, we need register an XSD document

with the database. XMLDB will then generate a bunch of tables that can hold and produce the

data from XML documents based on that Schema Definition. It also creates a number of database

Object Types act as the glue between the XML and the tables.

To register a Schema Definition with the database, perform the following call:

BEGIN

DBMS_XMLSCHEMA.registerSchema

( schemaurl => 'http://our.hospital.com/PatientRoundTripXSDtoDB.xsd'

, schemadoc => '<xsd:schema ... </xsd:schema>' -- the actual contents of the

XSD document

, local => TRUE

, gentypes => TRUE

, genbean => FALSE

, gentables => TRUE

);

END;

This call will create tables and object types in the database schema for the user who executes this

operation. The XSD document itself will be registered and can be looked up in the data

dictionary view USER_XML_SCHEMAS.


15-41

Note: you can add annotations to the XML Schema that you register to instruct the registration

mechanism in use of specific database types, adding database constraints and overriding naming

derivation with names of your choosing.

Another way of creating the database design could be using an XSL-T stylesheet that transforms

the XSD source into a DDL output. See for an example this blog article:

http://annlewkowicz.blogspot.com/2008/01/create-ddl-from-xsd-file-part-ii.html .

Of course the mapping from XSD to Database is one you could easily do by hand as well - and

probably better than any automated tool. Elements with child-elements or attributes typically will

become tables, child elements detail tables with a foreign key to their parent element. Elements

without content or attributes and attributes convert to columns. Some of the XSD constraints can

be turned into database constraints , such as NOT NULL constraints - while others cannot be

implemented using declarative constraints - such as minOccurrences > 1.

From database design to XSD

Now for the return trip. Starting from the database we can have an XSD generated, based on

Object Types or Table and View definitions. Several tools can do this for you - such as Oracle

JPublisher, XMLSpy and XMLFox. The Oracle database itself also provides some support: the

DBMS_XMLSCHEMA package provides the generateschema function. It can be called to

generate an XSD document for an object type and all of its associated types. For example with

these object types:

create type hospital_visit_t as object

( date_of_visit date

, summary varchar2(4000)

)

create type hospital_visit_tbl_t as table of hospital_visit_t

create type patient_t as object

( id number(10)

, name varchar2(200)


8-42

, initials varchar2(10)

, birthdate date

, hospital_visits hospital_visit_tbl_t

)

This call

SELECT DBMS_XMLSCHEMA.generateschema('SCOTT', 'PATIENT_T') FROM DUAL

returns an XSD document that describes this data structure very well.

Producing Java Classes from an XSD

The last stage of our voyage is from XSD to Java Classes. Again, several options are available to

map from XSD definitions to Java Classes. We will use JAXB 2.0, the Java Specification for

XML Binding and more specifically the Toplink/EclipseLink support for Java/XML mapping. In

JDeveloper, you can select the option JAXB 2.0 Content Model from XML Schema, from the

Toplink/JPA category in the New Gallery. A wizard appears that asks you for the location of the

XSD document. When you select the XSD and complete the wizard, it will generate Java Classes

that are derived from the XSD type and element definitions.

Using XPath to query XML data

XML Path Language 1.0 (commonly referred to as XPath) is a W3C standard. XPath is a

language for addressing (finding and either retrieving or manipulating) values in XML sources.

See http://www.w3.org/TR/xpath for the specification.

XPath is used in BPEL process in Assign activities. XPath is also a key element of XML

Stylesheet Language Transformations (XSLT), is used in SCA and SDO (Service Data Objects),

core to XQuery and heavily used in SQL/XML, the SQL variant for dealing with XML in

relational databases. XPath is supported in Javascript, through the XMLType in PL/SQL and for

example using JAXP in Java.


15-43

From the W3C specification: “XPath gets its name from its use of a path notation - as in

URLs - for navigating through the hierarchical structure of an XML document.[..] XPath models

an XML document as a tree of nodes. There are different types of nodes, including element

nodes, attribute nodes and text nodes. XPath defines a way to compute a string-value for each

type of node.”

Using XPath‟s notation, we construct an expression (location path) that accesses a node

or set of nodes, possibly with their child nodes, in the XML source we have the expression act

on.

Take this XPath expression that addresses all name nodes under the root patient element:

/patient/name

and apply it to this XML document:

<patient>

<name>John Doe</name>

<physicalCharacteristic staffMember="Doctor X. Zhivago">

<dateOfMeasurement>2010-11-22</dateOfMeasurement>

<whatWasMeasured>BodyHeight</whatWasMeasured>

<measuredValue>184</measuredValue>

<unitOfMeasurement>cm</unitOfMeasurement>

</physicalCharacteristic>

<hospitalVisit cost="312.54">

<dateOfVisit>2010-11-22</dateOfVisit>

<summary>Dead upon Arrival.</summary>

</hospitalVisit>



<summary>kidney surgery</summary>


8-44

</hospitalVisit>

</patient>

The result will be <name>John Doe</name>, as that is the only name node available.

Note: every location step - a string between two virgules or backslash characters - in the XPath

expression evaluates to an XML node set (which can be empty, can contain a single node or may

contain multiple nodes). If I want to have the value of the <name> node, or better stated: the

value of text node that is the child of the <name> node, the XPath expression should be:

/patient/name/text()

XPath expressions address attributes using the @ operator. To get the cost for every

hospitalVisit in the document, use:

/patient/hospitalVisit/@cost

To access a specific element in a node set, we can use an array like notation using the

square brackets. For example the expression:

/patient/hospitalVisit[2]/dateOfVisit

Returns <dateOfVisit>2010-12-14</dateOfVisit>, as that is the dataOfVisit child element

in the second hospitalVisit element. Note: the indexing is not zero-based, like Java, but starts at

1.

This notation by the way is short for:

/patient/hospitalVisit[position()=2]/dateOfVisit

Here we see that the square brackets are a construction for specifying a Boolean

expression that must evaluate to true for a node in order to be returned by the XPath processor. It

is important to realize that such search conditions can be applied to every step in the location


15-45

path. The function position() by the way is one of the many built-in XPath functions that can be

used in XPath expressions. XPath supports operands and functions to manipulate values, and can

be extended with vendor or even user defined functions. The Oracle SOA Suite contains a

substantial number of additional XPath functions, all readily available from the XPath expression

builder tool.

A slightly more complex example that returns all hospitalVisit elements for a patient

whose gender is M(ale), where the visit was more expensive than 400 and its summary contains

the word “kidney”. Note that the function translate is used here to cater for the fact that kidney

may have been spelled with a capital K. XPath 1.0 does not have a function that converts a

string to only lowercase characters.

/patient[gender='M']/hospitalVisit[@cost > 400 and

contains(translate(summary,'K','k'),'kidney')]

The result of this XPath query:



<summary>kidney surgery.</summary>

</hospitalVisit>

XPath has a lot more to offer than these examples illustrate. Using no fewer than thirteen

axis specifications for example, XPath expression can move between nodes in many advanced

ways to retrieve data according to very complex requirements.

JDeveloper has built in XPath search support,. When an XML document is open in the

source editor - including XSD, WSDL, SOAP and even JSPX files - the option XPath Search is

available from the Search option in the main menu. In the XPath Search tool, an XPath

expression is entered, along with possible namespace details, and the search can be executed.


8-46

XSLT - XML Stylesheet Language for Transformations

XML documents represent data, organized in some predefined, structured way. XML

documents are used frequently to communicate data, between automated environments and

potentially across technology, platform, protocol and vendor borders as few mechanism for

recording data are as generic and technology-free as XML. However, even though a plethora of

tools, environments, platforms and applications know how to interpret XML in general does not

necessarily mean they all work with the same XSD definitions as well. In many situations, data

in XML documents needs to be transformed before it can be sent or processed. Note that usually

this transformation takes an XML document and produces another XML document. Source and

target documents are generally based on different XSD documents.

XSLT is a language, itself written in XML, that prescribes the XML elements and

attributes to produce and the values for these to write, usually queried from the source document.

Data is queried from the source document using XPath expressions.

15-47

XSLT processing takes an XML source document and an XSLT stylesheet, and produces

XML output document. The XSLT stylesheet: contains static XML to send into the output, uses

XPath expressions to get data from the XML source and uses XSLT logic (if-else) and operators

(for-each) to process the XML source. The XML output can be XHTML, SVG, RSS, XSL-FO

(=> PDF), JSPX or any other XSD based XML.

At the heart of XSLT processing are templates: snippets that can be matched against

sections in the source document based on XPath expressions. When a template is matched, the

contents of the template is processed.

<?xml version="1.0"?>

<xsl:stylesheet ...>

<xsl:template match="XPath"/>



</xsl:template>

</xsl:stylesheet>

An XSLT stylesheet is an XML document containing: a <xsl:stylesheet> root element

declaring the xsl namespace prefix with http://www.w3.org/1999/XSL/Transform and one or

more <xsl:template> elements and other XSL elements defining transformation rules.

The XSLT stylesheet typically contains the root template - a template that matches the

root node of the source document - and starts the creation of the output document:


8-48

<xsl:template match="/">

<root>output</root>

</xsl:template>

This template will match against the root node of any source document and will produce

the following result document (always the same, regardless of the contents and size of the source

document):

<root>output</root>

If we take the Patient document as the source again:

<patient>

<name>John Doe</name>

<physicalCharacteristic staffMember="Doctor X. Zhivago">

<dateOfMeasurement>2010-11-22</dateOfMeasurement>

<whatWasMeasured>BodyHeight</whatWasMeasured>

<measuredValue>184</measuredValue>

<unitOfMeasurement>cm</unitOfMeasurement>

</physicalCharacteristic>



<summary>Dead upon Arrival.</summary>

</hospitalVisit>



<summary>kidney surgery</summary>

</hospitalVisit>

</patient>


15-49

and try to design the XSLT stylesheet that will create an output document that looks as

follows:

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

<customer name="John Doe" height="184">

<consults>

<consult>

<notes>Dead upon Arrival.</notes>

</consult>

<consult>

<notes>kidney surgery</notes>

<specialDate/>

</consult>

</consults>

</customer>

We will come up with the following XSLT stylesheet:


<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:template match="/">

<customer>

<xsl:attribute name="name">

<xsl:value-of select="/patient/name"/>

</xsl:attribute>

<xsl:attribute name="height">

<xsl:value-of

select="//physicalCharacteristic[whatWasMeasured/text()='BodyHeight']/measuredValu

e"/>


8-50

</xsl:attribute>

<consults>

<xsl:for-each select="//hospitalVisit">

<consult>

<notes>

<xsl:value-of select="summary"/>

</notes>

<xsl:if test="dateOfVisit='2010-12-14'">

<specialDate/>

</xsl:if>

</consult>

</xsl:for-each>

</consults>

</customer>

</xsl:template>

</xsl:stylesheet>

You will notice the template that matches on the XPath expression '/' - the root note in the

source document. This template creates the customer element in the result document. Then it

creates a new attribute - through the xsl:attribute instruction to the XSLT processor - that has

name as its name and the value of the (first) name element under the (first) patient element under

the root. A second attribute called height is create on the customer element. The value for this

attribute is derived using a somewhat interesting XPath expression:

//physicalCharacteristic[whatWasMeasured/text()='BodyHeight']/measuredValue. It queries the

value of the measuredValue child element under the physicalCharacteristic element that has

another child element whatWasMeasured with a text value of BodyHeight.

The template then creates the <consults> element. Using the xsl:forEach instruction, it

queries the collection of hospitalVisit child elements under the current root. (The <xsl:for-each

select=""> element instructs the XSLT processor to loop over the node set returned by the XPath


15-51

expression in the select attribute) For each such child element found, it creates a consult element

in the output document. This element gets a notes child element for which the value is queried

through the xsl:value-of instruction that uses the XPath query expression summary -the value of

the element called summary.

Sometimes a section of the XSLT tree should only be processed under certain conditions.

The instruction <xsl:if test=""> can be used to build in that conditionality. The test attribute

contains an XPath expression that should evaluate to a boolean value. In this case we assume that

14th of December is a very special day. When a visit to the hospital takes place on that day, it

should be highlighted - by including a <specialDate> element.

Miscellaneous

Creating comments is done using <xsl:comment>. Use Include and Import to add XSLT

templates from external documents (just like XSD). XSLT functions are available like

document(), current(), format-number(), system-property(), key() etc - in addition to the over 100

built in XPath functions. Extensible - support for addition of user defined functions - in most

XSLT processors (add custom functions). XSLT is supported in JavaScript, Java, Oracle

Database, C# and many other languages.

XSL-FO is XSL-T‟s little brother for describing the layout of a document (FO=

Formatting Objects). XSL-FO can be converted to PDF, SVG, RTF and others

JDeveloper support for XSD and XSLT

JDeveloper provides a number of advanced features - otherwise found in commercial

XML editors - that make life a lot easier. My personal favorites are 'Create XML Document from

XML Schema' and even more 'Create XML Schema from XML Document'. The latter inspects

an XML instance document and derives an XSD that describes the structure of the XML

document. It is a bit like taking the outcome of a complex SQL query can creating the DDL to

create the underlying tables. The former feature - create XML Document from XML Schema - is

quite useful too: it generates an XML document with sample data based on a selected XSD

document.


8-52

JDeveloper provides the XSLT Data Mapper tool that enables you to create an xsl file to

transform data from one XML Schema to another. An XSL Map is an annotated XSL Stylesheet

- that JDeveloper can represent and edit in a visual way.

Web Services

We now take a closer look at the interface definitions that are drawn up for web service.

We have earlier on seen the beginning of this contract:

<operation name="getPatientRecord">

<input message="PatientIdentificationInputMessage"/>

<output message="PatientDataRecordOutputMessage"/>

<fault message="UnknownPatientIdFaultMessage" name="UnknownPatientId"/>


15-53

<fault message="NoUniquePatientMatchFaultMessage"

name="NoUniquePatientMatch"/>

</operation>

This snippet is part of a so called WSDL document (WSDL is Web Service Definition

Language, frequently pronounced as whiz-dul). WSDL is a W3C standard, originally for

defining Web Services but today used for almost any kind of service - including Java interfaces,

Database APIs and RESTful services (with WSDL 2.0, see also Chapter 17). A WSDL document

describes the functional interface, including operations, input and output messages and faults. It

also describes the implementations of the interface, or rather the physical endpoint (address)

where the service can be invoked in combination with the protocol to be used for invoking the

service.

An interface can be bound to multiple to multiple protocols - such as SOAP, HTTP or

MIME- and each binding can be exposed at one or more endpoints. WSDL has extension points

that allow definition of other binding types, for example based on Java, JCA and JMS. Note that

we will focus on the 1.1 release of WSDL supported by the SOA Suite.

Abstract Service Interface: the portType

We have talked about a specific operation the Patient Data Service should provide:

getPatientRecord. However, his Service may very well offer additional operations as well, just as

a Java Class may contain (and typically does) multiple methods and a PL/SQL Package provides

more than one procedure. The WSDL document contains the portType element, a named set of

abstract operations and the abstract messages (input, output and fault) involved with those

operations. Faults (referring to SOAP faults here) are the web service equivalent of the exception

in languages like PL/SQL or Java. The portType element is very similar to the Java Interface

artifact, as it specifies the abstract service interface that is on offer from the WebService. It is up

to the port elements to hook up the implementation of this abstract interface and its operations.

<portType name="SimplePatientRecordDataInterface">

<operation name="getPatientDataRecord">

<input message="tns:PatientIdentityRequestMessage"/>


8-54

<output message="tns:PatientDataRecord"/>

</operation>

</portType>

Message Definition

We are nowhere near the point where we can or should start talking about the

implementation details such as the end point for his service. We first need to further specify the

functionality of the getPatientRecord operation, by defining what the structure will be of the

input and output messages.

The input and output element each have a message attribute. This attribute refers to a

message element defined in the WSDL document or an external XSD:

<message name="PatientIdentificationInputMessage">

<part name="PatientIdentificationPart"

element="imp1:PatientIdentification"/>

</message>

<message name="PatientDataRecordOutputMessage">

<part name="PatientDataRecordPart" element="imp1:PatientDataRecord"/>

</message>

A message can consist of multiple parts. Each part can be seen to represent a parameter in

the operation request or response. Multiple part elements can be used when a message has

several unrelated or at least logically separate units.

For the “document literal (wrapped)” style service (which we will work with most of the

time), the WS-I Basic Profile specifies that at most one part is allowed. In general it seems that

unless there is a real need for using multi-part messages, sticking with single-part messages is

less complex and less likely to have you run into tool limitations.


15-55

Each part is based on either a type (for Remote Procedure Call or RPC style Services) or

an element (for the document literal style services we will primarily deal with) that is defined in

the <types> section of the WSDL document. This section can contain XSD style element and

type definitions, or import one or more external XSD documents. For reasons of loosely coupling

and reuse of type definitions as well as keeping the WSDL document readable, working with

external XSDs is preferable over including type definitions inside the WSDL document.

<types>

<schema attributeFormDefault="qualified" elementFormDefault="qualified"


xmlns="http://www.w3.org/2001/XMLSchema">

<import namespace="http://ourhospital.com/patient"

schemaLocation="Patient.xsd"/>

</schema>

</types>

Frank and Margaret need to flesh out the structure of the PatientIdentification and

PatientDataRecord elements in the Patient.xsd. When they have done so, they have the abstract

interface for the getPatientRecord operation in the PatientDataService. At that point, Frank and

his team can start working on the implementation - how to fulfill the contract - and Margaret‟s

team can commence with software invoking that service. Well, almost. The two first need to

agree on how the service will be called. The precise physical address can be determined later on,

but it would be useful to know the protocol via which the service is to be invoked.

Through the operation and message elements together with any referenced XSDs we have

specified the XML structure for the requests to and responses from the service. What we have

not described yet is how the request and the response are communicated. It‟s like agreeing on the

form that we will fill out and send to some agency to make a request but not discussing the

address we should send the form to - that is what the service and port- elements are for - nor


8-56

thinking about the envelope we should wrap the form in and the fact that we may need to provide

a return address to ever receive the reply from this agency if they cannot give one straightaway

but have to come back to it later.

While RESTful Service APIs are quickly becoming more popular, many tools including

the Oracle SOA Suite when it comes to external Web Service calls primarily speak SOAP

(formerly known as the Simple Object Access Protocol but today just referred to as SOAP).

SOAP - the XML transmission language

SOAP describes the meta-details for sending messages between service and requesters. It

is another W3C standard that describes the structure of an XML document, this time the XML

document that contains at its core a message being transmitted, enveloped by meta-data

pertaining to the transmission itself. Note: we discuss SOAP 1.2 as that is the default version

used in the Oracle 11g SOA Suite.

A SOAP message in its simplest form looks like this:

Structure of SOAP messages

The SOAP header can contain various types of meta-data, including addressing

information - for example the address to which send any replies -, transaction coordination


15-57

details and authorization tokens. Namespace can be declared at various levels, such as the root

Envelope element or the Header and Body elements. The Body element is the container for the

actual payload sent in the SOAP message. In the example below, the payload is the

{http://ourhospital.com/patient }patientIdentification root element with its contents.

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:ns1="http://ourhospital.com/patient">

<env:Header/>

<env:Body>

<ns1:patientIdentification>

<ns1:patientId>3232</ns1:patientId>

</ns1:patientIdentification>

</env:Body>

</env:Envelope>

Of course the structure of SOAP messages is the same, regardless of whether the

messages contain a request or a reply.

The How and Where in the WSDL contract

The Binding element in the WSDL document is used to describe the fact that the specific

operations in the service are callable via a specific protocol binding and data format. Several

options are available for bindings, including HTTP, MIME, JCA with SOAP being the most

prominent among them:

<binding name="PatientDataServiceSoapHttp" type="tns:

PatientDataServiceInterface">

<soap:binding style="document"

transport="http://schemas.xmlsoap.org/soap/http"/>


<soap:operation soapAction="getPatientDataRecord" />

<input>


8-58

<soap:body use="literal"/>

</input>

<output>


</output>

</operation>

</binding>

The type attribute in the binding element refers to a portType element - the element that

contains the abstract functional interface that declares the available operations. The binding

element links a portType to a protocol and a style of message formatting. In this case we have

defined the binding of the PatientDataServiceInterface portType to the SOAP protocol using a

document style message format.

The child element of the binding element - in this case soap:binding or

{http://schemas.xmlsoap.org/wsdl/soap/}binding since the prefix soap is bound to this

namespace - indicates the protocol. The soap:binding element specifies the format through the

style attribute. For the purpose of this book - and almost always in other cases - it will be set to

document. The alternative, rpc, is rapidly getting out of fashion. See this almost classic paper for

details: http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/ .

For each operation in the referenced portType that we want to support through the

binding, we need to include a child operation element inside soap:binding. The name attribute

on the operation element refers to the name of one of the operation inside the referenced

portType.

Note: This soap:operation element must also have a soapAction attribute when the

transport is http. The value specified for soapAction must be included in the HTTP Request

Header as SOAPAction.

The input and output elements are finally used to specify whether the SOAP binding has

a literal or encoded use for the parameters. We will always use literal - refer to the paper

mentioned above for details.


15-59

Overview of the structure of WSDL documents. Note the three sections that describe the

what [functionality is offered by the service], the how [can this functionality be invoked in

terms of protocol and message format] and where [at which physical end point can the

service be contacted] of the service

The WSDL document will be completed with the Service element that finally assigns

physical address details to each of the binding elements in the document. Here is the Service

element for the contract Frank and Maggie are drawing up:

<service name="PatientDataService">

<port name="PatientDataRecordServiceSoapHttpPort" binding="tns:

PatientDataServiceSoapHttp ">

<soap:address location="URL_To_Be_Defined"/>


8-60

</port>

</service>

This element associates a binding element with a physical end point. The binding tells us

how to invoke the service operations - which protocol and message format - and the port child of

the service element contains the details of the whereabouts of the deployed service

implementation.

However, note that Frank is at this point far from able to indicate the URL where his

service will reside, nor does Margaret need that information at this point. The location is

therefore not yet defined in the WSDL.

JDeveloper provides a WSDL editor, with both Source and Design view, the latter

offering a graphical overview of the WSDL with drag and drop support for adding elements to

the document. However neat this UI, you will probably find yourself inspecting and editing the

source code directly. By the way: most WSDL documents will be generated for you by the SOA

Suite design time environment, based on for example BPEL process and Mediator service

definitions.


15-61

The WSDL editor in JDeveloper

Demo - Create the simplest Web Service implementation

Once you have the complete WSDL and any referenced XSDs, you can start writing code

to call the web service (even if it does not yet exist). Calling a Web Service is supported by

libraries and platform infrastructure in many technology environments.

Let‟s assume a fairly simple WSDL document along the lines of the

PatientDataRecordService - but simpler, just to give you the idea. The WSDL document is

shown below. Let‟s see how to read it:

<definitions

targetNamespace="ourHospital.PatientData"

xmlns="http://schemas.xmlsoap.org/wsdl/"

xmlns:tns="ourHospital.PatientData"

xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"


8-62

xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"

xmlns:hospital="http://ourhospital.com/patient"

>

<types>

<schema attributeFormDefault="qualified" elementFormDefault="qualified"


xmlns="http://www.w3.org/2001/XMLSchema">

<import namespace="http://ourhospital.com/patient"

schemaLocation="SimplePatient.xsd"/>

</schema>

</types>

<message name="PatientIdentityRequestMessage">

<part name="in" element="hospital:patientIdentification"/>

</message>

<message name="PatientDataRecord">

<part name="return" element="hospital:patient"/>

</message>

<portType name="SimplePatientRecordDataInterface">


<input message="tns:PatientIdentityRequestMessage"/>

<output message="tns:PatientDataRecord"/>

</operation>

</portType>

<binding name="SimplePatientDataRecordServiceSoapHttp"

type="tns:SimplePatientRecordDataInterface">

<soap:binding style="document"

transport="http://schemas.xmlsoap.org/soap/http"/>


15-63


<soap:operation soapAction="getPatientData"/>

<input>


</input>

<output>


</output>

</operation>

</binding>

<service name="SimplePatientDataRecordService">

<port name="GetPatientDataRecordServiceSoapHttpPort"

binding="tns:SimplePatientDataRecordServiceSoapHttp">

<soap:address

location="http://host:port/hospital/patientservices/GetPatientDataRecordServiceSoa

pHttpPort"/>

</port>

</service>

</definitions>

The portType element contains the actual operation on offer in this service. Through the

message elements and the schema referenced from types we quickly get a feel for the input

parameters and the outcome of calling the operation.

The external SimplePatient.xsd document looks like this:





8-64



<xsd:element name="patientIdentification" type="patientIdType"/>

<xsd:element name="patient" type="patientType"/>

<xsd:complexType name="patientIdType">

<xsd:sequence>

<xsd:element name="patientId" type="xsd:integer"/>

</xsd:sequence>

</xsd:complexType>


<xsd:sequence>

<xsd:element name="name" type="xsd:string"/>

<xsd:element name="initials" type="xsd:string"/>

<xsd:element name="gender" type="genderType"/>

<xsd:element name="birthDate" type="xsd:date"/>

<xsd:element name="physicalCharacteristic" type="measurementType"

minOccurs="0" maxOccurs="unbounded"/>

<xsd:element name="hospitalVisit" type="hospitalVisit" minOccurs="0"

maxOccurs="unbounded"/>

</xsd:sequence>

</xsd:complexType>

<xsd:complexType name="measurementType">

<xsd:sequence>

<xsd:element name="dateOfMeasurement" type="xsd:date"/>

<xsd:element name="whatWasMeasured" type="xsd:string"/>

<xsd:element name="measuredValue" type="xsd:decimal"/>


15-65

<xsd:element name="unitOfMeasurement" type="xsd:string" minOccurs="0"/>

</xsd:sequence>

</xsd:complexType>

<xsd:complexType name="hospitalVisit">

<xsd:sequence>

<xsd:element name="dateOfVisit" type="xsd:date" maxOccurs="1"/>

<xsd:element name="summary" type="xsd:string"/>

</xsd:sequence>

</xsd:complexType>

<xsd:simpleType name="genderType">

<xsd:restriction base="xsd:string">

<xsd:enumeration value="M"/>

<xsd:numeration value="F"/>

</xsd:restriction>

</xsd:simpleType>

</xsd:schema>

We can ask for a PatientRecord by submitting the PatientId , an integer value. The

service may return to us an XML document that apparently contains patient details such as name,

initials, gender and birthdate, recent hospital visits and some physical characteristics that could

include weight, height, color of eyes.

The service is (to be) offered through the SOAP protocol - as we can see from the

binding element. The endpoint is not yet specified - so we do not know the actual URL where we

can call this service.

In fact, the service does not even exist at this point. Let‟s first do something about that.

JDeveloper helps us with the implementation of a Web Service: you can ask it to generate a

service implementation based on a WSDL document. All you have to add yourself is the Java


8-66

code that does the actual work. All the Web Service deployment details and XML to Java data

type mapping is taken care of.

When we select the WSDL file in the Application Navigator, we can find the option

Create Web Service in the Right Mouse Menu (RMB) menu. Pressing it brings up a wizard that

we can by and large accept the default values in. You may want to set a nicer package name in

which the Java Classes will be generated.

The central class generated by the Create Web Service wizard is PatientType - based on

the XSD Element by the same name. Its properties are defined as follows:

public class PatientType {

@XmlElement(required = true)

protected String name;


protected String initials;


protected GenderType gender;


@XmlSchemaType(name = "date")

protected XMLGregorianCalendar birthDate;

protected List<MeasurementType> physicalCharacteristic;

protected List<HospitalVisit> hospitalVisit;

The Annotations are part of the JAX-WS specification, part of JEE 5. They provide

additional type mapping instructions to the container in which the Web Service will be deployed.

It is now up to us to implement the Class SimplePatientRecordDataInterfaceImpl, more

specifically the method getPatientDataRecord that accepts a PatientIdType and returns a

PatientType:


15-67

public PatientType getPatientDataRecord(PatientIdType in)

We can both test and deploy the Web Service from the RMB menu, once we have

implemented this method.

Web Services once implemented can be called from different technology stacks - the

main raison d‟être for Web Services. Invoking the Web Service we have introduced above can be

done from for example PL/SQL and Java.

Tool for (test) invoking and (mock) implementing WebServices:

soapUI

A useful way, of trying out an existing Web Service as well as providing a quick mock service

implementation of a WSDL is through the use of soapUI.

Using soapUI to call Web Services

soapUI is an open source tool that frequently comes in handy to quickly try out Web

Services and inspect the messages they return. It can be downloaded at http://www.soapui.org/.

To use soapUI for trying out the simplePatientDataRecordService, perform the following steps:

1. download, install and run soapUI

2. create a new WSDL project; associate the WSDL for the

simplePatientDataRecordService with this project

3. edit the SOAP request message for the getPatientDataRecord operation (provide an

integer value for the patientId)

4. edit the end point - enter the URL at which the Web Service is available

5. press the „submit request‟ button, to have the service invoked


8-68

Screenshot showing soapUI after making a test call to the simplePatientDataRecordService

One of the features offered by soapUI is called MockWebServices. This allows us to

make a Web Service available as described in a WSDL document, without writing any

implementation code. SoapUI can make this service available at a port and URL path you can

configure yourself and start receiving SOAP calls.

Obviously, a mock implementation does not return meaningful values, but it can be

called as the real service will be called and it does return values in the appropriate data structure.

For service clients who want to start developing and testing before a real service is available, this

offers an ideal way of quickly starting out.

Calling a Web Service from PL/SQL

A SOAP bound Web Service for which we have the entire WSDL can be called from

PL/SQL. In fact, it is very easy to do so. A Web Service call consists of sending a SOAP based

XML document across HTTP to the URL specified in the Service element of the WSDL.

PL/SQL can send any text based messages to URLs via HTTP using the UTL_HTTP package -

and receive synchronous responses as well.

The PL/SQL code required to invoke the SimplePatientDataRecordService service looks

like this:


15-69

DECLARE

l_response_payload XMLType;

l_payload varchar2(2000);

l_payload_namespace varchar2(200):= 'http://ourhospital.com/patient';

l_soap_action varchar2(30000):= 'getPatientData';

l_target_url varchar2(200):=

'http://host:port/hospital/patientservices/GetPatientDataRecordServiceSoapHttpPort

';

function soap_call

( p_payload in varchar2

, p_target_url in varchar2

, p_soap_action in varchar2 default null

) return xmltype

is

c_soap_envelope varchar2(250):= '<soap:Envelope

xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body>**payload**</soap:Body>

</soap:Envelope>';

l_soap_request varchar2(30000);

l_soap_response varchar2(30000);

http_req utl_http.req;

http_resp utl_http.resp;

begin

l_soap_request := replace(c_soap_envelope, '**payload**', p_payload);

http_req:= utl_http.begin_request

( p_target_url


8-70

, 'POST'

, 'HTTP/1.1'

);

utl_http.set_header(http_req, 'Content-Type', 'text/xml');

utl_http.set_header(http_req, 'Content-Length', length(l_soap_request));

utl_http.set_header(http_req, 'SOAPAction', l_soap_action);

utl_http.write_text(http_req, l_soap_request);

-- the actual call to the service is made here

http_resp:= utl_http.get_response(http_req);

utl_http.read_text(http_resp, l_soap_response);

utl_http.end_response(http_resp);

-- only return the payload from the soap response - tyhat is: the content of

the body element in the SOAP envelope

return XMLType.createXML( l_soap_response).extract(

'/soap:Envelope/soap:Body/child::node()'

, 'xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"'

);

end;

BEGIN

l_payload := '<ns1:patientIdentification

xmlns:ns1="http://ourhospital.com/patient">

<ns1:patientId>43</ns1:patientId>

</ns1:patientIdentification>';

l_response_payload := soap_call(l_payload, l_target_url, l_soap_action);

END;


15-71

The l_response_payload variable of type XMLType contains the XML message that was

returned by the service; it is described by the PatientDataRecord message in the WSDL, which is

directly based on the patient element in the SimplePatient.xsd document. We can extract

structured information from this variable using the operation on the XMLType object. For

example to get hold of the name and birth date of the patient:

l_name := l_response_payload.extract('/patient/name/text()', 'xmlns="'||

l_payload_namespace||'"').getStringVal();

l_date := to_date(l_response_payload.extract('/patient/birthDate/text()',

'xmlns="'|| l_payload_namespace||'"').getStringVal(), 'YYYY-MM-DD');

Calling a Web Service from Java

Using the Web Service facilities in JDeveloper for Java development, it is even easier to

create a piece of application logic to call the Web Service. JDeveloper can create a so called Web

Service Proxy - code to invoke the Web Application that can be integrated with your own

application as a piece native Java functionality.

The wizard requires the WSDL, which must include the proper end point, and will

generate the necessary Java classes. The result is based on the JAX-WS specification.

On top of all generated classes, there is the hook we can use to embed the service call in

our Java application:

public class GetPatientDataRecordServiceSoapHttpPortClient

{

@WebServiceRef

private static SimplePatientDataRecordService simplePatientDataRecordService;

public static void main(String [] args)

{

simplePatientDataRecordService = new SimplePatientDataRecordService();


8-72

SimplePatientRecordDataInterface simplePatientRecordDataInterface =

simplePatientDataRecordService.getGetPatientDataRecordServiceSoapHttpPort();

// Add your code to call the desired methods.

PatientIdType patientId = new PatientIdType();

patientId.setPatientId(new BigInteger("23"));

PatientType patient =

simplePatientRecordDataInterface.getPatientDataRecord(patientId);

}

}

SOA Appendix B XML Fundamentals August 2010

Documents

Transcript of SOA Appendix B XML Fundamentals August 2010