com.webobjects.foundation.xml
Class NSXMLOutputStream

java.lang.Object
  java.io.OutputStream
      java.io.ObjectOutputStream
          com.webobjects.foundation.xml.NSXMLOutputStream

All Implemented Interfaces:

NSXMLObjectOutput, NSXMLObjectStreamConstants, Closeable, DataOutput, Flushable, ObjectOutput, ObjectStreamConstants

public class NSXMLOutputStream
extends ObjectOutputStream
implements NSXMLObjectStreamConstants, NSXMLObjectOutput

An NSXMLOutputStream writes primitive data types and graphs of Java objects to an OutputStream as XML data. The objects can be read (reconstituted) using an NSXMLInputStream. Persistent storage of objects can be accomplished by using a file for the stream. If the stream is a network socket stream, the objects can be reconsituted on another host or in another process.

Only objects that support the java.io.Serializable interface can be written to streams. The class structure of each serializable object is encoded including the class name and the super classes, the values of the object's fields and arrays, and the closure of any other objects referenced from the initial objects.

The method writeObject is used to write an object to the stream. Any object, including Strings and arrays, is written with writeObject. Multiple objects or primitives can be written to the stream. The objects must be read back from the corresponding NSXMLInputstream with the same types and in the same order as they were written.

Primitive data types can also be written to the stream using the appropriate methods from DataOutput. Strings can also be written using the writeUTF method.

The default serialization mechanism for an object writes the class structure of the object and the values of all non-transient and non-static fields. References to other objects (except in transient or static fields) cause those objects to be written also. Multiple references to a single object are encoded using a reference sharing mechanism so that graphs of objects can be restored to the same shape as when the original was written. Reader is encouraged to consult the serialization specification to understand how and when each reference number is assigned if there is a need to.

For example to write an object that can be read by the corresponding example in NSXMLInputStream:

 FileOutputStream ostream = new FileOutputStream("t.tmp");
 NSXMLOutputStream p = new NSXMLOutputStream(ostream);
 if (p instanceof NSXMLOutputStream) {
        NSXMLOutputFormat format = new NSXMLOutputFormat();
        p.setOutputFormat(format);
        p.writeRootComment("Writing comment", true);
 }

 p.writeInt(12345);
 p.writeObject("Today");
 p.writeObject(new Date());

 p.flush();
 p.close();
 

The default XML output is:

      <?xml version="1.0" encoding="UTF-8"?>
      <!--Writing comment-->
      <content xmlns="http://www.apple.com/webobjects/XMLSerialization"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.apple.com/webobjects/XMLSerialization http://www.apple.com/webobjects/5.2/schemas/woxml.xsd">

          <int>12345</int>

          <string id="0" xml:space="preserve">Today</string>

          <object id="2">
              <class flag="3" id="1" name="java.util.Date" suid="7523967970034938905"/>
              <long ignoreEDB="1">1026763105869</long>
          </object>

      </content>
 

Classes that require special handling during the serialization and deserialization process must implement special methods with these exact signatures:

   private void readObject(java.io.ObjectInputStream stream)
       throws java.io.IOException, ClassNotFoundException;
   private void writeObject(java.io.ObjectOutputStream stream)
       throws java.io.IOException
 

The writeObject method is responsible for writing the state of the object for its particular class so that the corresponding readObject method can restore it. The method does not need to concern itself with the state belonging to the object's superclasses or subclasses. State is saved by writing the individual fields to the NSXMLOutputStream using the writeObject method or by using the methods for primitive data types supported by DataOutput.

Serialization does not write out the fields of any object that does not implement the java.io.Serializable interface. Subclasses of Objects that are not serializable can be serializable. In this case the non-serializable class must have a no-arg constructor to allow its fields to be initialized. In this case it is the responsibility of the subclass to save and restore the state of the non-serializable class. It is frequently the case that the fields of that class are accessible (public, package, or protected) or that there are get and set methods that can be used to restore the state.

Serialization of an object can be prevented by implementing writeObject and readObject methods that throw the NotSerializableException. The exception will be caught by the ObjectOutputStream and abort the serialization process.

