com.webobjects.appserver.xml
Class WOXMLCoder

java.lang.Object
  com.webobjects.appserver.xml.WOXMLCoder

public class WOXMLCoder
extends Object

This class is used to encode objects as XML data. Encoding can take place either with or without a mapping model. The mapping model provides greater control over the encoding 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. For more information on the mapping model, see the "The Format of the Mapping Model" in the package description. To encode an object, simply invoke the encodeRootObjectForKey method. To perform the reverse operation, generating an object from XML data, see the WOXMLDecoder class.

See Also:

WOXMLDecoder, WOXMLCoder.encodeRootObjectForKey(java.lang.Object, java.lang.String)

Field Summary

protected String

xmlDeclaration

Constructor Summary

protected

WOXMLCoder()

Method Summary

static WOXMLCoder	coder() Returns a default coder capable of encoding objects into XML data without using a mapping model.
static WOXMLCoder	coderWithMapping(String mappingURL) Returns a coder object initialized with the mapping model specified by mappingURL.
protected void	cr()
void	encodeBooleanForKey(boolean b, String key) Encodes a boolean value into XML data.
protected String	encodedClassName()
void	encodeDoubleForKey(double d, String key) Encodes a double value into XML data.
void	encodeFloatForKey(float f, String key) Encodes a float value into XML data.
void	encodeIntForKey(int i, String key) Encodes an integer value into XML data.
void	encodeObjectForKey(Object object, String key) Encodes an object into XML data.
protected void	encodeObjectInTag(String s, String xmlTag, String type)
protected void	encodeReferenceInTag(int objectID, String xmlTag, String type)
String	encodeRootObjectForKey(Object object, String key) Encodes an object so that it becomes the root element for the generated XML data.
protected void	encodeStringInTag(String s, String xmlTag, String type)
protected String	escapeString(String toValidate)
void	setXmlDeclaration() Sets the XML declaration to the default: <?xml version="1.0" ?>
void	setXmlDeclaration(String version, String encoding, String standalone) Sets the XML declaration according to the parameters passed.
protected boolean	typeNeedsIndentation(Object o)
String	xmlDeclaration() Gets the previously specified XML declaration.
protected String	xmlTagForClassNamed(String className)
protected String	xmlTagForPropertyKey(String propertyKey, String className)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

xmlDeclaration

protected String xmlDeclaration

Constructor Detail

WOXMLCoder

protected WOXMLCoder()

Method Detail

cr

protected void cr()

typeNeedsIndentation

protected boolean typeNeedsIndentation(Object o)

encodedClassName

protected String encodedClassName()

xmlTagForClassNamed

protected String xmlTagForClassNamed(String className)

xmlTagForPropertyKey

protected String xmlTagForPropertyKey(String propertyKey,
                                      String className)

encodeObjectInTag

protected void encodeObjectInTag(String s,
                                 String xmlTag,
                                 String type)

encodeStringInTag

protected void encodeStringInTag(String s,
                                 String xmlTag,
                                 String type)

encodeReferenceInTag

protected void encodeReferenceInTag(int objectID,
                                    String xmlTag,
                                    String type)

escapeString

protected String escapeString(String toValidate)

coder

public static WOXMLCoder coder()

Returns a default coder capable of encoding objects into XML data without using a mapping model. This method corresponds directly with the decoder factory method in WOXMLDecoder. When encoding a custom object using the WOXMLCoder 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). You don't need this if the object you are encoding is:

• an instance of String, Number, Boolean and NSTimestamp. Subclasses of these classes will be treated like their superclass, unless you explicitly implement WOXMLCoding interface.
• an instance of NSArray, NSDictionary and NSData. Please note that before WebObjects 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 the objects, they are decoded as mutable forms.
• an instance of EOEnterpriseObject (or a subclass, providing that all instance variables are either attributes or relationships).
• Your custom class also don't need to implement WOXMLCoding if you are working with a mapping model.

See Also:

WOXMLDecoder.decoder(), WOXMLCoding

coderWithMapping

public static WOXMLCoder coderWithMapping(String mappingURL)

Returns a coder object initialized with the mapping model specified by mappingURL. For more information on the mapping model, see the "The Format of the Mapping Model" in the package description. This method corresponds directly with the decoderWithMapping factory method in WOXMLDecoder.

Parameters:

mappingURL - an URL to the mapping file that specifies the mapping model

See Also:

WOXMLDecoder.decoderWithMapping(java.lang.String)

xmlDeclaration

public String xmlDeclaration()

Gets the previously specified XML declaration.

Returns:

a previously set XML declaration; if it's not set, an empty String is returned

setXmlDeclaration

public void setXmlDeclaration()

Sets the XML declaration to the default: <?xml version="1.0" ?>

setXmlDeclaration

public void setXmlDeclaration(String version,
                              String encoding,
                              String standalone)

Sets the XML declaration according to the parameters passed.

Parameters:

version - XML version number

encoding - the encoding of the XML data, for example, "ISO-8859-1"; if null, it will not be set

standalone - indicates if XML document can 'standalone'; if null, it will not be set

encodeRootObjectForKey

public String encodeRootObjectForKey(Object object,
                                     String key)

Encodes an object so that it becomes the root element for the generated XML data.

If a mapping model is not used, object has to be an instance of a limited set of classes described in coder or its class has to implement WOXMLCoding interface.

key is ignored when a mapping model is used or when object is an Enterprise Object. In the former case, the mapping model specifies what XML tag to use. In the latter, attribute information stored in the EOModel is used when assigning an XML tag.

Parameters:

object - the object to be encoded as XML data

