WebObjects 5.4.2

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 comment)
          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 comment, 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

write

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

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

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

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

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"

writeShort

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"

writeChar

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"

writeInt

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

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"

writeFloat

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"

writeDouble

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"

writeObject

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:
object - 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.

writeBytes

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.

writeChars

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

writeUTF

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"

writeComment

void writeComment(String comment)
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:
NSXMLObjectOutput.writeRootComment(java.lang.String, boolean)

writeRootComment

void writeRootComment(String comment,
                      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:
NSXMLObjectOutput.writeComment(java.lang.String)

setUseBase64ForBinaryData

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:
NSXMLObjectOutput.useBase64ForBinaryData()

useBase64ForBinaryData

boolean useBase64ForBinaryData()
Gets the previously set output mode for binary data. The default is true.

Returns:
the output mode for binary data
See Also:
NSXMLObjectOutput.setUseBase64ForBinaryData(boolean)

enableReferenceForString

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:
NSXMLObjectOutput.disableReferenceForString(), NSXMLObjectOutput.disableReferenceForString(int)

disableReferenceForString

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:
NSXMLObjectOutput.enableReferenceForString(), NSXMLObjectOutput.disableReferenceForString(int)

disableReferenceForString

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:
NSXMLObjectOutput.enableReferenceForString(), NSXMLObjectOutput.disableReferenceForString()

useReferenceForString

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

Returns:
the output behavior
See Also:
NSXMLObjectOutput.enableReferenceForString(), NSXMLObjectOutput.disableReferenceForString(), NSXMLObjectOutput.disableReferenceForString(int)

Last updated June 2008

Copyright © 2000-2008 Apple Inc.