com.webobjects.foundation.xml
Interface NSXMLObjectOutput

All Known Implementing Classes:

NSXMLOutputStream

public interface NSXMLObjectOutput

This interface provides for converting data from any of the Java primitive types to a series of XML elements. There are also facilities for converting a Java object in a XML element which then includes sub XML elements.

The major difference from java.io.ObjectOutput is that each of the method in this interface takes an extra parameter key, which will be appear as the data of the attribute "key" in the XML element written out. This key can then be used in XSLT to transform the tag name of the XML element. For example:

	6.25  ---> 6.25
 

Thus, key has to be a proper XML attribute value. For example, it cannot be a String of the null character, \U0000. And if you want to use it in XSLT to become a tag name, then it has to be a proper XML tag name. For example, there must not be whitespaces.

There are also a few utility methods that are not found in java.io.ObjectOutput.

Method Summary

boolean	disableReferenceForString() Disables the use of references for repeated Strings in XML output.
int	disableReferenceForString(int length) See disableReferenceForString() for details first.
boolean	enableReferenceForString() Enables the use of references for repeated Strings in XML output.
boolean	setUseBase64ForBinaryData(boolean on) Sets the output mode for binary data (essentially array of bytes) to be either using the Base64 encoding or a simple series of numbers (-128 to 127) delimited by a space.
boolean	useBase64ForBinaryData() Gets the previously set output mode for binary data.
boolean	useReferenceForString() Gets the previously set output behavior for a java.lang.String object.
void	write(byte[] buf, int off, int len, String key) Writes a sub array of bytes.
void	write(byte[] buf, String key) Writes an array of bytes.
void	write(int val, String key) Writes a byte.
void	writeBoolean(boolean val, String key) Writes a boolean.
void	writeByte(int val, String key) Writes an 8 bit byte.
void	writeBytes(String str, String key) Writes a String as a sequence of bytes.
void	writeChar(int val, String key) Writes a 16 bit char.
void	writeChars(String str, String key) Writes a String as a sequence of chars.
void	writeComment(String str) Writes a comment to the XML output.
void	writeDouble(double val, String key) Writes a 64 bit double.
void	writeFloat(float val, String key) Writes a 32 bit float.
void	writeInt(int val, String key) Writes a 32 bit int.
void	writeLong(long val, String key) Writes a 64 bit long.
void	writeObject(Object object, String key) Writes the specified object as XML data.
void	writeRootComment(String str, boolean before) Writes a comment to the XML output.
void	writeShort(int val, String key) Writes a 16 bit short.
void	writeUTF(String str, String key) Primitive data write of this String in UTF format.

Method Detail

disableReferenceForString

public boolean disableReferenceForString()

Disables the use of references for repeated Strings in XML output. Because Strings are objects in general, NSXMLObjectOutput attaches an id attribute by default:

    <string id="39" xml:space="preserve">Well Done!</string>
 

And any repeating output of the same String will just use the idRef attribute feature:

    <string idRef="39" />
 

This saves space in the output and more importantly maintain the integrity of the objects during deserialization: the two Strings are the same object.

However, sometimes you are just concerned about the data itself and want to see the content of the repeated string without following its reference. You can either use the writeUTF method or use this method to globally treat all Strings as different objects. Thus, if you are not using references for String, subsequent output of the same string looks like this:

    <string id="40" xml:space="preserve">Well Done!</string>
 

Returns:

true if the previous behavior is to use references for Strings; false otherwise

See Also:

enableReferenceForString(), disableReferenceForString(int)

disableReferenceForString

public int disableReferenceForString(int length)

See disableReferenceForString() for details first.

The parameter length allows you to further fine tune the disabled effect. It tells NSXMLObjectOutput to revert back to default behavior when length of the string exceeds the length so that long strings will not waste space in the output. For example, when the length is 100, only strings of length 100 or less are written out as they out, without the use of references.

Parameters:

length - the length by which NSXMLObjectOutput reverts to default behavior; -1 means there is no length consideration

Returns:

the previously set length

See Also:

enableReferenceForString(), disableReferenceForString()

enableReferenceForString

public boolean enableReferenceForString()

Enables the use of references for repeated Strings in XML output. Because Strings are objects in general, NSXMLObjectOutput attaches an id attribute by default:

    <string id="39" xml:space="preserve">Well Done!</string>
 

And any repeating output of the same String will just use the idRef attribute feature:

    <string idRef="39" />
 

This saves space in the output and more importantly maintain the integrity of the objects during deserialization: the two Strings are the same object.

This is the default behavior.

Returns:

true if the previous behavior is to use references for Strings; false otherwise

See Also:

disableReferenceForString(), disableReferenceForString(int)

setUseBase64ForBinaryData

public boolean setUseBase64ForBinaryData(boolean on)

Sets the output mode for binary data (essentially array of bytes) to be either using the Base64 encoding or a simple series of numbers (-128 to 127) delimited by a space. The former is the default. Binary data cannot usually be represented as a series of characters because not all characters (e.g. 0x00) can be represented as legal XML characters. Thus, we have the two ways to deal with it. See http://www.w3c.org/TR/2000/REC-xml-20001006#charsets for more details.

Parameters:

