WebObjects 5.4.2

Package com.webobjects.appserver.xml

Provides for encoding and decoding of XML data.


Interface Summary
WOXMLCoding This interface allows WOXMLCoder, when used without a mapping model, to encode the class that implements this interface as XML data.

Class Summary
WOXMLCoder This class is used to encode objects as XML data.
WOXMLDecoder Use this class to decode an object from XML data.

Exception Summary
WOXMLException This class serves to wrap a number of exceptions that can arise during the parsing process, reducing the number of exceptions your code has to catch.

Package com.webobjects.appserver.xml Description

Provides for encoding and decoding of XML data.


The XML framework consists of two main classes-WOXMLCoder and WOXMLDecoder-which can encode and decode objects as XML. These classes can also be used to parse or generate XML data from an external source (such as the World Wide Web). When working with such "foreign" XML, you describe the XML elements and properties and their mapping to objects in an XML-format "mapping model" that you can create with either a text editor or an XML editor.

The mapping model provides greater control over the decoding process and is typically used when you are encoding and decoding XML that is destined for, or originates from, an external source. When the WOXMLCoder and WOXMLDecoder are used as a simple archiving mechanism, the mapping model is usually not necessary. See "The Format of the Mapping Model" for more information on the contents and structure of the mapping model.

When encoding and decoding a custom object using the WOXMLCoder and WOXMLDecoder classes without a mapping model, your custom class needs to:

You don't need to do the above if you are working with a mapping model or the object you are encoding and decoding is:

Exceptions raised by the underlying SAX parser are, for simplicity's sake, wrapped in a WOXMLException object, greatly reducing the number of exceptions your code needs to catch.

The Format of the Mapping Model

The mapping model can be created manually with a text editor or an XML editor. It is simply a text file that consists of one or more <entity> elements, each of which can enclose zero or more <property> elements, all enclosed within a single root <model> element.

The following is a simple mapping model:
<model> <entity name="Command" xmlTag="command"> <property name="qty" xmlTag="quantity" attribute="YES"/> <property name="movie" xmlTag="movie"/> <property name="customer" xmlTag="customer"/> </entity> <entity name="MyMovie" xmlTag="movie"> <property name="title" xmlTag="name" attribute="YES"/> <property name="dateReleased" xmlTag="date"> <property name="roles" xmlTag="role"> <property name="category" xmlTag="cat"/> </entity> <entity name="com.webobjects.eocontrol.EOGenericRecord" xmlTag="role"> <property name="roleName" xmlTag="name" attribute="YES"/> </entity> </model>

When creating a mapping model, be aware that mappings must be unique for a given property when decoding (that is, you cannot have two mappings for the same property). The same applies for XML tags when encoding: you cannot have two mappings for the same XML tag.

The <model> element

The <model> element is the root element of the mapping file and it contains the mapping information. It has no attributes. The <model> element must contain at least one <entity> element.

The <entity> element

The <entity> element describes the relationship between the generated XML data and the encoded objects. The first <entity> element describes the root element of the generated XML data. Subsequent <entity> elements are usually required to complete the description of the root element. It has two required attributes and a number of optional ones:

The <property> element

Within an <entity> element, you can have zero or more <property> elements. It describes the mapping between the entity object's property and the XML data to be generated for that property. Each entity object's property is a key-value coding pair whose value will end up as XML data. A <property> element has two required attributes and a few optional ones:

Package Specification

Related Documentation

Last updated June 2008

Copyright © 2000-2008 Apple Inc.