org.tm4j.topicmap.utils
Class TopicMapSerializer

java.lang.Object
  org.tm4j.topicmap.utils.HelperBase
      org.tm4j.topicmap.utils.TopicMapSerializer

public class TopicMapSerializer

extends HelperBase

A subclass of HelperBase capable of serializing a TopicMap to an OutputStream. A typical usage pattern for instances of this class is this:

• Construct an instance of TopicMapSerializer.
• (optional) Register event listeners so you can deal with property changes. See below for a list of bound properties supported by this class. Changes to most of the properties supported by this class are vetoable, so you are able to register a VetoableChangeListener and provide for consistency or sanity checks.
• (optional) Register a jakarta-commons Log to receive log messages.
• (optional) Set properties using their setter methods. You can skip this step if you prefer to use the default property values.
• Set the output stream using setOutputStream(OutputStream). Alternatively, you may also use setOutputFile(File) or setOutputFile(String) to write directly to a file.
• Set the topic map to be serialized using setTopicMap(TopicMap).
• Invoke serialize() to perform the actual serialization. When serialization is complete, the output stream is flushed, but not closed.
• (optional) Close the output stream using closeOutputStream().

This class supports the following "bound" properties, changes to which are vetoable by registered VetoableChangeListeners:

• "topicMap" (TopicMap, read/write). The topic map to be serialized.
• "outputStream" (OutputStream, read/write). The output stream to which the topic map is serialized.
• "includeDoctype" (boolean, read/write). If true, the result document will contain a <!DOCTYPE> declaration, if false, that declaration is omitted. If false, no indentation is used. The default is true.
• "systemId" (String, read/write). The System identifier to be used in the document type declaration of the output document. The default is the System ID for XTM 1.0. This property is ignored if "includeDoctype" is false.
• "publicId" (String, read/write). The Public identifier to be used in the document type declaration of the output document. The default is the Public ID for XTM 1.0. This property is ignored if "includeDoctype" is false.
• "encoding" (String, read/write). The output encoding to be used during serialization. The default is UTF-8.
• "indentation" (int, read/write). The number of space characters used to indent the serialized output. The default is 2.
• "logger" (org.apache.commons.logging.Log, read/write). The jakarta-commons log to receive logging messages. The default is null, which will cause any debugging output, except "fatal" messages, to be suppressed. This property is inherited from the superclass.

In addition to the above, the following non-vetoable property is defined for this class:

• "serialized" (boolean, read-only). true if the result has been properly serialized, false otherwise. The default (prior to serialization) is false.

Since:

0.8.4

Author:

Florian G. Haas

Field Summary

protected static java.lang.String	DEFAULT_ENCODING The default output encoding.
protected static boolean	DEFAULT_INCLUDE_DOCTYPE The default setting for including a document type declaration in the output.
protected static int	DEFAULT_INDENT The default setting for indenting the output.
protected static java.io.OutputStream	DEFAULT_OUTPUT_STREAM The default serialization output stream.
static java.lang.String	XTM_PUBLIC_ID The XTM 1.0 system ID.
static java.lang.String	XTM_SYSTEM_ID The XTM 1.0 system ID.

Constructor Summary

TopicMapSerializer()
Constructs a new instance.

TopicMapSerializer(TopicMap topicMap)
Constructs a new instance, initializing it with an existing TopicMap.

TopicMapSerializer(TopicMap topicMap, java.io.File file)
Constructs a new instance, initializing it with an existing TopicMap and an output File to serialize to.

TopicMapSerializer(TopicMap topicMap, java.io.OutputStream stream)
Constructs a new instance, initializing it with an existing TopicMap and an OutputStream to serialize to.

TopicMapSerializer(TopicMap topicMap, java.lang.String path)
Constructs a new instance, initializing it with an existing TopicMap and the path to an output File to serialize to.

Method Summary

