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:

• implement encodeWithWOXMLCoder declared in the WOXMLCoding interface (your implementation of this method is where you encode the custom class's instance variables)
• implement the single-argument constructor described in the WOXMLDecoder class description

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:

• an instance of String, Number, Boolean and NSTimestamp. Subclasses of these classes will be treated like their superclass, unless you explicitly implement the WOXMLCoding interface.
• an instance of NSArray, NSDictionary and NSData. Please note that before WebObject 5.1, when the mutable forms of these classes (NSMutableArray, NSMutableDictionary and NSMutableData) are encoded using WOXMLCoder, they get written out as their immutable counterparts. For example, NSMutableArray used to be written out as NSArray. Now, they get written out as themselves. As a result, when WOXMLDecoder is used to decode mutable objects, they are decoded as mutable forms.
• an instance of EOEnterpriseObject (or a subclass, providing that all instance variables are either attributes or relationships).

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:

• name=property (required)
  The type name for the encoded object, for example the MyMovie class. Usually, this is the name of the property on the key-value coding side (the name of the class, name of the attribute of the enterprise object in the EOModel, or dictionary key to which the XML data is to be mapped).
• xmlTag=tag (required)
  The XML tag that appears in the generated data. This tag corresponds to the entity that is currently being described.
• ignoreUnmappedTags="YES" | "NO" (optional)
  This attribute is useful only during decoding.
  "NO" causes a WOXMLException to be thrown if unmappedTagsKey isn't specified and, while parsing the XML for the entity, an XML tag is encountered for which there is no specified mapping in the mapping model. No exception is thrown if "YES" is specified or if the entity object being decoded is an NSDictionary.
  Default is "NO".
• unmappedTagsKey=key (optional)
  This attribute is useful only during decoding.
  The name of the property on the key-value coding side to be used when, while parsing the XML for the entity, an XML tag is encountered for which there is no specified mapping in the mapping model. Note the value to be given for the key-value coding is an NSDictionary, for example, '{ quantity = "9"; }'. The developer has to deal with this as such.
• contentsKey=key(optional)
  This attribute is useful only during decoding.
  The property name to be used for text enclosed by the <entity> element being parsed. For example, if the mapping model contained the following:

  
  ...
  <entity name="com.webobjects.foundation.NSMutableDictionary" xmlTag="text" contentsKey="contents" />
  ...
  

  and if the following was encountered while parsing XML:

  
  <text>Hello, <b>World!</b></text>
  

  an NSMutableDictionary object would be created with a single key-value pair: the key "contents" would have as its value an NSMutableArray containing two elements: the string "Hello, " and a dictionary with a single key-value pair: the key "b" would have as its value the string "World!".

  When this attribute is specified, it is not necessary to create <property> elements for this <entity> element since they are not used anyway. Instead, ensure that there is a key-value coding pair for the key and that the value is dealt with as an NSMutableArray.

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:

• name=key (required)
  The name of the key of the key-value coding pair representing the property.
• xmlTag=tag (required)
  The XML tag that appears in the generated data. This tag corresponds to the property that is currently being described. If this property's type is actually a class, for example MyMovie, then an <entity> element has to be defined later to complete the full description. The chaining is done using this <xmlTag>. Using the previous example, the entity Command has a property movie. Since movie is actually an object of class MyMovie, it is further described using another <entity> element.
• attribute="YES" | "NO" (optional)
  This attribute is useful only during encoding.
  "YES" causes this property to be encoded as an attribue of the enclosing <entity> element instead of the usual sub-element. For example, if attribute="YES" was specified for the movie property, it will be encoded as:

  
  	<command movie="someValue" ... </command>
  
  

  instead of:

  
  	<command>
  		...
  		<movie>someValue</movie>
  		...
  	</command>
  
  

  Default is "NO".
• forceList="YES" | "NO" (optional)
  This attribute is useful only during decoding.
  When parsing for the value of the property, a single enclosed value is decoded as an object of the appropriate type or as a String (if there is no further <entity> element mapping for the value). This is the default behavior (when forceList="NO"). "YES" causes a single enclosed element to be decoded as an NSMutableArray with a single object of the appropriate type. For example, if we have an XML segment like this:

  
  	<property_foo>
  	  <type_bar>some_Value</type_bar>
  	</property_foo>
  
  

  by default, decoding will result in a key-value coding call with key property_foo and value an object of type type_bar. But forceList="YES" causes the value in this instance to become an NSMutableArray containing a single object of type type_bar.
  

  Note that decoding an XML structure like the following:

  
  	<property_foo>
  	  <type_bar>value1</type_bar>
  	  <type_bar>value2</type_bar>
  	</property_foo>
  
  

  always results in a key-value coding call with key property_foo and value an NSMutableArray containing the two type_bar objects.

  Default is "NO".
• codeBasedOn="TAG" (optional)
  This attribute is useful only during decoding.
  The WOXMLCoder normally uses the value of the property's name attribute as the key during key-value coding. This is the desired behavior in most situations since the name attribute typically indicates the name of an instance variable in a custom class. When working with NSDictionary objects, however, you may instead want to use the value of the xmlTag attribute as the key. To do this, specify codeBasedOn="TAG" in the property's list of attributes.
• reportEmptyValues="YES" | "NO" (optional)
  This attribute is useful only during decoding.
  When an empty element is encountered while decoding XML (for instance, <myElement></myElement>), the WOXMLDecoder creates an empty NSDictionary object by default. Setting reportEmptyValues to "NO" prevents this empty object from being created.
  Default is "YES".
• outputTags="class" | "property" | "both" | "neither" (optional)
  This attribute is useful only during encoding.
  It specifies which XML tag specified in the mapping model should be output for the given property. property, the default, specifies that the property's XML tag should be output. class specifies that the XML tag associated with the property's enclosing class should be output instead. both indicates that both the property and the class tags should be output, and neither indicates that neither XML tag should be placed in the XML.

  To illustrate the use of the outputTags attribute, the following mapping model could be used to produce HTML tags from an NSMutableDictionary object:

  
  <model>
    <entity name="com.webobjects.foundation.NSMutableDictionary" xmlTag="text">
      <property name="p" xmlTag="ignore" outputTags="neither"/>
    </entity>
    <entity name="Paragraph" xmlTag="p">
      <property name="text.contents" xmlTag="text" outputTags="class"/>
    </entity>
    <entity name="ItemList" xmlTag="ul">
      <property name="contents" xmlTag="li" outputTags="both"/>
    </entity>
    <entity name="Item" xmlTag="item">
      <property name="contents" xmlTag="ignore" outputTags="class"/>
    </entity>
    <entity name="LineBreak" xmlTag="br"/>
    <entity name="ExternalLink" xmlTag="a">
      <property name="url" xmlTag="href" attribute="YES"/>
      <property name="anchorText" xmlTag="ignore" outputTags="neither"/>
    </entity>
  </model>
  
  

Package Specification

Related Documentation