com.aliasi.util

Class AbstractExternalizable

java.lang.Object

com.aliasi.util.AbstractExternalizable

All Implemented Interfaces:

Externalizable, Serializable

public abstract class AbstractExternalizable
extends Object
implements Externalizable

The AbstractExternalizer is an adapter for read resolved externalizables. This provides a general mechanism to write objects to an object output and read them back in. Instances of this class may be written and read from object streams in the usual way (see Serializable, Externalizable, ObjectInput and ObjectOutput for details.

Concrete subclasses of this class will define a writeExternal(ObjectOutput) method which writes an object, a read(ObjectInput) method which returns an object. Subclasses must also implement a public nullary constructor. None of the methods in this class should be called directly. The Java interface specification requires the reads and writes to be public and the resolver to be accessible to the subclass.

When an instance of this class is written to an object output by serialization, the method writeExternal(ObjectOutput) is called. When an instance is read back in by deserialization, first an instance is created using the nullary constructor. Then readExternal(ObjectInput) is called, which is implemented by this class to call read(ObjectInput) and store the result in a member variable. Finally, serialization calls readResolve() to get the object read.

This class is employed throughout LingPipe to carry out compilation of classes for two reasons. First, it allows the compiled objects to have final variables set, which supports LingPipe's extensive use of immutables. Second, it avaoids the messiness of exposing the I/O methods required for externalization and deserialization, most notably the no-argument constructor. This class is used as the superclass of a private private internal class that does the actual compilation. This private internal class implements the required no-arg constructor and stores the object required for readResolve().

Since:

LingPipe2.0

Version:

3.9.1

Author:

Bob Carpenter

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractExternalizable() Construct an abstract externalizable.

Method Summary

Methods

Modifier and Type	Method and Description
static Object	compile(Compilable c) Return the compiled form of the specified compilable.
static void	compileOrSerialize(Object obj, ObjectOutput out) Compile the object to the output if it is compilable, else serialize it to the output if it is serializable but not compilable.
static void	compileTo(Compilable compilable, File file) Compiles the specified compilable object to the specified file.
protected abstract Object	read(ObjectInput in) Read an object from the specified input stream and return it.
static double[]	readDoubles(ObjectInput objIn) Return the array of doubles read from the specified object input.
void	readExternal(ObjectInput objIn) Read an object from the specified input using and store it for later resolution.
static float[]	readFloats(ObjectInput objIn) Return the array of floats read from the specified object input.
static int[]	readInts(ObjectInput objIn) Return the array of integers read from the specified object input.
static Object	readObject(File file) Returns the result of reading a serialized object stored in the specified file.
protected Object	readResolve() Returns the object read.
static Object	readResourceObject(Class<?> clazz, String resourcePathName) Return the object read from an object input stream created from the specified resource relative to the specified class.
static Object	readResourceObject(String resourceAbsolutePathName) Returns the object read from an object input stream created from the specified absolute path name for a resource.
static String[]	readUTFs(ObjectInput objIn) Return the array of strings read from the specified object input.
static Object	serializeDeserialize(Serializable s) Returns the result of serializing the specified object and then reading the result as an object.
static void	serializeOrCompile(Object obj, ObjectOutput out) Serialize the object to the output if it is serializable, else compile it to the output if it is compilable but not serializable.
static void	serializeTo(Serializable serializable, File file) Serializes the specified serializable object to the specified file.
static void	writeDoubles(double[] xs, ObjectOutput objOut) Write a double array to the specified object output.
abstract void	writeExternal(ObjectOutput out) Writes an object to the specified object output.
static void	writeFloats(float[] xs, ObjectOutput objOut) Write a float array to the specified object output.
static void	writeInts(int[] xs, ObjectOutput objOut) Write an integer array to the specified object output.
static void	writeUTFs(String[] xs, ObjectOutput objOut) Write a string array to the specified object output.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractExternalizable

protected AbstractExternalizable()

Construct an abstract externalizable. Concrete subclasses must provide a no-argument constructor or the compiled object will throw a InvalidClassException when it attempts to invoke the no-argument constructor through reflection.

Like the other methods, this method should not be called directly. See the class documentation above for details.

Method Detail

read

protected abstract Object read(ObjectInput in)
                        throws ClassNotFoundException,
                               IOException

Read an object from the specified input stream and return it. Concrete subclasses implement this method in order to define deserialization behavior -- the object returned is the one produced by this object.

Like the other methods, this method should not be called directly. See the class documentation above for details.

Parameters:

in - Object input from which to read an object.

Throws:

IOException - If there is an I/O exception reading.

ClassNotFoundException - If a class required for deserialization is not loadable.

writeExternal

public abstract void writeExternal(ObjectOutput out)
                            throws IOException

Writes an object to the specified object output. Writes should match reads in that the output produced by this method should be readable using read(ObjectInput).

Like the other methods, this method should not be called directly. See the class documentation above for details.

Specified by:

writeExternal in interface Externalizable

Parameters:

out - Object output to which an object is written.

Throws:

IOException - If there is an I/O exception writing.

readExternal

public final void readExternal(ObjectInput objIn)
                        throws ClassNotFoundException,
                               IOException

Read an object from the specified input using and store it for later resolution.

Like the other methods, this method should not be called directly. See the class documentation above for details.

Specified by:

readExternal in interface Externalizable

Parameters:

objIn - Object input from which to read an object.

Throws:

IOException - If there is an I/O exception reading.

ClassNotFoundException

readResolve

protected Object readResolve()

Returns the object read.

Like the other methods, this method should not be called directly. See the class documentation above for details.

Returns:

The last object read.

compileTo

public static void compileTo(Compilable compilable,
             File file)
                      throws IOException

Compiles the specified compilable object to the specified file.

Parameters:

compilable - Object to compile.

file - File to which object is written.

Throws:

IOException - If there is an underlying I/O error.

serializeTo

public static void serializeTo(Serializable serializable,
               File file)
                        throws IOException

Serializes the specified serializable object to the specified file.

Parameters:

serializable - Object to serialize.

file - File to which the object is serialized.

Throws:

IOException - If there is an underlying I/O error duruing serialization.

serializeOrCompile

public static void serializeOrCompile(Object obj,
                      ObjectOutput out)
                               throws IOException

Serialize the object to the output if it is serializable, else compile it to the output if it is compilable but not serializable.

Parameters:

obj - Object to serialize or compile.

out - Output stream to which to write the object.

Throws:

IllegalArgumentException - If the specified object is neither serializable nor compilable.

IOException

compileOrSerialize

public static void compileOrSerialize(Object obj,
                      ObjectOutput out)
                               throws IOException

Compile the object to the output if it is compilable, else serialize it to the output if it is serializable but not compilable.

Parameters:

obj - Object to compile or serializable.

out - Output stream to which to write the object.

Throws:

NotSerializableException - If the specified object is neither serializable nor compilable.

IOException - if there is an underlying I/O error.

readObject

public static Object readObject(File file)
                         throws IOException,
                                ClassNotFoundException

Returns the result of reading a serialized object stored in the specified file.

Implementation Note: This is just a convenience method that creates a file input stream, buffers it, wraps it in an object input stream and reads an object from the input. It always makes sure to close all of the stream, even if exceptions are raised.

Parameters:

file - File from which to read the object.

Returns:

The object read from the file.

Throws:

IOException - If there is an underlying I/O error while reading.

ClassNotFoundException - If the classloader could not load the class for the serialized object.

readResourceObject

public static Object readResourceObject(Class<?> clazz,
                        String resourcePathName)
                                 throws IOException,
                                        ClassNotFoundException

Return the object read from an object input stream created from the specified resource relative to the specified class. The stream will be closed whether this method exits normally or throws an exception.

See Class.getResourceAsStream(String) for more information on loading resources. Notably, if the name starts with a forward slash ('/'), it will be taken as an absolute path from which to search. If the name does not start with a forward slash, the name of the package for the class passed in will be used.

Parameters:

resourcePathName - Relative or absolute path to resource.

clazz - Class from which to relativize search.

Returns:

Object read from resource.

Throws:

IOException - If the resource cannot be found or if there is an I/O error reading from the resource.

ClassNotFoundException - If a class required for deserializing the object cannot be found.

readResourceObject

public static Object readResourceObject(String resourceAbsolutePathName)
                                 throws IOException,
                                        ClassNotFoundException

Returns the object read from an object input stream created from the specified absolute path name for a resource. Absolute path names must start with a forward slash ('/'), and will be interpreted absolutely with respect to the classpath.

This method delegates to readResourceObject(Class,String) after verifying the path name is absolute. See that class for more information.

Parameters:

resourceAbsolutePathName - Path to resource to read.

Returns:

Object read from resource.

Throws:

IOException - If the resource cannot be found or if there is an I/O error reading from the resource.

ClassNotFoundException - If a class required for deserializing the object cannot be found.

IllegalArgumentException - If the resource name does not start with a forward slash.

compile

public static Object compile(Compilable c)
                      throws ClassNotFoundException,
                             IOException

Return the compiled form of the specified compilable.

See serializeDeserialize(Serializable) for a similar method that operates through the Serializable interface rather than the compilable interface.

Implementation Note: The model is written to a byte array using compileTo and then read back in using ObjectInput's readObject method. This means that both the object being compiled and the result will typically be held in memory at one time. After compiling to a file, the object being compiled may be garbage collected before the compiled object is read in from the file.

Parameters:

c - Object to compile.

Returns:

Compiled form of object.

Throws:

ClassNotFoundException - If the class of the compiled object cannot be found.

IOException - If there is an I/O exception compiling or deserializing the compilable, or if there is a class not found exception thrown while deserializing.

serializeDeserialize

public static Object serializeDeserialize(Serializable s)
                                   throws IOException

Returns the result of serializing the specified object and then reading the result as an object.

See compile(Compilable) for a similar method that operates through the compilable interface rather than the serializable interface.

Implementation Note: See the note for compile(Compilable).

Parameters:

s - A serializable object.

Returns:

The result of serializing and deserializing the object.

Throws:

IOException - If there is an I/O exception serializing or deserializing the object, or if there is a class not found exception thrown while deserializing.

writeInts

public static void writeInts(int[] xs,
             ObjectOutput objOut)
                      throws IOException

Write an integer array to the specified object output. First the length is written as an integer, then each element is written in turn as an integer.

Parameters:

xs - Integers to write.

objOut - Output stream to which integers are written.

Throws:

IOException - If there is an underlying I/O error.

readInts

public static int[] readInts(ObjectInput objIn)
                      throws IOException

Return the array of integers read from the specified object input.

See writeInts(int[],ObjectOutput) for format.

Parameters:

objIn - Input stream from which to read.

Returns:

Integers read from stream.

Throws:

IOException - If there is an underlying I/O error.

writeFloats

public static void writeFloats(float[] xs,
               ObjectOutput objOut)
                        throws IOException

Write a float array to the specified object output. First the length is written as an integer, then each element is written in turn as a float.

Parameters:

xs - Floats to write.

objOut - Output stream to which floats are written.

Throws:

IOException - If there is an underlying I/O error.

writeDoubles

public static void writeDoubles(double[] xs,
                ObjectOutput objOut)
                         throws IOException

Write a double array to the specified object output. First the length is written as an integer, then each element is written in turn as a double;

Parameters:

xs - Doubles to write.

objOut - Output stream to which doubles are written.

Throws:

IOException - If there is an underlying I/O error.

readFloats

public static float[] readFloats(ObjectInput objIn)
                          throws IOException

Return the array of floats read from the specified object input.

See writeFloats(float[],ObjectOutput) for format.

Parameters:

objIn - Input stream from which to read.

Returns:

Floats read from stream.

Throws:

IOException - If there is an underlying I/O error.

readDoubles

public static double[] readDoubles(ObjectInput objIn)
                            throws IOException

Return the array of doubles read from the specified object input.

See writeDoubles(double[],ObjectOutput) for format.

Parameters:

objIn - Input stream from which to read.

Returns:

Doubles read from stream.

Throws:

IOException - If there is an underlying I/O error.

writeUTFs

public static void writeUTFs(String[] xs,
             ObjectOutput objOut)
                      throws IOException

Write a string array to the specified object output. First the length is written as an integer, then each element is written in turn using DataOutput.writeUTF(String).

Parameters:

xs - Strings to write.

objOut - Output stream to which strings are written.

Throws:

IOException - If there is an underlying I/O error.

readUTFs

public static String[] readUTFs(ObjectInput objIn)
                         throws IOException

Return the array of strings read from the specified object input.

See writeUTFs(String[],ObjectOutput) for format.

Parameters:

objIn - Input stream from which to read.

Returns:

Strings read from stream.

Throws:

IOException - If there is an underlying I/O error.