Introduction to XML
Extensible Markup Language (XML) is a way to describe structured data in text. Of the many roles XML plays in web services, perhaps the most visible to you as a developer is providing the format for the messages a web service sends and receives. A web service receives method calls, returns values, and sends notifications as XML messages. As you test and debug your service, for example, you might construct XML documents that represent sample messages your service could receive, then pass these documents to your service and view the results.
For more information about the XML standard, see Extensible Markup Language (XML) 1.0 (Second Edition) at the web site of the W3C. The W3C also provides a page with useful links to more information about XML at Extensible Markup Language (XML).
Note: While WebLogic Server handles the task of converting data in Java to and from XML messages, you can exert greater control over your service's use of these messages through XML maps. For more about XML mapping, see Why Use XML Maps?
Let's start with a sample XML document. Imagine that you are writing a web service to return information about employees from a database. Based on first and last name values sent to your service, your code searches the employee database and returns contact information for any matches. The following example is XML that might be returned by your service. Even if you have no experience with XML, you can probably see structure in the example.
<!-- Information about the employee record(s) returned from search. --> <employees> <employee> <id ssn="123-45-6789"/> <name> <first_name>Gladys</first_name> <last_name>Cravits</last_name> </name> <title>Busybody</title> <address location="home"> <street>1313 Mockingbird Lane</street> <city>Anytown</city> <state>IL</state> <zip>12345</zip> </address> </employee> </employees>
In XML, text bracketed by < and > symbols is known as an element. Elements in this example are delimited by tags such as <employees> and </employees>, <name> and </name>, and so on. Note that most elements in this example have a start tag (beginning with <) and an end tag (beginning with </). Because it has no content the <id> element ends with a /> symbol. XML rules also allow empty elements to be expressed with start and end tags, like this: <id ssn="123-45-6789"></id>.
Every XML document has a root element that has no parent and contains the other elements. In this example, the <employees> element is the root. The name of the root element is generally based on the context of the document. For example, if your service is designed to return merely an address—an <address> element and its contents—then the root element is likely to be <address>.
Elements that contain other elements are said to be parent elements; the elements that parent elements contain are known as child elements. In this example, <employees>, <employee>, <name>, and <address> are parent elements. Elements they contain—including <employee>, <id>, <name>, and <city>—are children. (Note that an element can be both a parent and a child.)
Note: This example uses indentation to accentuate the hierarchical relationship, but indentation is not necessary.
Attributes are name/value pairs attached to an element (and appearing in its start tag), and intended to describe the element. The <id> element in this example has an ssn attribute whose value is 123-45-6789.
The content in XML is the text between element tags. Content and attribute values represent the data described by an XML document. An element can also be empty. In the example above, “Gladys” is the content (or value) of the <first_name> element.
You can add comments to XML just as you would with HTML, Java, or other languages. In XML, comments are bracketed with <!-- and --> symbols (the same symbols used in HTML). The first line of the example above is a comment.
A namespace in XML serves to define the scope in which tag names should be unique. This is important because XML's wide use and textual nature make it likely that you will see occasions where element names with different meanings occur in the same document. For example, namespaces and prefixes are used in XML maps, where a prefix differentiates the tags that are needed for mapping from those associated with the mapped method's XML message.
As you gain more experience with XML you may become exposed to schemas. Schemas are not required but can be used to help define what should be in an XML document used for a certain purpose. Whereas XML itself defines basic rules for syntax and structure, a schema defines more stringent rules for the structure and content of an XML document. It can specify which elements and attributes can appear in a document, which elements should be children of others, the sequence of child elements, and so on. If an XML document meets XML's general rules it is called well-formed; if it meets a schema's more specific rules, it is said to be valid.
The following example XML document describes an order of oranges and apples. Compare this document with the schema that follows it.
<?xml version="1.0"?> <produceOrder> <item> <name>Oranges</name> <amount>4</amount> <price>2.0</price> </item> <item> <name>Apples</name> <amount>12</amount> <price>3.6</price> </item> </produceOrder>
The following schema is designed to enforce not only the hierarchy of the produce order description, but also the data types allowable for each element. XML schemas use XML syntax, and as a result they can look somewhat like the documents to which they apply.
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="produceOrder" type="item"/> <xs:complexType name="item"> <xs:sequence> <xs:element name="name" type="xs:string"/> <xs:element name="amount" type="xs:integer"/> <xs:element name="price" type="xs:decimal"/> </xs:sequence> </xs:complexType>
In this simple example, the hierarchy specifies that the <name>, <amount>, and <price> elements should be children of the <item> element, and the order in which they should appear. The structure of an XML document—including its hierarchy, the order of elements, and so on—is sometimes called its shape.
The xs prefix specifies the namespace against which the tag names should be evaluated for uniqueness. The namespace declaration, which begins with xmlns (for XML namespace), maps the xs prefix to the Uniform Resource Identifier (URI), http://www.w3.org/2001/XMLSchema. In practice, there need not be anything special at the other end of the URI—it need only be a path that is unique.
The xs prefix also lends specific meaning to the value of type attributes where it is used. Here, types whose values have an xs prefix are known as "simple types," and are defined by the W3C XML Schema specification. Finally, this schema also defines a complex type called item. According to this schema, the item type consists of three XML elements in a specific sequence.
You can use a schema to validate messages received or sent by your web service. When you do so, you can mark your service method's implementation with a custom Javadoc tag that specifies the schema to use. For reference information, see @jws:parameter-xml Tag or @jws:return-xml Tag.