XML Concepts
The following table provides an overview of the documentation available on XML and Web Services resources:
|
Provides an overview of the facilities available using XML Resources
and Web Services Resources. |
|
|
In depth technical description of the operation of the XML Resources
and Web Services Resources. |
|
|
How to use the studio to create and maintain XML Resources and Web
Services Resources. |
|
|
Description of the supplied adapters and parameters to configure them. |
|
|
This document - some general information on XML |
Overview
XML Structure
XML Namespaces
The W3C XML
Schema Language
SOAP
This section gives a brief overview of XML, Namespaces, XML Schemas and SOAP. Verj.io supports XML READ and WRITE functions using XMLCustomResource and CALL function WebServicesCustomResource that is available as a separate download from the standard Verj.io distribution.
SOAP messaging is used for passing messages, usually request and response from client to server machines that contains an XML message body. This is the fundamentals for Web Services to allow different platforms to communicate to one another using a standard protocol. This section gives a brief introduction to SOAP and Web Services.
The eXtensible Markup Language (XML) is a meta-language. This is defined by the W3C specification that defines all the rules for creating XML markup languages. XML defines a set of custom tags that are used to organize and describe text. Tags are usually paired together with a start and end tag. Everything between the two tags are known as an element. An example of an XML structure to organize customer shipping details on an order form is shown below:
<?xml
version="1.0" encoding="UTF-8" ?>
<customer>
<firstname>Fred</firstname>
<surname>Bloggs</surname>
<DOB>10/12/1970</DOB>
<addresses>
<address type="billing">
<addressLine1>1 North Road</address1>
<addressLine2/>
<town>Colchester</town>
<county>Essex</county>
<postcode>CO9 9JJ</postcode>
</address>
<address
type="shipping">
<addressLine1>2 South Road</address1>
<addressLine2/>
<town>Colchester</town>
<county>Essex</county>
<postcode>CO8 9SR</postcode>
</address>
</addresses>
<homeTelephone>01334
234567</homeTelephone>
<businessTelephone>01334
234568</businessTelephone>
<mobileTelephone>0777
876543</mobileTelephone>
</customer>
The XML structure shown above is self explanatory. XML Data must start with a root element, the above example shows customer as the root element. All text data is enclosed within a start tag and an end tag, e.g <firstname>Fred</firstname>. All start tags are wrapped using <tagName> and end tags end with </tagName>. Enclosed within these tags can be other tags or textual data. An Element can contain empty data. Element names do not need to be unique, but they are case sensitive.
Attributes
An element may contain 1 or more attributes. Attributes are used to supplement the data contained by an element to provide data that is not provided by its content. In the example above, the address element has an attribute of type="billing" or type="shipping" to determine whether this is a billing address or shipping address.
For more information on XML see W3C specification.
An XML Namespace creates a qualified name for an XML Element. This provides a unique identifier for the element or attribute. The namespace is identified as a URI, e.g. http://www.somecomapny.com/order/ADDR. This example may declare a Namespace for an address. Using namespaces helps avoid name conflicts, organizes the XML and provides access control. An example of how to use namespaces is shown below:
<?xml
version="1.0" encoding="UTF-8" ?>
<purchaseOrder xmlns="http://www.somecompany.com/order/PO>
<firstname>Fred</firstname>
<surname>Bloggs</surname>
<address xmlns="http://www.somecomapany.com/order/ADDR">
<addressLine1>2 South
Road</address1>
<addressLine2/>
<town>Colchester</town>
<county>Essex</county>
<postcode>CO8
9SR</postcode>
</address>
<telephone>01334 234567</telephone>
</purchaseOrder>
The above example
defines two default namespaces. The first is defined
within the purchaseOrder element and the other is
defined within the address element. The final part of the URI (/
Default Namespace, Prefixes and Qualified Names
The xmlns defines the default namespace and all its descendants. The scope of the namespace in address will only apply to address, address1, address2, town, county and postcode. Using default namespaces can be complicated when many are declared within the XML tree. It is recommended to use prefixed namespaces. A qualified name assigns a prefix to an element that maps to a declared namespace. An element using a prefix is defined with two parts, a prefix and a local name separated with a :, e.g addr:address. All descendants of the address element should also be prefixed as shown in the example below:
<?xml
version="1.0" encoding="UTF-8" ?>
<po:purchaseOrder xmlns:po="http://www.somecompany.com/order/PO
xmlns:addr="http://www.somecomapany.com/order/ADDR>
<po:firstname>Fred</po:firstname>
<po:surname>Bloggs</po:surname>
<addr:address">
<addr:addressLine1>2 South
Road</addr:address1>
<addr:addressLine2/>
<addr:town>Colchester</addr:town>
<addr:county>Essex</addr:county>
<addr:postcode>CO8
9SR</addr:postcode>
</addr:address>
<po:telephone>01334
234567</po:telephone>
</po:purchaseOrder>
In the example above, the namespace declaration is moved to the purchaseOrder element. This is optional and can be declared within the address element. Adding the namespace gives the address namespace scope throughout the whole of the document and is not restricted to the address element.
It is not required to qualify all elements within the XML. You can rely on default namespace to determine the namespace for all elements not explicitly prefixed. This is shown in the example below:
<?xml
version="1.0" encoding="UTF-8" ?>
<purchaseOrder xmlns="http://www.somecompany.com/order/PO
xmlns:addr="http://www.somecomapany.com/order/ADDR>
<firstname>Fred</firstname>
<surname>Bloggs</surname>
<addr:address">
<addr:addressLine1>2 South
Road</addr:address1>
<addr:addressLine2/>
<addr:town>Colchester</addr:town>
<addr:county>Essex</addr:county>
<addr:postcode>CO8
9SR</addr:postcode>
</addr:address>
<telephone>01334 234567</po:telephone>
</purchaseOrder>
(See W3C Namespaces for more information)
This section gives a brief description of XML Schemas. This subject is extremely large, so an overview of XML Schemas is given below. For more information on XML Schemas, see W3C Schema Specification.
The XML specification includes the Document Type Definition (DTD), which can be used to describe how XML elements and attributes are organized. XML Schemas, known as XML Schema Definition, (XSD) are an extension to DTD which also provides validation of data types.
XSD documents end with .xsd extension and define the structure of the XML element and all their datatypes. An xsd is assigned to a XML document by adding xsi:schemaLocation="http://www.mycompany.com/order/po.xsd" to the element that is required to follow the schema validation. This is shown in the example at the end of this section.
The XML Schema root element must start and end with schema tag. There are two element types, simple types and complex types.
Simple and Complex Types
A simple type defines the primitive data type of an element. The XML Schema specification defines many standard types know as built-in types. These are declared using <element name="elementname" type="datatype"/>.
A Complex type defines how many elements contain other elements that are not simple types. In other words, defines the parent of nested Simple Types or Nested Complex types. These are declared using
<complexType name="elementname"/>
An example of simple
and complex type declaration within an XML Schema is shown below:
<?xml
version="1.0" encoding="UTF-8" ?>
<schema xmlns:"http://www.w3.org/2001/XMLSchema">
<element name="purchaseOrder"
type="PurchaseOrder"/>
<complexType name="PurchaseOrder">
<sequence>
<element
name="firstname"
type="string"/>
<element
name="surname" type="string"/>
<element
name="shipAddress"
type="address"/>
<element
name="billAddress"
type="address"/>
<element
name="telephone" type="string"/>
</sequence>
</complexType>
<complexType
name="address">
<sequence>
<element
name="addressLine1" type="string"/>
<element
name="addressLine2" type="string"/>
<element
name="town" type="string"/>
<element
name="county" type="string"/>
<element
name="postcode" type="string"/>
</sequence>
</complexType>
</schema>
XML Schemas also declare sequences, attribute types and occurrences.
SOAP was originally
an acronym for Simple Object Access Protocol, but now it is just a name. SOAP's primary application is A2A (Application to
Application) communication, specifically it is used for B2B (Business to
Business) and Enterprise applications. SOAP is another XML Markup language with
one primary purpose, to exchange data across a network from one machine to
another. SOAP is specification governed by the W3C.
A SOAP XML document instance is commonly known as a SOAP message and is transferred across a network using some over network protocol. The most common way to transfer a SOAP message is using HTTP (HyperText Transfer Protocol). These are not meant to be read like a conventional web page, but are processed by the receiving server which then sends a response once the server has processed SOAP Message. SOAP can also be used as one way communication (fire and forget approach).
The power of SOAP is that it uses XML's extensibility and is firewall friendly. Most firewalls are configured to allow HTTP communications through them.
Basic Structure of SOAP
A SOAP Message is a kind of XML document. It has its own XML Schema, namespaces and processing rules. A SOAP Message consists of a SOAP Envelope as its root element. Just as a paper envelope, it contains a message inside. The message inside the SOAP Element must contain a Body. It may also contain a header that contains additional information such as digital signature information or actors. SOAP Headers are not described in this document. For more information about SOAP, see SOAP Specification.
The example below shows the basic structure of a SOAP message.
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header>
<!-- SOAP Header goes in here and
is only created if required otherwise the Header tag can be left out //-->
</soap:Header>
<soap:Body>
<purchaseOrderRequest xmlns="http://www.somecompany.com/order/PO
xmlns:addr="http://www.somecomapany.com/order/ADDR>
<firstname>Fred</firstname>
<surname>Bloggs</surname>
<addr:address">
<addr:addressLine1>2 South Road</addr:address1>
<addr:addressLine2/>
<addr:town>Colchester</addr:town>
<addr:county>Essex</addr:county>
<addr:postcode>CO8 9SR</addr:postcode>
</addr:address>
<telephone>01334 234567</po:telephone>
</purchaseOrderRequest>
</soap:Body>
</soap:Envelope>
Shown in the example above, the SOAP message consists of an Envelope, that consists of a Header (optional and can be omitted) and a Body. The Body of the document consists of the actual message which is an arbitrary element. In this example, the purchase order to be processed. The SOAP specific elements are shown in bold and note that they have their own schema and have a prefix of soap.
A SOAP Response (if applicable) would consist of the same structure shown above but the message body would be different. In many web services it is usually standard to expect elementNameResponse as the base element in the soap:Body. N.B. the request base element usually consists of elementName Request.
SOAP Fault
If there is an error
processing the request on the receiving server, a SOAP Fault will be generated.
A SOAP Fault is defined within the SOAP XML Schema and consists of the
following:
· faultcode - specifies the fault code. The most common fault codes are soap:Client for client side error or soap:Server for server side error.
· faultstring - brief description of the error
· actor - URL representation of Server processing the machine
· detail - base element for additional information relating to the error. This is optional and may not be included.
An example of a SOAP Fault is shown below:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Fault>
<faultcode>soap:Client</faultcode>
<faultstring>Customer
Fred Blogs does not exist</stringcode>
<faultactor>http://www.somecompany.com/order/processorder</faultactor>
<detail/>
</soap:Fault>
</soap:Envelope>
SOAP Actions
Some Web Services require a SOAP Action that is a URL String set in the mime headers of the HTTP request. The HTTP Header is mapped using SOAPAction: "empty string or URL". The SOAP Action must match the SOAP Action declared within the WSDL (Web Services Definition Language, not described in this document) soapbind:operation element. This may not be required and can be omitted.
SOAP Summary
This section has given a basic overview of SOAP and its use in Web Services. SOAP is a much larger subject and to utilize all its functionality it is recommended to read the W3C SOAP Specification.