void	closeOutputStream() A convenience method that closes the output stream.
java.lang.String	getEncoding() Retrieves the character encoding to be used when serializing.
int	getIndentation() Returns the indentation level of the serialized output.
java.io.OutputStream	getOutputStream() Retrieves the output stream to be used for serialization.
java.lang.String	getPublicId() Retrieves the PUBLIC identifier to be included in the serialized document's <!DOCTYPE> declaration.
java.lang.String	getSystemId() Retrieves the SYSTEM identifier to be included in the serialized document's <!DOCTYPE> declaration.
TopicMap	getTopicMap() Retrieves the TopicMap to be serialized.
boolean	getWriteStubs()
protected void	init() Initializes the instance and sets appropriate default values for properties.
boolean	isIncludingDoctype() Determines whether the serialized output will contain a <!DOCTYPE> declaration.
boolean	isSerialized() Returns whether the instance has successfully completed the serialization process.
void	serialize() Performs the serialization of the merged topic map.
void	setEncoding(java.lang.String newVal) Sets the character encoding to be used when serializing.
void	setIncludeDoctype(boolean newVal) Configures the instance to include a <!DOCTYPE> declaration in the serialized output.
void	setIndentation(int newVal) Configures the instance to indent (pretty-print) the serialized output.
void	setOutputFile(java.io.File file) Configures the instance to use the specified output file for serialization.
void	setOutputFile(java.lang.String path) Configures the instance to use the file denoted by the specified path for serialization.
void	setOutputStream(java.io.OutputStream newStream) Sets the output stream to which the merged result is serialized.
void	setPublicId(java.lang.String newVal) Sets the PUBLIC identifier to be included in the serialized document's <!DOCTYPE> declaration.
protected void	setSerialized(boolean newVal) Sets the state of serialization.
void	setSystemId(java.lang.String newVal) Sets the SYSTEM identifier to be included in the serialized document's <!DOCTYPE> declaration.
void	setTopicMap(TopicMap newTopicMap) Sets the TopicMap to be serialized.
void	setWriteStubs(boolean b) Sets whether or not the serialization will include topics that have only a single subject indicator or only a subject address and no other properties.

Methods inherited from class org.tm4j.topicmap.utils.HelperBase

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, debug, error, error, fatal, fatal, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getLogger, hasLogger, info, logVetoedChange, removeLogger, setLogger, trace, warn, warn

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ENCODING

protected static final java.lang.String DEFAULT_ENCODING

The default output encoding.

See Also:

Constant Field Values

DEFAULT_INCLUDE_DOCTYPE

protected static final boolean DEFAULT_INCLUDE_DOCTYPE

The default setting for including a document type declaration in the output.

See Also:

Constant Field Values

DEFAULT_INDENT

protected static final int DEFAULT_INDENT

The default setting for indenting the output.

See Also:

Constant Field Values

DEFAULT_OUTPUT_STREAM

protected static final java.io.OutputStream DEFAULT_OUTPUT_STREAM

The default serialization output stream.

XTM_PUBLIC_ID

public static final java.lang.String XTM_PUBLIC_ID

The XTM 1.0 system ID.

See Also:

Constant Field Values

XTM_SYSTEM_ID

public static final java.lang.String XTM_SYSTEM_ID

The XTM 1.0 system ID.

See Also:

Constant Field Values

Constructor Detail

TopicMapSerializer

public TopicMapSerializer()

Constructs a new instance. Merely invokes the superclass constructor.

TopicMapSerializer

public TopicMapSerializer(TopicMap topicMap)

Constructs a new instance, initializing it with an existing TopicMap. Using this constructor will cause property change vetoing on the "topicMap" property to be bypassed as the property is set before any change listeners can be registered.

Parameters:

topicMap - the topic map to be serialized.

TopicMapSerializer

public TopicMapSerializer(TopicMap topicMap,
                          java.io.File file)
                   throws java.io.IOException