Implementing the Externalizable interface allows the object to assume complete control over the contents and format of the object's serialized form. The methods of the Externalizable interface, writeExternal and readExternal, are called to save and restore the objects state. When implemented by a class they can write and read their own state using all of the methods of ObjectOutput and ObjectInput. It is the responsibility of the objects to handle any versioning that occurs.

We provided a simple interface NSXMLObjectOutput that would add a key as an attribute to the XML element representing the primitive data or the object. This key can then be used in XSLT to transform the tag name of the XML element. For example:

      <float key="InterestRate">6.25</float>  ---> <InterestRate>6.25</InterestRate>
 

See Also:

DataOutput, ObjectInputStream, Serializable, Externalizable

Nested Class Summary

Nested classes/interfaces inherited from class java.io.ObjectOutputStream

ObjectOutputStream.PutField

Field Summary

Fields inherited from interface com.webobjects.foundation.xml.NSXMLObjectStreamConstants

ARRAY_TAG, BOOLEAN_TAG, BYTE_TAG, CHAR_TAG, CLASS_ATTR, CLASS_TAG, CONTENT_TAG, DOUBLE_TAG, EXCEPTION_TAG, FIELD_ATTR, FIELD_TAG, FLAG_ATTR, FLOAT_TAG, ID_ATTR, IDREF_ATTR, IGNORE_ATTR, INT_TAG, INTERFACE_TAG, KEY_ATTR, LENGTH_ATTR, LONG_TAG, NAME_ATTR, NAMESPACE, OBJECT_TAG, PROXY_TAG, SHORT_TAG, STRING_TAG, SUID_ATTR, SUPER_TAG, TYPE_ATTR

Fields inherited from interface java.io.ObjectStreamConstants

baseWireHandle, PROTOCOL_VERSION_1, PROTOCOL_VERSION_2, SC_BLOCK_DATA, SC_ENUM, SC_EXTERNALIZABLE, SC_SERIALIZABLE, SC_WRITE_METHOD, STREAM_MAGIC, STREAM_VERSION, SUBCLASS_IMPLEMENTATION_PERMISSION, SUBSTITUTION_PERMISSION, TC_ARRAY, TC_BASE, TC_BLOCKDATA, TC_BLOCKDATALONG, TC_CLASS, TC_CLASSDESC, TC_ENDBLOCKDATA, TC_ENUM, TC_EXCEPTION, TC_LONGSTRING, TC_MAX, TC_NULL, TC_OBJECT, TC_PROXYCLASSDESC, TC_REFERENCE, TC_RESET, TC_STRING

Constructor Summary

NSXMLOutputStream(OutputStream out)
Creates an ObjectOutputStream that writes to the specified OutputStream.

NSXMLOutputStream(OutputStream out, File xslt)
Creates an ObjectOutputStream that writes to the specified OutputStream.

NSXMLOutputStream(OutputStream out, InputSource xslt)
Creates an ObjectOutputStream that writes to the specified OutputStream.

NSXMLOutputStream(OutputStream out, Transformer transformer)
Creates an ObjectOutputStream that writes to the specified OutputStream.

Method Summary

