com.wm.util.coder

Class XMLCoder

java.lang.Object

com.wm.util.coder.Coder

com.wm.util.coder.XMLCoder

public class XMLCoder
extends Coder

This class extends Coder and contains methods you use to encode Values objects as XML documents and decode XML documents as Values objects. These methods are often used to transform a Values object into an XML document (typically so you can easily store it to a file) and regenerate the Values object from the XML document at a later time.

Important: If you use XMLCoder to encode Values objects, then you MUST use XMLCoder. to decode it. Although webMethods may change the XML format produced by this class in the future, it will always remain backwardly compatible. If you modify the XML outside of XMLCoder methods, you might not be able to decode that XML in a future release.

XMLCoder can encode Values objects that contain any of the following Object types.

Primary Types

ValuesCodable	StringCodable	IDataCodable (when decoded creates a Values object)
Values	Codable	Vector
Number	String	IData (when decoded creates a Values object)

Array Types

String[]	IData[]> (when decoded creates a Values[] object)	IDataCodable[] (when decoded creates a Values[] object)
Object[]	String[][]	Vector

Objects other than those listed above are not supported, and XMLCoder will not encode or decode them. If an unsupported object is contained in a Values object that you are encoding, XMLCoder will post a warning message to the debug log.

Note: We recommend that you use the UTF8 character set to encode and decode your XML documents to ensure that your solution is compatible with international character sets.

See Also:

XMLCoderWrapper, IDataXMLCoder, Codable, IDataCodable, StringCodable, ValuesCodable

Constructor Summary

Constructors

Constructor and Description
XMLCoder() Constructs an XMLCoder object that defaults to file.encoding for encoding and decoding XML
XMLCoder(boolean utf8) Constructs an XMLCoder object that uses the UTF8 character set to encode to and decode XML documents.

Method Summary

Modifier and Type	Method and Description
Values	decode(java.io.InputStream is) Decodes the XML in the specified InputStream to a Values object.
void	encode(java.io.OutputStream os, Values data) Encodes the specified Values object as an XML document and writes that document to an OutputStream.
java.lang.String	getContentType() Returns a String object indicating the current content type.
void	setContentType(java.lang.String ctype) Sets the content type.
void	setIgnoreInvalid(boolean ignore) Sets a boolean flag that specifies whether this XMLCoder ignores unsupported object types in the data that it encodes or decodes.
void	setRootTag(java.lang.String tag) Specifies the root tag for XML.
void	setUseOIDs(boolean use) Specifies whether Object Identifiers (OIDs) are assigned to object values.
void	setUseUTF8(boolean use) Sets a boolean flag that specifies whether the UTF8 character set is used to encode and decode XML.
void	setUseXMLHeader(boolean use) Sets a boolean flag that specifies whether or not an XML header (for example, <?xml version="1.0" encoding "UTF-8" >) is included in the XML document.

Methods inherited from class com.wm.util.coder.Coder

decodeFromBytes, encodeToBytes, readFromFile, readFully, writeToFile

Methods inherited from class java.lang.Object

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

Constructor Detail

XMLCoder

public XMLCoder()

Constructs an XMLCoder object that defaults to file.encoding for encoding and decoding XML

XMLCoder

public XMLCoder(boolean utf8)

Constructs an XMLCoder object that uses the UTF8 character set to encode to and decode XML documents.

Parameters:

utf8 - A boolean specifying whether this XMLCoder will use UTF8 character set when encoding to or decoding from XML.

Set utf8 to…	To…
true	Use UTF8 character sets
false	Use file.encoding (default)

Method Detail

decode

public Values decode(java.io.InputStream is)
              throws java.io.IOException,
                     InvalidDatatypeException

Decodes the XML in the specified InputStream to a Values object. If useUTF8 is true then the XML is decoded from the InputStream using the encoding specified in the XML declaration. If no encoding information is specified in the XML declaration or useUTF8 is false, then file.encoding is used (for backward compatibility).

Specified by:

decode in class Coder

Parameters:

is - An InputStream that originates from a specific XML source.

Returns:

The Values object decoded from is.

Throws:

java.io.IOException - If an error occurs while reading InputStream.

InvalidDatatypeException - If the XML in InputStream cannot be decoded or it contains an unsupported object type and setIgnoreInvalid is false.

