WebObjects 5.2.3

Package com.webobjects.foundation.xml

Provides for encoding and decoding of XML data.

See:
          Description

Interface Summary
NSXMLObjectOutput This interface provides for converting data from any of the Java primitive types to a series of XML elements.
NSXMLObjectStreamConstants Constants used for XML serialization.
 

Class Summary
NSXMLInputStream An NSXMLInputStream deserializes primitive data and objects previously written as XML data using an NSXMLOutputStream.
NSXMLOutputFormat This simple class specifies an output format to control the XML output and is based on the XSLT specification for output format.
NSXMLOutputStream An NSXMLOutputStream writes primitive data types and graphs of Java objects to an OutputStream as XML data.
 

Package com.webobjects.foundation.xml Description

Provides for encoding and decoding of XML data.

Introduction

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 Thu Oct 21 15:04:16 PDT 2004.

Copyright © 2004 Apple Computer, Inc.