void	close() Closes the stream.
void	defaultWriteObject() Write the non-static and non-transient fields of the current class to this stream.
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.
void	flush() Flushes the stream.
NSXMLOutputFormat	outputFormat() Gets the current NSXMLOutputFormat object.
ObjectOutputStream.PutField	putFields() Retrieve the object used to buffer persistent fields to be written to the stream.
void	reset() Reset will disregard the state of any objects already written to the stream.
void	setOutputFormat(NSXMLOutputFormat format) Sets the current NSXMLOutputFormat object that will be used to change the format of the XML output.
void	setTransformer(Transformer transformer) Sets the XSLT transformer that will be used to transform the XML output before the it is written out.
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.
void	setXSLTSource(File xslt) Sets the XSLT stylesheet that will be used to transform the XML output before the it is written out.
void	setXSLTSource(InputSource xslt) Sets the XSLT stylesheet that will be used to transform the XML output before the it is written out.
Transformer	transformer() Gets the XSLT transformer that will be used to transform the XML output before the it is written out.
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) Writes an array of bytes.
void	write(byte[] buf, int off, int len) Writes a sub array of bytes.
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) Writes a byte.
void	write(int val, String key) Writes a byte.
void	writeBoolean(boolean val) Writes a boolean.
void	writeBoolean(boolean val, String key) Writes a boolean.
void	writeByte(int val) Writes an 8 bit byte.
void	writeByte(int val, String key) Writes an 8 bit byte.
void	writeBytes(String str) Writes a String as a sequence of bytes.
void	writeBytes(String str, String key) Writes a String as a sequence of bytes.
void	writeChar(int val) Writes a 16 bit char.
void	writeChar(int val, String key) Writes a 16 bit char.
void	writeChars(String str) Writes a String as a sequence of chars.
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) Writes a 64 bit double.
void	writeDouble(double val, String key) Writes a 64 bit double.
void	writeFields() Write the buffered fields to the stream.
void	writeFloat(float val) Writes a 32 bit float.
void	writeFloat(float val, String key) Writes a 32 bit float.
void	writeInt(int val) Writes a 32 bit int.
void	writeInt(int val, String key) Writes a 32 bit int.
void	writeLong(long val) Writes a 64 bit long.
void	writeLong(long val, String key) Writes a 64 bit long.
void	writeObject(Object obj, String key) Writes the specified object as XML data.
protected void	writeObjectOverride(Object obj) Method used by subclasses to override the default writeObject method.
void	writeRootComment(String comment, boolean before) Writes a comment to the XML output.
void	writeShort(int val) Writes a 16 bit short.
void	writeShort(int val, String key) Writes a 16 bit short.
protected void	writeStreamHeader() The writeStreamHeader method is provided so subclasses can append or prepend their own header to the stream.
void	writeUTF(String str) Primitive data write of this String in UTF format.
void	writeUTF(String str, String key) Primitive data write of this String in UTF format.

Methods inherited from class java.io.ObjectOutputStream

annotateClass, annotateProxyClass, drain, enableReplaceObject, replaceObject, useProtocolVersion, writeClassDescriptor, writeObject, writeUnshared

Methods inherited from class java.lang.Object

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

Constructor Detail

NSXMLOutputStream

public NSXMLOutputStream(OutputStream out,
                         File xslt)
                  throws IOException

Creates an ObjectOutputStream that writes to the specified OutputStream.

If a security manager is installed, this constructor will check for the "enableSubclassImplementation" SerializablePermission.

Parameters:

out - output stream to write to

xslt - XSLT stylesheet that will be used to transform the XML output before the it is written to out; the File reference must be non null

Throws:

IOException - if an I/O error occurs while writing stream header

SecurityException - if the "enableSubclassImplementation" SerializablePermission is not allowed

See Also:

NSXMLOutputStream.NSXMLOutputStream(OutputStream), NSXMLOutputStream.NSXMLOutputStream(OutputStream, InputSource), NSXMLOutputStream.NSXMLOutputStream(OutputStream, Transformer), NSXMLOutputStream.putFields(), NSXMLInputStream.NSXMLInputStream(InputStream)

NSXMLOutputStream

public NSXMLOutputStream(OutputStream out,
                         InputSource xslt)
                  throws IOException

Creates an ObjectOutputStream that writes to the specified OutputStream.

If a security manager is installed, this constructor will check for the "enableSubclassImplementation" SerializablePermission.

Parameters:

out - output stream to write to

xslt - XSLT stylesheet that will be used to transform the XML output before the it is written to out

Throws:

IOException - if an I/O error occurs while writing stream header

SecurityException - if the "enableSubclassImplementation" SerializablePermission is not allowed

See Also:

NSXMLOutputStream.NSXMLOutputStream(OutputStream, File), NSXMLOutputStream.NSXMLOutputStream(OutputStream), NSXMLOutputStream.NSXMLOutputStream(OutputStream, Transformer), NSXMLOutputStream.putFields(), NSXMLInputStream.NSXMLInputStream(InputStream), InputSource

NSXMLOutputStream

public NSXMLOutputStream(OutputStream out,
                         Transformer transformer)
                  throws IOException

Creates an ObjectOutputStream that writes to the specified OutputStream.

If a security manager is installed, this constructor will check for the "enableSubclassImplementation" SerializablePermission.

Parameters:

out - output stream to write to

transformer - XSLT transformer that will be used to transform the XML output before the it is written to out

Throws:

IOException - if an I/O error occurs while writing stream header