on - output mode is Base64 if it is true

Returns:

the previous mode; the default is true

See Also:

useBase64ForBinaryData()

useBase64ForBinaryData

public boolean useBase64ForBinaryData()

Gets the previously set output mode for binary data. The default is true.

Returns:

the output mode for binary data

See Also:

setUseBase64ForBinaryData(boolean)

useReferenceForString

public boolean useReferenceForString()

Gets the previously set output behavior for a java.lang.String object. The default is true.

Returns:

the output behavior

See Also:

enableReferenceForString(), disableReferenceForString(), disableReferenceForString(int)

write

public void write(int val,
                  String key)

Writes a byte.

Parameters:

val - the byte to be written to the stream

key - this will appear as the data of the attribute "key"

write

public void write(byte[] buf,
                  String key)
           throws IOException

Writes an array of bytes.

Parameters:

buf - the data to be written

key - this will appear as the data of the attribute "key"

Throws:

IOException - if I/O errors occur while writing to the underlying stream

write

public void write(byte[] buf,
                  int off,
                  int len,
                  String key)
           throws IOException

Writes a sub array of bytes.

Parameters:

buf - the data to be written

off - the start offset in the data

len - the number of bytes that are written

key - this will appear as the data of the attribute "key"

Throws:

IOException - if I/O errors occur while writing to the underlying stream

writeBoolean

public void writeBoolean(boolean val,
                         String key)

Writes a boolean.

Parameters:

val - the boolean to be written

key - this will appear as the data of the attribute "key"

writeByte

public void writeByte(int val,
                      String key)

Writes an 8 bit byte.

Parameters:

val - the byte value to be written

key - this will appear as the data of the attribute "key"

writeBytes

public void writeBytes(String str,
                       String key)
                throws IOException

Writes a String as a sequence of bytes. Unlike the JDK implementation where each character in str is cast into a byte (and hence information could be lost), the encoding specified by the user (using NSXMLOutputFormat) is used to convert each character to a certain number of bytes.

Parameters:

str - the String of bytes to be written

key - this will appear as the data of the attribute "key"

Throws:

IOException - Any exception thrown by the underlying OutputStream.

writeChar

public void writeChar(int val,
                      String key)

Writes a 16 bit char.

Parameters:

val - the char value to be written

key - this will appear as the data of the attribute "key"

writeChars

public void writeChars(String str,
                       String key)
                throws IOException

Writes a String as a sequence of chars.

Parameters:

str - the String of chars to be written

key - this will appear as the data of the attribute "key"

Throws:

IOException - if I/O errors occur while writing to the underlying stream

writeComment

public void writeComment(String str)

Writes a comment to the XML output. The location is right after the most recent write operation and enclosed within the root element.

Parameters:

comment - the comment to be written out

See Also:

writeRootComment(java.lang.String, boolean)

writeDouble

public void writeDouble(double val,
                        String key)

Writes a 64 bit double.

Parameters:

val - the double value to be written

key - this will appear as the data of the attribute "key"

writeFloat

public void writeFloat(float val,
                       String key)

Writes a 32 bit float.

Parameters:

val - the float value to be written

key - this will appear as the data of the attribute "key"

writeInt

public void writeInt(int val,
                     String key)

Writes a 32 bit int.

Parameters:

val - the integer value to be written

key - this will appear as the data of the attribute "key"

writeLong

public void writeLong(long val,
                      String key)

Writes a 64 bit long.

Parameters:

val - the long value to be written

key - this will appear as the data of the attribute "key"

writeObject

public void writeObject(Object object,
                        String key)
                 throws IOException

Writes the specified object as XML data. The class structure of the object and the values of the non-transient and non-static fields of the class and all of its supertypes are written. Default serialization for a class can be overridden using the writeObject and the readObject methods. Objects referenced by this object are written transitively so that a complete equivalent graph of objects can be reconstructed by an NSXMLInputStream.

Exceptions are thrown for problems with the OutputStream and for classes that should not be serialized. All exceptions are fatal to the OutputStream, which is left in an indeterminate state, and it is up to the caller to ignore or recover the stream state.

Parameters:

obj - the object to be written out

key - this will appear as the data of the attribute "key"

Throws:

InvalidClassException - Something is wrong with a class used by serialization.

NotSerializableException - Some object to be serialized does not implement the java.io.Serializable interface.

IOException - Any exception thrown by the underlying OutputStream.

writeRootComment

public void writeRootComment(String str,
                             boolean before)

Writes a comment to the XML output. The location is either before or after the root element.

Parameters:

comment - the comment to be written out

before - if true, the comment is right before the root element; otherwise, it is right after the root element

See Also:

writeComment(java.lang.String)

writeShort

public void writeShort(int val,
                       String key)

Writes a 16 bit short.

Parameters:

val - the short value to be written

key - this will appear as the data of the attribute "key"

writeUTF

public void writeUTF(String str,
                     String key)

Primitive data write of this String in UTF format. Note that there is a significant difference between writing a String into the stream as primitive data or as an Object. A String instance written by writeObject is written into the stream as a String initially. Future writeObject() calls write references to the string into the stream.

Parameters:

str - the String in UTF format

key - this will appear as the data of the attribute "key"