See Also:

setIgnoreInvalid(boolean), setUseUTF8(boolean), encode(java.io.OutputStream, com.wm.util.Values)

encode

public void encode(java.io.OutputStream os,
                   Values data)
            throws java.io.IOException,
                   InvalidDatatypeException

Encodes the specified Values object as an XML document and writes that document to an OutputStream. If useUTF8 is true, then the encoding declaration encoding='UTF8' is included in the XML declaration. If useUTF8 is false, then file.encoding is used (for backward compatibility) and the encoding declaration is omitted from the XML declaration.

Specified by:

encode in class Coder

Parameters:

os - The OutputStream into which you want the XML-encoded Values object written.

data - The Values object that you want to encode.

Throws:

java.io.IOException - If error occurs while writing to the OutputStream.

InvalidDataTypeException - If the Values object contains an unsupported object type and setIgnoreInvalid is false.

InvalidDatatypeException - If the data in the Values object cannot be encoded (i.e., the Values object contains an object type that is not supported by the specific implementation of encode that you are using.)

See Also:

setIgnoreInvalid(boolean), setUseUTF8(boolean), decode(java.io.InputStream)

getContentType

public java.lang.String getContentType()

Returns a String object indicating the current content type. The default content type for XMLCoder objects is: text/xml

Specified by:

getContentType in class Coder

Returns:

A String containing the content type for this XMLCoder.

See Also:

setContentType(java.lang.String)

setContentType

public void setContentType(java.lang.String ctype)

Sets the content type. The default content type for XMLCoder is "text/xml". The coder classes, IDataXMLCoder and XMLCoder, both support the default content type. This method enables support for custom content types.

Note: If you want to use the standard webMethods ContentHandler, then do not use this method to override the default content type with a custom one.

Parameters:

ctype - A String specifying the content type for this XMLCoder.

See Also:

getContentType()

setIgnoreInvalid

public void setIgnoreInvalid(boolean ignore)

Sets a boolean flag that specifies whether this XMLCoder ignores unsupported object types in the data that it encodes or decodes. The default is to ignore unsupported object types.

Parameters:

ignore - A boolean specifying whether unsupported objects are ignored.

Set ignore to…	To…
true	Ignore unsupported objects types when encountered (default).
false	Throw an InvalidDataTypeException when an unsupported object type is encountered.

setRootTag

public void setRootTag(java.lang.String tag)

Specifies the root tag for XML. The default root tag is Values. Generally, you should not change the root tag, because other supporting classes such as XMLCoderWrapper will not be able to understand the encoded data.

Note: If you need to set the root tag, set it before using the writeToFile or readFromFile methods.

Parameters:

tag - A String specifying the root tag.

setUseOIDs

public void setUseOIDs(boolean use)

Specifies whether Object Identifiers (OIDs) are assigned to object values. Assigning an OID to each object value better utilizes disk space, but demands more CPU usage and run-time memory (especially for large value sets). The default is to omit OIDs.

Parameters:

use - A boolean specifying whether to assign Object Identifiers (OID) to each object value.

Set use to…	To…
true	Assign OIDs to object values.
false	Omit OIDs from object values.

setUseUTF8

public void setUseUTF8(boolean use)

Sets a boolean flag that specifies whether the UTF8 character set is used to encode and decode XML.

Note: We recommend that you use the UTF8 character set to encode and decode your XML documents to ensure that your solution is compatible with international character sets.

Parameters:

use - A boolean specifying whether this XMLCoder will use the UTF8 character set to encode and decode XML.

Set use to…	To…
true	Use UTF8 character sets. When set to true, XMLCoder includes the encoding declaration encoding='UTF8' in the XML it generates.
false	Use file.encoding. When set to false, XMLCoder omits the encoding declaration from the XML it generates. (default)

setUseXMLHeader

public void setUseXMLHeader(boolean use)

Sets a boolean flag that specifies whether or not an XML header (for example, <?xml version="1.0" encoding "UTF-8" >) is included in the XML document. The default behavior is to include the XML header.

Parameters:

use - A boolean specifying whether this XMLCoder will include an XML header when it encodes a Values object as XML.

Set use to…	To…
true	Include the XML header. (default)
false	Omit the XML header.