WOXMLDecoder

Inherits from: Object

Implements: NSKeyValueCoding

Package: com.webobjects.appserver.xml

Class Description

Use this class to construct ("decode") an object from XML data. Decoding can take place either with or without a mapping model. 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 an archiving mechanism, the mapping model is usually not necessary. For more information on the mapping model, see the "The Format of the Mapping Model" (page 4) in the framework introduction.

Decoding XML Without a Mapping Model

On its own, without a mapping model, WOXMLDecoder is able to decode any object as long as the object and all of its children either implement the WOXMLDecoder interface or are an instance of String, Number (or a subclass, provided that the subclass doesn't add instance variables), NSArray, NSDictionary, NSDate, NSData, or EOEnterpriseObject (or a subclass, providing that all instance variables are either attributes or relationships). To construct an object from XML data, invoke one of the decodeRootObject methods.

Objects that implement the WOXMLCoding interface must also implement a single-argument constructor that takes a WOXMLDecoder object as the single argument if they are to be decoded. Within this constructor you decode your object's instance variables using WOXMLDecoder's various decode...ForKey methods.

The following simple "Person" class implements both the single-argument constructor needed to decode objects of this class and the WOXMLCoding interface.








import com.webobjects.appserver.xml.*;
import com.webobjects.foundation.*;
import java.lang.*;
import java.net.*;
import java.math.*;

public class Person extends Object implements WOXMLCoding {
    String name;
    boolean married;
    int children;

    public Person() {
        name = "John Smith";
        married = true;
        children = 2;
    }

    public void encodeWithWOXMLCoder(WOXMLCoder coder) {
        coder.encodeObjectForKey(name, "Name");
        coder.encodeBooleanForKey(married, "MaritalStatus");
        coder.encodeIntForKey(children, "NumberOfChildren");
   }

    // constructor required for decoding
    public Person(WOXMLDecoder decoder) {
        name = (String)decoder.decodeObjectForKey("Name");
        married = decoder.decodeBooleanForKey("MaritalStatus");
        children = decoder.decodeIntForKey("NumberOfChildren");
    }
}

See the XMLArchiving example (accessible through the WebObjects Info Center under Examples > WebObjects > Java > XMLArchiving) for a more complete example.

Decoding XML With a Mapping Model

The mapping decoder gives you much greater control over the decoding process, since it operates under the direction of an XML-format mapping model that you create. This mapping model allows you to specify how XML elements and attributes are to be mapped to objects and object attributes (the mapping is performed using key-value coding). Because of the added power and flexibility the mapping model provides, the mapping decoder is particularly well-suited to decode XML that wasn't generated by the WOXMLDecoder.

Suppose you had the following XML:








<command quantity="10">
    <customer><name>Ringle</name></customer>
    <fullMovie name="Alien">
        <date>1979-10-25 00:00:00 -0700</date>
        <cat>Horror</cat>
        <role name="Brett"></role>
        <role name="Kane"></role>
        <role name="Dallas"></role>
        <role name="Parker"></role>
        <role name="Lambert"></role>
        <role name="Ash"></role>
        <role name="Ripley"></role>
    </fullMovie>
</command>

Futher suppose that you wanted to decode the above XML into an object of the following class:








public class Command extends NSObject {
    public EOGenericRecord movie;
    public NSMutableDictionary customer;
    public int qty;
}

The WOXMLDecoder will do the job for you given the following 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>

The above is a simple example; see the RelatedLinks example (accessible through the WebObjects Info Center under Examples > WebObjects > Java > RelatedLinks) for a more complete example illustrating the use of the WOXMLDecoder with a mapping model.

Interfaces Implemented

NSKeyValueCoding takeValueForKey valueForKey

Method Types

Creating a WOXMLDecoder decoder decoderWithMapping Decoding XML decodeRootObject Reconstructing an object's contents without a mapping model decodeBooleanForKey decodeDoubleForKey decodeFloatForKey decodeIntForKey decodeObjectForKey Working with the XML parser parser parserClassName setParserClassName

Constructors

WOXMLDecoder

protected WOXMLDecoder()

Description forthcoming.

Static Methods

decoder

public static WOXMLDecoder decoder()

Creates and returns a new WOXMLDecoder object.

decoderWithMapping

public static WOXMLDecoder decoderWithMapping(String mappingURL)

Creates and returns a new WOXMLDecoder object that decodes XML based upon the mapping model specified by mappingURL. For more information, see "Decoding XML With a Mapping Model" (page 19).

Note: Windows NT uses backslashes where other systems use forward slashes. When prepending the "file:" URL prefix to a path such as is returned by WOResourceManager's pathForResourceNamed method, on Windows NT the prefix must be "file:\\" while on all other platforms the prefix must be "file://". See the RelatedLinks example for one way to select the proper prefix based upon the underlying system.

Instance Methods

addObjectToCache

protected void addObjectToCache(_private._DecodingNode childNode, Object anObject)

For internal use only.

decodeBooleanForKey

public boolean decodeBooleanForKey(String key)

Invoke this method from within in your single-argument constructor to set a boolean instance variable to the value of the key element within the XML being decoded. For example, to extract the marital status from the following XML:









<element type="Person" objectID="4">
    <Name type="java.lang.String" objectID="5">John Smith</Name>
    <MaritalStatus type="boolean">True</MaritalStatus>
    <NumberOfChildren type="int">2</NumberOfChildren>
</element>

You could use something similar to the following:









married = decoder.decodeBooleanForKey("MaritalStatus");

decodeDoubleForKey

public double decodeDoubleForKey(String key)

Invoke this method from within in your single-argument constructor to set an instance variable of type double to the value of the key element within the XML being decoded.

See Also: decodeIntForKey

decodeFloatForKey

public float decodeFloatForKey(String key)

Invoke this method from within in your single-argument constructor to set an instance variable of type int to the value of the key element within the XML being decoded.

See Also: decodeIntForKey

decodeIntForKey

public int decodeIntForKey(String key)

Invoke this method from within in your single-argument constructor to set an instance variable of type int to the value of the key element within the XML being decoded. For example, to extract the number of children from the following XML:








<element type="Person" objectID="4">
    <Name type="java.lang.String" objectID="5">John Smith</Name>
    <MaritalStatus type="boolean">True</MaritalStatus>
    <NumberOfChildren type="int">2</NumberOfChildren>
</element>

You could use something similar to the following:









children = decoder.decodeIntForKey("NumberOfChildren");

decodeObjectForKey

public Object decodeObjectForKey(String key)

Invoke this method from within in your single-argument constructor to set an instance variable to a newly constructed object whose class and content depends upon the value of the key element within the XML being decoded. The object being decoded must meet the same criteria outlined in decodeRootObject; if not, or if an error arises during the construction of the object, decodeObjectForKey throws a WOXMLException.

decodeRootObject

public synchronized Object decodeRootObject(NSData data)

public synchronized Object decodeRootObject( org.xml.sax.InputSource inputSource)

public synchronized Object decodeRootObject(String XMLfileURL)

Decodes the indicated XML and constructs a corresponding object. decodeRootObject accepts XML either in an NSData object, in a file, or through an InputSource. If the XML resides within a file, XMLfileURL should be a URLthat identifies the file containing the XML. If the XML resides within a String object, use a StringReader object to supply an InputSource, like this:








stringReader = new StringReader(xmlString);
is = new InputSource(stringReader);
// invoke setEncoding (on the input source) if the XML contains multibyte characters
decodedObject = (NSMutableArray)myDecoder.decodeRootObject(is);

In the above example, xmlString is a String object that contains the XML for an encoded NSMutableArray object.

Each object encoded within the XML must have a type attribute that indicates the object's class. Each encoded object must be one of the following:

an instance of String
an instance of NSArray
an instance of NSDictionary
an instance of NSDate)
an instance of Number (or a subclass, providing that the subclass doesn't add instance variables)
an instance of NSData
an object that implements the WOXMLCoding interface
an instance of EOEnterpriseObject (or a subclass, providing that all instance variables are either attributes or relationships)

Objects that implement the WOXMLDecoder interface must also implement a special constructor; see "Decoding XML Without a Mapping Model" (page 18) for more information and an example.

If the parser is unable to parse the supplied XML, decodeRootObject throws a WOXMLException that encloses either a SAXException or an IOException.

getChildNodeType

protected String getChildNodeType(_private._DecodingNode childNode)

For internal use only.

handler

protected _private._DecodingHandler handler()

For internal use only.

parser

public org.xml.sax.Parser parser()

Returns the XML parser (instantiating one based upon the parser class name, if necessary). This method throws a ClassNotFoundException if the parser class cannot be located, and an InstantiationException or IllegalAccessException if the parser cannot be created. The default parser is the SAX parser (com.ibm.xml.parsers.SAXParser).

This method is invoked by decodeRootObject.

See Also: parserClassName, setParserClassName

parserClassName

public String parserClassName()

Returns the name of the XML parser's class. By default, this is "com.ibm.xml.parsers.SAXParser".

See Also: parser, setParserClassName

setParserClassName

public void setParserClassName(String className)

Sets className as the name of the class to be instantiated and used as the XML parser. The default parser class name is "com.ibm.xml.parsers.SAXParser". This method must be invoked before the parser is instantiated (by the parser method); once the parser has been instantiated, setParserClassName has no effect.

See Also: parser, parserClassName

takeValueForKey

public void takeValueForKey( Object, String)

Description forthcoming.

toString

public String toString()

Returns a String description of the receiver suitable for debugging purposes.

valueForKey

public Object valueForKey(String aKey)

Description forthcoming.