SecurityException - if the "enableSubclassImplementation" SerializablePermission is not allowed

See Also:

NSXMLOutputStream.NSXMLOutputStream(OutputStream, File), NSXMLOutputStream.NSXMLOutputStream(OutputStream, Transformer), NSXMLOutputStream.NSXMLOutputStream(OutputStream), NSXMLOutputStream.putFields(), NSXMLInputStream.NSXMLInputStream(InputStream), Transformer

NSXMLOutputStream

public NSXMLOutputStream(OutputStream out)
                  throws IOException

Creates an ObjectOutputStream that writes to the specified OutputStream.

If a security manager is installed, this constructor will check for the "enableSubclassImplementation" SerializablePermission.

Parameters:

out - output stream to write to

Throws:

IOException - if an I/O error occurs while writing stream header

SecurityException - if the "enableSubclassImplementation" SerializablePermission is not allowed

See Also:

NSXMLOutputStream.NSXMLOutputStream(OutputStream, File), NSXMLOutputStream.NSXMLOutputStream(OutputStream, InputSource), NSXMLOutputStream.NSXMLOutputStream(OutputStream, Transformer), NSXMLOutputStream.putFields(), NSXMLInputStream.NSXMLInputStream(InputStream)

Method Detail

writeStreamHeader

protected void writeStreamHeader()
                          throws IOException

The writeStreamHeader method is provided so subclasses can append or prepend their own header to the stream.

Overrides:

writeStreamHeader in class ObjectOutputStream

Throws:

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

writeObjectOverride

protected void writeObjectOverride(Object obj)
                            throws IOException

Method used by subclasses to override the default writeObject method.

Overrides:

writeObjectOverride in class ObjectOutputStream

Parameters:

obj - object to be written to the underlying stream

Throws:

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

See Also:

NSXMLOutputStream.NSXMLOutputStream(OutputStream), ObjectOutputStream.writeObject(Object)

setXSLTSource

public void setXSLTSource(File xslt)
                   throws IOException

Sets the XSLT stylesheet that will be used to transform the XML output before the it is written out.

Parameters:

xslt - the File reference to the stylesheet; must be non null

Throws:

IOException

setXSLTSource

public void setXSLTSource(InputSource xslt)
                   throws IOException

Sets the XSLT stylesheet that will be used to transform the XML output before the it is written out.

Parameters:

xslt - the InputSource to the stylesheet

Throws:

IOException

See Also:

InputSource

setTransformer

public void setTransformer(Transformer transformer)

Sets the XSLT transformer that will be used to transform the XML output before the it is written out.

Parameters:

transformer - the XSLT transformer

See Also:

Transformer

transformer

public Transformer transformer()

Gets the XSLT transformer that will be used to transform the XML output before the it is written out. User can use it to change the output properties.

See Also:

Transformer, Transformer.setOutputProperty(java.lang.String, java.lang.String)

outputFormat

public NSXMLOutputFormat outputFormat()

Gets the current NSXMLOutputFormat object.

See Also:

NSXMLOutputFormat

setOutputFormat

public void setOutputFormat(NSXMLOutputFormat format)

Sets the current NSXMLOutputFormat object that will be used to change the format of the XML output.

See Also:

NSXMLOutputFormat

defaultWriteObject

public void defaultWriteObject()
                        throws IOException

Write the non-static and non-transient fields of the current class to this stream. This may only be called from the writeObject method of the class being serialized. It will throw the NotActiveException if it is called otherwise.

Overrides:

defaultWriteObject in class ObjectOutputStream

Throws:

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

putFields

public ObjectOutputStream.PutField putFields()
                                      throws IOException

Retrieve the object used to buffer persistent fields to be written to the stream. The fields will be written to the stream when writeFields method is called.

Overrides:

putFields in class ObjectOutputStream

Returns:

an instance of the class Putfield that holds the serializable fields

Throws:

IOException - if I/O errors occur

writeFields

public void writeFields()
                 throws IOException

Write the buffered fields to the stream.

Overrides:

writeFields in class ObjectOutputStream

Throws:

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

NotActiveException - Called when a classes writeObject method was not called to write the state of the object.

write

public void write(int val)
           throws IOException

Writes a byte.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Overrides:

write in class ObjectOutputStream

Parameters:

val - the byte to be written to the stream

Throws:

IOException - If an I/O error has occurred.

write

public void write(byte[] buf)
           throws IOException

Writes an array of bytes.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Overrides:

write in class ObjectOutputStream

Parameters:

buf - the data to be written

Throws:

IOException - If an I/O error has occurred.

write

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

Writes a sub array of bytes.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Overrides:

write in class ObjectOutputStream

Parameters:

buf - the data to be written

off - the start offset in the data

len - the number of bytes that are written

Throws:

IOException - If an I/O error has occurred.

writeBoolean

public void writeBoolean(boolean val)
                  throws IOException

Writes a boolean.

Specified by:

writeBoolean in interface DataOutput

Overrides:

writeBoolean in class ObjectOutputStream

Parameters:

val - the boolean to be written

Throws:

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

writeByte

public void writeByte(int val)
               throws IOException

Writes an 8 bit byte.

Specified by:

writeByte in interface DataOutput

Overrides:

writeByte in class ObjectOutputStream

Parameters:

val - the byte value to be written

Throws:

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

writeShort

public void writeShort(int val)
                throws IOException

Writes a 16 bit short.

Specified by:

writeShort in interface DataOutput

Overrides:

writeShort in class ObjectOutputStream

Parameters:

val - the short value to be written

Throws:

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

writeChar

public void writeChar(int val)
               throws IOException

Writes a 16 bit char.

Specified by:

writeChar in interface DataOutput

Overrides:

writeChar in class ObjectOutputStream

Parameters:

val - the char value to be written

Throws:

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

writeInt

public void writeInt(int val)
              throws IOException

Writes a 32 bit int.

Specified by:

writeInt in interface DataOutput

Overrides:

writeInt in class ObjectOutputStream

Parameters:

val - the integer value to be written

Throws:

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

writeLong

public void writeLong(long val)
               throws IOException

Writes a 64 bit long.

Specified by:

writeLong in interface DataOutput

Overrides:

writeLong in class ObjectOutputStream

Parameters:

val - the long value to be written

Throws:

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

writeFloat

public void writeFloat(float val)
                throws IOException

Writes a 32 bit float.

Specified by:

writeFloat in interface DataOutput

Overrides:

writeFloat in class ObjectOutputStream

Parameters:

val - the float value to be written

Throws:

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

writeDouble

public void writeDouble(double val)
                 throws IOException

Writes a 64 bit double.

Specified by:

writeDouble in interface DataOutput

Overrides:

writeDouble in class ObjectOutputStream

Parameters:

val - the double value to be written

Throws:

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

writeBytes

public void writeBytes(String str)
                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.

Specified by:

writeBytes in interface DataOutput

Overrides:

writeBytes in class ObjectOutputStream

Parameters:

str - the String of bytes to be written

Throws:

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

writeChars

public void writeChars(String str)
                throws IOException

Writes a String as a sequence of chars.

Specified by:

writeChars in interface DataOutput

Overrides:

writeChars in class ObjectOutputStream

Parameters:

str - the String of chars to be written

Throws:

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

writeUTF

public void writeUTF(String str)
              throws IOException

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.

Specified by:

writeUTF in interface DataOutput

Overrides:

writeUTF in class ObjectOutputStream

Parameters:

str - the String in UTF format

Throws:

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

reset

public void reset()
           throws IOException

Reset will disregard the state of any objects already written to the stream. The state is reset to be the same as a new NSXMLOutputStream.

Overrides:

reset in class ObjectOutputStream

Throws:

IOException - if reset() is invoked while serializing an object.

flush

public void flush()
           throws IOException

Flushes the stream. Nothing happens at this point. Use close() to do the final flush.

Specified by:

flush in interface Flushable

Specified by:

flush in interface ObjectOutput

Overrides:

flush in class ObjectOutputStream

Throws:

IOException - If an I/O error has occurred.

close

public void close()
           throws IOException

Closes the stream. This method must be called to release any resources associated with the stream.

Specified by:

close in interface Closeable

Specified by:

close in interface ObjectOutput

Overrides:

close in class ObjectOutputStream

Throws:

IOException - If an I/O error has occurred.

write

public void write(int val,
                  String key)

Writes a byte.

Specified by:

write in interface NSXMLObjectOutput

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