Constructs a new instance, initializing it with an existing TopicMap and an output File to serialize to. Using this constructor will cause property change vetoing on the "topicMap" and "outputStream" properties to be bypassed as the properties are set before any change listeners can be registered.

Parameters:

topicMap - the topic map to be serialized.

file - the file to which the output shall be serialized.

Throws:

FileNotFoundException - if the output file can't be accessed. Kept for backwards compatiblity with JDK/JRE 1.2, on later Java versions, this constructor will only throw FileNotFoundException.

java.io.IOException

TopicMapSerializer

public TopicMapSerializer(TopicMap topicMap,
                          java.io.OutputStream stream)

Constructs a new instance, initializing it with an existing TopicMap and an OutputStream to serialize to. Using this constructor will cause property change vetoing on the "topicMap" and "outputStream" properties to be bypassed as the properties are set before any change listeners can be registered.

Parameters:

topicMap - the topic map to be serialized.

stream - the output stream to serialize to

TopicMapSerializer

public TopicMapSerializer(TopicMap topicMap,
                          java.lang.String path)
                   throws java.io.IOException

Constructs a new instance, initializing it with an existing TopicMap and the path to an output File to serialize to. Using this constructor will cause property change vetoing on the "topicMap" and "outputStream" properties to be bypassed as the properties are set before any change listeners can be registered.

Parameters:

topicMap - the topic map to be serialized.

path - the path of the file to which the output shall be serialized.

Throws:

java.io.IOException - if the output file denoted by the path can't be accessed. Kept for backwards compatibility with JDK/JRE 1.2, on later Java versions, this constructor will only throw FileNotFoundException.

Method Detail

closeOutputStream

public void closeOutputStream()
                       throws java.io.IOException

A convenience method that closes the output stream. This is equivalent to invoking getOutputStream().close().

Throws:

java.io.IOException - if the stream could not be closed properly.

getEncoding

public java.lang.String getEncoding()

Retrieves the character encoding to be used when serializing.

Returns:

the character encoding used during serialization.

getOutputStream

public java.io.OutputStream getOutputStream()

Retrieves the output stream to be used for serialization.

Returns:

the output stream to which the merged result is written during serialization.

getPublicId

public java.lang.String getPublicId()

Retrieves the PUBLIC identifier to be included in the serialized document's <!DOCTYPE> declaration.

Returns:

the public ID to be used while writing the output document.

getSystemId

public java.lang.String getSystemId()

Retrieves the SYSTEM identifier to be included in the serialized document's <!DOCTYPE> declaration.

Returns:

the system ID to be used while writing the output document.

getTopicMap

public TopicMap getTopicMap()

Retrieves the TopicMap to be serialized.

Returns:

the topic map to be serialized.

init

protected void init()
             throws java.lang.InstantiationException,
                    java.lang.IllegalAccessException,
                    TopicMapProviderException,
                    LocatorFactoryException

Initializes the instance and sets appropriate default values for properties.

Specified by:

init in class HelperBase

Throws:

java.lang.InstantiationException

java.lang.IllegalAccessException

TopicMapProviderException

LocatorFactoryException

isIncludingDoctype

public boolean isIncludingDoctype()

Determines whether the serialized output will contain a <!DOCTYPE> declaration.

Returns:

true if the serialized output is to contain a document type declaration, false otherwise.

getIndentation

public int getIndentation()

Returns the indentation level of the serialized output.

Returns:

the number of spaces used for indenting.

isSerialized

public boolean isSerialized()

Returns whether the instance has successfully completed the serialization process.

Returns:

true if the instance has been properly serialized, false otherwise.

serialize

public void serialize()
               throws TopicMapProcessingException,
                      java.io.IOException

Performs the serialization of the merged topic map. Note that this method only flushes the output stream when serialization is complete, rather than closing it, so it is up to the invoking application to close the stream. This class provides a convenience method for doing so, see closeOutputStream().

Throws:

TopicMapProcessingException - if an unexpected condition occurs while "walking" the topic map.

java.io.IOException - if writing to the output stream fails.