key - the XML tag to be used for the XML data generated from object

Returns:

if setXmlDeclaration has been called, a complete XML document is returned. Else an XML segment is returned.

See Also:

WOXMLCoder.coder(), WOXMLCoder.setXmlDeclaration(String, String, String), WOXMLCoder.setXmlDeclaration(), WOXMLCoding

encodeObjectForKey

public void encodeObjectForKey(Object object,
                               String key)

Encodes an object into XML data. It is called either implicitly from encodeRootObjectForKey or directly as part of encodeWithWOXMLCoder. Note that nothing is returned from this method but the internal state of WOXMLCoder gets appended with the generated XML data as a result of this method call. The XML data will eventually be returned as a result of encodeRootObjectForKey.

If a mapping model is not used, object has to be an instance of a limited set of classes described in coder or its class has to implement WOXMLCoding interface.

key is ignored when a mapping model is used or when object is an Enterprise Object. In the former case, the mapping model specifies what XML tag to use. In the latter, attribute information stored in the EOModel is used when assigning an XML tag.

Parameters:

object - the object to be encoded as XML data

key - the XML tag to be used for the XML data generated from object

See Also:

WOXMLCoder.encodeRootObjectForKey(java.lang.Object, java.lang.String), WOXMLCoding.encodeWithWOXMLCoder(com.webobjects.appserver.xml.WOXMLCoder)

encodeBooleanForKey

public void encodeBooleanForKey(boolean b,
                                String key)

Encodes a boolean value into XML data. It is called either implicitly from encodeRootObjectForKey or directly as part of encodeWithWOXMLCoder. Note that nothing is returned from this method but the internal state of WOXMLCoder gets appended with the generated XML data as a result of this method call. The XML data will eventually be returned as a result of encodeRootObjectForKey.

key is used as the XML element and the content is the string representation of b-either "True" or "False"-and the element has an attribute type="boolean". For example, the following call

 encodeBooleanForKey(true, "myTag");
 

causes the following XML data to be appended to the WOXMLCoder's internal state:

   <myTag type="boolean">True</myTag>
 

key is ignored when a mapping model is used as the model specifies what XML tag to use.

Parameters:

b - the boolean value to be encoded

key - the XML tag to be used for the XML data generated

See Also:

WOXMLCoder.encodeRootObjectForKey(java.lang.Object, java.lang.String), WOXMLCoding.encodeWithWOXMLCoder(com.webobjects.appserver.xml.WOXMLCoder)

encodeIntForKey

public void encodeIntForKey(int i,
                            String key)

Encodes an integer value into XML data. It is called either implicitly from encodeRootObjectForKey or directly as part of encodeWithWOXMLCoder. Note that nothing is returned from this method but the internal state of WOXMLCoder gets updated with the generated XML data as a result of this method call. The XML data will eventually be returned as a result of encodeRootObjectForKey.

key is used as the XML element and the content is the string representation of i and the element has an attribute type="int". For example, the following call

 encodeIntForKey(123, "myTag");
 

causes the following XML data to be appended to the WOXMLCoder's internal state:

   <myTag type="int">123</myTag>
 

key is ignored when a mapping model is used as the model specifies what XML tag to use.

Parameters:

i - the integer value to be encoded

key - the XML tag to be used for the XML data generated

See Also:

WOXMLCoder.encodeRootObjectForKey(java.lang.Object, java.lang.String), WOXMLCoding.encodeWithWOXMLCoder(com.webobjects.appserver.xml.WOXMLCoder)

encodeFloatForKey

public void encodeFloatForKey(float f,
                              String key)

Encodes a float value into XML data. It is called either implicitly from encodeRootObjectForKey or directly as part of encodeWithWOXMLCoder. Note that nothing is returned from this method but the internal state of WOXMLCoder gets updated with the generated XML data as a result of this method call. The XML data will eventually be returned as a result of encodeRootObjectForKey.

key is used as the XML element and the content is the string representation of f and the element has an attribute type="float". For example, the following call

 encodeFloatForKey(1.23, "myTag");
 

causes the following XML data to be appended to the WOXMLCoder's internal state:

   <myTag type="float">1.23</myTag>
 

key is ignored when a mapping model is used as the model specifies what XML tag to use.

Parameters:

f - the float value to be encoded

key - the XML tag to be used for the XML data generated

See Also:

WOXMLCoder.encodeRootObjectForKey(java.lang.Object, java.lang.String), WOXMLCoding.encodeWithWOXMLCoder(com.webobjects.appserver.xml.WOXMLCoder)

encodeDoubleForKey

public void encodeDoubleForKey(double d,
                               String key)

Encodes a double value into XML data. It is called either implicitly from encodeRootObjectForKey or directly as part of encodeWithWOXMLCoder. Note that nothing is returned from this method but the internal state of WOXMLCoder gets updated with the generated XML data as a result of this method call. The XML data will eventually be returned as a result of encodeRootObjectForKey.

key is used as the XML element and the content is the string representation of d and the element has an attribute type="double". For example, the following call

 encodeDoubleForKey(1.23, "myTag");
 

causes the following XML data to be appended to the WOXMLCoder's internal state:

   <myTag type="double">1.23</myTag>
 

key is ignored when a mapping model is used as the model specifies what XML tag to use.

Parameters:

d - the double value to be encoded

key - the XML tag to be used for the XML data generated

See Also:

WOXMLCoder.encodeRootObjectForKey(java.lang.Object, java.lang.String), WOXMLCoding.encodeWithWOXMLCoder(com.webobjects.appserver.xml.WOXMLCoder)