Description copied from interface: NSXMLObjectOutput

Writes an array of bytes.

Specified by:

write in interface NSXMLObjectOutput

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

Description copied from interface: NSXMLObjectOutput

Writes a sub array of bytes.

Specified by:

write in interface NSXMLObjectOutput

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.

Specified by:

writeBoolean in interface NSXMLObjectOutput

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.

Specified by:

writeByte in interface NSXMLObjectOutput

Parameters:

val - the byte value to be written

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

writeShort

public void writeShort(int val,
                       String key)

Writes a 16 bit short.

Specified by:

writeShort in interface NSXMLObjectOutput

Parameters:

val - the short value to be written

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

writeChar

public void writeChar(int val,
                      String key)

Writes a 16 bit char.

Specified by:

writeChar in interface NSXMLObjectOutput

Parameters:

val - the char 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.

Specified by:

writeInt in interface NSXMLObjectOutput

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.

Specified by:

writeLong in interface NSXMLObjectOutput

Parameters:

val - the long 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.

Specified by:

writeFloat in interface NSXMLObjectOutput

Parameters:

val - the float value to be written

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

writeDouble

public void writeDouble(double val,
                        String key)

Writes a 64 bit double.

Specified by:

writeDouble in interface NSXMLObjectOutput

Parameters:

val - the double value to be written

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

writeObject

public void writeObject(Object obj,
                        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.

Specified by:

writeObject in interface NSXMLObjectOutput

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.

writeBytes

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

Description copied from interface: NSXMLObjectOutput

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.

Specified by:

writeBytes in interface NSXMLObjectOutput

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

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

Writes a String as a sequence of chars.

Specified by:

writeChars in interface NSXMLObjectOutput

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

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.

Specified by:

writeUTF in interface NSXMLObjectOutput

Parameters:

str - the String in UTF format

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

writeComment

public 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.

Specified by:

writeComment in interface NSXMLObjectOutput

Parameters:

comment - the comment to be written out

See Also:

NSXMLOutputStream.writeRootComment(String comment, boolean before)

writeRootComment

public void writeRootComment(String comment,
                             boolean before)

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

Specified by:

writeRootComment in interface NSXMLObjectOutput

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:

NSXMLOutputStream.writeComment(String comment)

setUseBase64ForBinaryData

public final boolean setUseBase64ForBinaryData(boolean on)

Description copied from interface: NSXMLObjectOutput

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.

Specified by:

setUseBase64ForBinaryData in interface NSXMLObjectOutput

Parameters:

on - output mode is Base64 if it is true

Returns:

the previous mode; the default is true

See Also:

NSXMLObjectOutput.useBase64ForBinaryData()

useBase64ForBinaryData

public final boolean useBase64ForBinaryData()

Description copied from interface: NSXMLObjectOutput

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

Specified by:

useBase64ForBinaryData in interface NSXMLObjectOutput

Returns:

the output mode for binary data

See Also:

NSXMLObjectOutput.setUseBase64ForBinaryData(boolean)

enableReferenceForString

public boolean enableReferenceForString()

Description copied from interface: NSXMLObjectOutput

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.

Specified by:

enableReferenceForString in interface NSXMLObjectOutput

Returns:

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

See Also:

NSXMLObjectOutput.disableReferenceForString(), NSXMLObjectOutput.disableReferenceForString(int)

disableReferenceForString

public boolean disableReferenceForString()

Description copied from interface: NSXMLObjectOutput

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>
 

Specified by:

disableReferenceForString in interface NSXMLObjectOutput

Returns:

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

See Also:

NSXMLObjectOutput.enableReferenceForString(), NSXMLObjectOutput.disableReferenceForString(int)

disableReferenceForString

public int disableReferenceForString(int length)

Description copied from interface: NSXMLObjectOutput

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.

Specified by:

disableReferenceForString in interface NSXMLObjectOutput

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

public boolean useReferenceForString()

Description copied from interface: NSXMLObjectOutput

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

Specified by:

useReferenceForString in interface NSXMLObjectOutput

Returns:

the output behavior

See Also:

NSXMLObjectOutput.enableReferenceForString(), NSXMLObjectOutput.disableReferenceForString(), NSXMLObjectOutput.disableReferenceForString(int)