setEncoding

public void setEncoding(java.lang.String newVal)

Sets the character encoding to be used when serializing. Since changes to this property are vetoable, a registered VetoableChangeListener may determine that the property change is inappropriate or invalid, and ask for it to be rolled back. In that case, the property's original value is restored, and a warning is issued to any registered logger.

Parameters:

newVal - the character encoding used during serialization.

setIncludeDoctype

public void setIncludeDoctype(boolean newVal)

Configures the instance to include a <!DOCTYPE> declaration in the serialized output. Since changes to this property are vetoable, a registered VetoableChangeListener may determine that the property change is inappropriate or invalid, and ask for it to be rolled back. In that case, the property's original value is restored, and a warning is issued to any registered logger.

Returns:

true if the serialized output is to contain a document type declaration, false otherwise.

setIndentation

public void setIndentation(int newVal)

Configures the instance to indent (pretty-print) the serialized output. Since changes to this property are vetoable, a registered VetoableChangeListener may determine that the property change is inappropriate or invalid, and ask for it to be rolled back. In that case, the property's original value is restored, and a warning is issued to any registered logger.

Returns:

true if the serialized output is to be indented, false otherwise.

setOutputFile

public void setOutputFile(java.io.File file)
                   throws java.io.IOException

Configures the instance to use the specified output file for serialization. This is merely a convenience method that constructs a new FileOutputStream from file, and then invokes setOutputStream(OutputStream).

Parameters:

file - the output file to use for serialization.

Throws:

java.io.IOException - if the specified output file can't be accessed. Kept for backwards compatibility with JDK/JRE 1.2, on later Java versions, this method will only throw FileNotFoundException.

setOutputFile

public void setOutputFile(java.lang.String path)
                   throws java.io.IOException

Configures the instance to use the file denoted by the specified path for serialization. This is merely a convenience method that constructs a new File from path, and then invokes setOutputFile(File).

Parameters:

path - the (relative or absolute) path to the output file to use for serialization.

Throws:

java.io.IOException - if the specified output file can't be accessed. Kept for backwards compatibility with JDK/JRE 1.2, on later Java versions, this method will only throw FileNotFoundException.

setOutputStream

public void setOutputStream(java.io.OutputStream newStream)

Sets the output stream to which the merged result is serialized. Since changes to this property are vetoable, a registered VetoableChangeListener may determine that the property change is inappropriate or invalid, and ask for it to be rolled back. In that case, the property's original value is restored, and a warning is issued to any registered logger.

Parameters:

newStream - the output stream to be written to during serialization.

setPublicId

public void setPublicId(java.lang.String newVal)

Sets the PUBLIC identifier to be included in the serialized document's <!DOCTYPE> declaration.

Parameters:

newVal - the public ID to be used while writing the output document.

setSerialized

protected void setSerialized(boolean newVal)

Sets the state of serialization.

Parameters:

newVal - true if the instance has been properly serialized, false otherwise.

setSystemId

public void setSystemId(java.lang.String newVal)

Sets the SYSTEM identifier to be included in the serialized document's <!DOCTYPE> declaration.

Parameters:

newVal - the system ID to be used while writing the output document.

setTopicMap

public void setTopicMap(TopicMap newTopicMap)

Sets the TopicMap to be serialized. Since changes to this property are vetoable, a registered VetoableChangeListener may determine that the property change is inappropriate or invalid, and ask for it to be rolled back. In that case, the property's original value is restored, and a warning is issued to any registered logger.

Parameters:

newTopicMap - the new topic map to be serialized.

getWriteStubs

public boolean getWriteStubs()

Returns:

setWriteStubs

public void setWriteStubs(boolean b)

Sets whether or not the serialization will include topics that have only a single subject indicator or only a subject address and no other properties. If this value is false, then such topics are omitted and references to the subject are made using a subjectIndicatorRef or resourceRef element.

Parameters:

b - true to write the topics, false to skip them