org.openimaj.io

Class IOUtils

java.lang.Object

org.openimaj.io.IOUtils

public class IOUtils
extends Object

Methods for reading Readable objects and writing Writeable objects.

Author:

Jonathon Hare (jsh2@ecs.soton.ac.uk), Sina Samangooei (ss@ecs.soton.ac.uk)

Constructor Summary

Constructors

Constructor and Description
IOUtils()

Method Summary

Modifier and Type	Method and Description
static boolean	canRead(InputStreamObjectReader<?> reader, BufferedInputStream is, String name) Test whether the data in the given InputStream can be read by the given InputStreamObjectReader.
static <SRC> boolean	canRead(ObjectReader<?,SRC> reader, SRC source, String name) Test whether the data in the given source can be read by the given ObjectReader.
static <T extends ReadableBinary> T	deserialize(byte[] source, Class<T> clazz) Convenience function for deserializing an object from a byte array.
static <T extends ReadableBinary> T	deserialize(byte[] source, long skip, Class<T> clazz) Convenience function for deserializing an object from a byte array.
static <T extends org.openimaj.io.InternalReadable> T	deserialize(byte[] source, T instance) Convenience function for deserializing an object from a byte array.
static <T extends ReadableASCII> T	fromString(String source, Class<T> clazz) Convenience function for deserializing an object from a String.
static boolean	isBinary(BufferedInputStream bis, byte[] header) Checks whether a given input stream contains readable binary information by checking for the first header.length bytes == header.
static <T extends ReadableBinary> boolean	isBinary(BufferedInputStream bis, T obj) Extracts the binary header from object and calls the byte[] version
static boolean	isBinary(File f, byte[] header) Opens an input stream and calls input stream version
static <T extends org.openimaj.io.InternalReadable> T	newInstance(Class<T> cls) Create a new instance of the given class.
static <T extends org.openimaj.io.InternalReadable> T	newInstance(String className) Create a new instance of the given class.
static <T> T	read(DataInput in) Utility method to read any object written with write(Object, DataOutput).
static <T extends org.openimaj.io.InternalReadable> T	read(File f) Read an object from a file.
static <T extends org.openimaj.io.InternalReadable> T	read(File f, Class<T> cls) Read a new instance of type class from a file.
static <T extends org.openimaj.io.InternalReadable> T	read(File f, Class<T> cls, String charset) Read a new instance of type class from a file.
static <T extends org.openimaj.io.InternalReadable> T	read(File f, String charset) Read an object from a file.
static <T extends org.openimaj.io.InternalReadable> T	read(File f, T obj) Open file input stream and call Readable#read(InputStream,T)
static <T extends org.openimaj.io.InternalReadable> T	read(File f, T obj, String charset) Open file input stream and call Readable#read(InputStream,T)
static <T extends org.openimaj.io.InternalReadable> T	read(InputStream ios, Class<T> cls) Read a new instance of type class from an input stream.
static <T extends org.openimaj.io.InternalReadable> T	read(InputStream ios, Class<T> cls, String charset) Read a new instance of type class from an input stream.
static <T extends org.openimaj.io.InternalReadable> T	read(InputStream fis, T obj) Read an instance of an object from an input stream.
static <T extends org.openimaj.io.InternalReadable> T	read(InputStream fis, T obj, String charset) Read an instance of an object from an input stream.
static <T extends org.openimaj.io.InternalReadable> T	read(Reader fis, Class<T> cls) Read an instance of an object from a reader.
static <T extends org.openimaj.io.InternalReadable> T	read(Reader fis, T obj) Read an instance of an object from a reader.
static boolean	readable(BufferedInputStream bis, byte[] header) Check whether a stream starts with a header.
static <T extends org.openimaj.io.InternalReadable> boolean	readable(BufferedInputStream bis, Class<T> cls) Check whether an InputStream can be read by an instantiated class based on it's binary and ascii headers.
static boolean	readable(BufferedInputStream bis, String header) Check whether an input stream starts with a header string.
static boolean	readable(File f, byte[] header) Check readability by checking whether a file starts with a given header.
static <T extends org.openimaj.io.InternalReadable> boolean	readable(File f, Class<T> cls) Check whether a given file is readable by a given Writeable class.
static boolean	readable(File f, String header) Check whether a file is readable by checking it's first bytes contains the header.
static <T> T	readFromFile(File in) Utility method to read any object written with writeToFile(Object, File).
static byte[]	serialize(WriteableBinary object) Convenience function for serializing a writeable object as a byte array.
static void	write(Object obj, DataOutput out) Writes an object using the Kryo serialisation library.
static <T extends WriteableASCII> void	writeASCII(File f, T obj) Writeable object is written to the a file in ASCII format.
static <T extends WriteableASCII> void	writeASCII(File f, T obj, String charset) Writeable object is written to the a file in ASCII format.
static <T extends WriteableASCII> void	writeASCII(OutputStream fos, T obj) Write the object in ASCII format to the output stream.
static <T extends WriteableASCII> void	writeASCII(OutputStream fos, T obj, String charset) Write the object in ASCII format to the output stream.
static <T extends WriteableASCII> void	writeASCII(Writer writer, T obj) Write the object in ASCII format to the output stream.
static <T extends WriteableASCII> void	writeASCIIFull(File f, T object) Write an object to a file fully.
static <T extends WriteableASCII> void	writeASCIIFull(File f, T object, String charset) Write an object to a file fully.
static <T extends WriteableBinary> void	writeBinary(BufferedOutputStream bos, T obj) Writeable object is written to the output stream in binary format.
static <T extends WriteableBinary> void	writeBinary(File f, T obj) Write a Writeable T object instance.
static <T extends WriteableBinary> void	writeBinary(OutputStream fos, T obj) Write a Writeable T object instance to the provided output stream, calls BufferedOutputStream version
static <T extends WriteableBinary> void	writeBinaryFull(File f, T object) Write an object to a file fully.
static void	writeToFile(Object obj, File out) Writes an object to a file using the Kryo serialisation library.

Methods inherited from class java.lang.Object

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

Constructor Detail

IOUtils

public IOUtils()

Method Detail

newInstance

public static <T extends org.openimaj.io.InternalReadable> T newInstance(Class<T> cls)

Create a new instance of the given class. The class must have a no-args constructor. The constructor doesn't have to be public.

Type Parameters:

T - The type of object.

Parameters:

cls - The class.

Returns:

a new instance.

newInstance

public static <T extends org.openimaj.io.InternalReadable> T newInstance(String className)

Create a new instance of the given class. The class must have a no-args constructor. The constructor doesn't have to be public.

Type Parameters:

T - The type of object.

Parameters:

className - The class name.

Returns:

a new instance.

read

public static <T extends org.openimaj.io.InternalReadable> T read(File f)
                                                           throws IOException

Read an object from a file.

Type Parameters:

T - instance type expected

Parameters:

f - the file

Returns:

object read from file

Throws:

IOException - problem reading file

read

public static <T extends org.openimaj.io.InternalReadable> T read(File f,
                                                                  String charset)
                                                           throws IOException

Read an object from a file.

Type Parameters:

T - instance type expected

Parameters:

f - the file

charset - the charsetName sent to the reader which reads the file IFF the file is not binary

Returns:

object read from file

Throws:

IOException - problem reading file

writeBinaryFull

public static <T extends WriteableBinary> void writeBinaryFull(File f,
                                                               T object)
                                                        throws IOException

Write an object to a file fully. The object will be saved with class information so that it can be automatically re-instantiated using read(File) without needing to know the actual type.

Type Parameters:

T - instance type expected

Parameters:

f - the file

object - the object to write

Throws:

IOException - problem reading file

writeASCIIFull

public static <T extends WriteableASCII> void writeASCIIFull(File f,
                                                             T object)
                                                      throws IOException

Write an object to a file fully. The object will be saved with class information so that it can be automatically re-instantiated using read(File) without needing to know the actual type.

Type Parameters:

T - instance type expected

Parameters:

f - the file

object - the object to write

Throws:

IOException - problem reading file

writeASCIIFull

public static <T extends WriteableASCII> void writeASCIIFull(File f,
                                                             T object,
                                                             String charset)
                                                      throws IOException

Write an object to a file fully. The object will be saved with class information so that it can be automatically re-instantiated using read(File) without needing to know the actual type.

Type Parameters:

T - instance type expected

Parameters:

f - the file

object - the object to write

charset - the charsetName sent to the internal writer

Throws:

IOException - problem reading file

read

public static <T extends org.openimaj.io.InternalReadable> T read(File f,
                                                                  Class<T> cls)
                                                           throws IOException

Read a new instance of type class from a file.

Type Parameters:

T - instance type expected

Parameters:

f - the file

cls - the class

Returns:

new instance of class instantiated from the file

Throws:

IOException - problem reading file

read

public static <T extends org.openimaj.io.InternalReadable> T read(File f,
                                                                  Class<T> cls,
                                                                  String charset)
                                                           throws IOException

Read a new instance of type class from a file.

Type Parameters:

T - instance type expected

Parameters:

f - the file

cls - the class

charset - the charsetName sent to the reader which reads the file IFF the file is not binary

Returns:

new instance of class instantiated from the file

Throws:

IOException - problem reading file

read

public static <T extends org.openimaj.io.InternalReadable> T read(InputStream ios,
                                                                  Class<T> cls)
                                                           throws IOException

Read a new instance of type class from an input stream.

Type Parameters:

T - instance type expected

Parameters:

ios - the input stream

cls - the class

Returns:

new instance of class instantiated from the stream

Throws:

IOException - problem reading stream

read

public static <T extends org.openimaj.io.InternalReadable> T read(InputStream ios,
                                                                  Class<T> cls,
                                                                  String charset)
                                                           throws IOException

Read a new instance of type class from an input stream.

Type Parameters:

T - instance type expected

Parameters:

ios - the input stream

cls - the class

charset - the charsetName sent to the internal inputstreamreader

Returns:

new instance of class instantiated from the stream

Throws:

IOException - problem reading stream

read

public static <T extends org.openimaj.io.InternalReadable> T read(File f,
                                                                  T obj)
                                                           throws IOException

Open file input stream and call Readable#read(InputStream,T)

Type Parameters:

T - instance type expected

Parameters:

f - the file

obj - the object of type T

Returns:

A new instance of type T

Throws:

IOException - an error reading the file

read

public static <T extends org.openimaj.io.InternalReadable> T read(File f,
                                                                  T obj,
                                                                  String charset)
                                                           throws IOException

Open file input stream and call Readable#read(InputStream,T)

Type Parameters:

T - instance type expected

Parameters:

f - the file

obj - the object of type T

charset - the charsetName sent to the reader which reads the file IFF the file is not binary

Returns:

A new instance of type T

Throws:

IOException - an error reading the file

read

public static <T extends org.openimaj.io.InternalReadable> T read(InputStream fis,
                                                                  T obj)
                                                           throws IOException

Read an instance of an object from an input stream. The stream is tested to contain the ASCII or binary header and the appropriate read instance is called.

Type Parameters:

T - instance type expected

Parameters:

fis - the input stream

obj - the object to instantiate

Returns:

the object

Throws:

IOException - if there is a problem reading the stream from the file

See Also:

ReadableBinary.binaryHeader(), ReadableBinary.readBinary(java.io.DataInput), ReadableASCII.readASCII(java.util.Scanner)

read

public static <T extends org.openimaj.io.InternalReadable> T read(InputStream fis,
                                                                  T obj,
                                                                  String charset)
                                                           throws IOException

Read an instance of an object from an input stream. The stream is tested to contain the ASCII or binary header and the appropriate read instance is called.

Type Parameters:

T - instance type expected

Parameters:

fis - the input stream

obj - the object to instantiate

charset - the charsetName sent the to the inputstreamreader

Returns:

the object

Throws:

IOException - if there is a problem reading the stream from the file

See Also:

ReadableBinary.binaryHeader(), ReadableBinary.readBinary(java.io.DataInput), ReadableASCII.readASCII(java.util.Scanner)

read

public static <T extends org.openimaj.io.InternalReadable> T read(Reader fis,
                                                                  T obj)
                                                           throws IOException

Read an instance of an object from a reader. The stream is assumed to be ascii and the appropriate read instance is called.

Type Parameters:

T - instance type expected

Parameters:

fis - the input stream

obj - the object to instantiate

Returns:

the object

Throws:

IOException - if there is a problem reading the stream from the file

See Also:

ReadableASCII.readASCII(java.util.Scanner)

read

public static <T extends org.openimaj.io.InternalReadable> T read(Reader fis,
                                                                  Class<T> cls)
                                                           throws IOException

Read an instance of an object from a reader. The stream is assumed to be ascii and the appropriate read instance is called.

Type Parameters:

T - instance type expected

Parameters:

fis - the input stream

cls - the object to instantiate

Returns:

the object

Throws:

IOException - if there is a problem reading the stream from the file

See Also:

ReadableASCII.readASCII(java.util.Scanner)

isBinary

public static boolean isBinary(File f,
                               byte[] header)
                        throws IOException

Opens an input stream and calls input stream version

Parameters:

f - file containing data

header - expected header in binary format

Returns:

is the file in the binary format

Throws:

IOException - if there was a problem reading the input stream

See Also:

isBinary(BufferedInputStream,byte[])

isBinary

public static <T extends ReadableBinary> boolean isBinary(BufferedInputStream bis,
                                                          T obj)
                                                   throws IOException

Extracts the binary header from object and calls the byte[] version

Type Parameters:

T - expected data type

Parameters:

bis - stream containing data

obj - instance of expected data type

Returns:

does the stream contain binary information

Throws:

IOException - problem reading input stream

See Also:

isBinary(BufferedInputStream,byte[])

isBinary

public static boolean isBinary(BufferedInputStream bis,
                               byte[] header)
                        throws IOException

Checks whether a given input stream contains readable binary information by checking for the first header.length bytes == header. The stream is reset to the beginning of the header once checked.

Parameters:

bis - stream containing data

header - expected binary header

Returns:

does the stream contain binary information

Throws:

IOException - problem reading or reseting the stream

writeBinary

public static <T extends WriteableBinary> void writeBinary(File f,
                                                           T obj)
                                                    throws IOException

Write a Writeable T object instance. Opens a file stream and calls output stream version

Type Parameters:

T - data type to be written

Parameters:

f - file to write instance to

obj - instance to be written

Throws:

IOException - error reading file

See Also:

IOUtils#writeBinary(OutputStream,Writeable)

writeBinary

public static <T extends WriteableBinary> void writeBinary(OutputStream fos,
                                                           T obj)
                                                    throws IOException

Write a Writeable T object instance to the provided output stream, calls BufferedOutputStream version

Type Parameters:

T - Expected data type

Parameters:

fos - output stream

obj - the object to write

Throws:

IOException - error writing to stream

See Also:

IOUtils#writeBinary(BufferedOutputStream,Writeable)

writeBinary

public static <T extends WriteableBinary> void writeBinary(BufferedOutputStream bos,
                                                           T obj)
                                                    throws IOException

Writeable object is written to the output stream in binary format. Firstly the binaryHeader is written then the object is handed the output stream to write it's content.

Type Parameters:

T - instance type expected

Parameters:

bos - the output stream

obj - the object to write

Throws:

IOException - error writing to stream

See Also:

WriteableBinary.writeBinary(java.io.DataOutput), WriteableBinary.binaryHeader()

writeASCII

public static <T extends WriteableASCII> void writeASCII(File f,
                                                         T obj)
                                                  throws IOException

Writeable object is written to the a file in ASCII format. File stream is opened and stream version is called

Type Parameters:

T - instance type expected

Parameters:

f - the file to write to

obj - the object to write

Throws:

IOException - error writing to file

See Also:

IOUtils#writeASCII(OutputStream, Writeable)

writeASCII

public static <T extends WriteableASCII> void writeASCII(File f,
                                                         T obj,
                                                         String charset)
                                                  throws IOException

Writeable object is written to the a file in ASCII format. File stream is opened and stream version is called

Type Parameters:

T - instance type expected

Parameters:

f - the file to write to

obj - the object to write

charset - the charsetName sent to the internal writer

Throws:

IOException - error writing to file

See Also:

IOUtils#writeASCII(OutputStream, Writeable)

writeASCII

public static <T extends WriteableASCII> void writeASCII(OutputStream fos,
                                                         T obj)
                                                  throws IOException

Write the object in ASCII format to the output stream. Construct a PrintWriter using the outputstream, write the object's ASCII header then write the object in ASCII format.

Type Parameters:

T - instance type expected

Parameters:

fos - the output stream

obj - the object

Throws:

IOException - error writing to stream

See Also:

PrintWriter, WriteableASCII.asciiHeader(), WriteableASCII.writeASCII(PrintWriter)

writeASCII

public static <T extends WriteableASCII> void writeASCII(OutputStream fos,
                                                         T obj,
                                                         String charset)
                                                  throws IOException

Write the object in ASCII format to the output stream. Construct a PrintWriter using the outputstream, write the object's ASCII header then write the object in ASCII format.

Type Parameters:

T - instance type expected

Parameters:

fos - the output stream

obj - the object

charset - the charsetName sent to the internal outputstreamwriter

Throws:

IOException - error writing to stream

See Also:

PrintWriter, WriteableASCII.asciiHeader(), WriteableASCII.writeASCII(PrintWriter)

writeASCII

public static <T extends WriteableASCII> void writeASCII(Writer writer,
                                                         T obj)
                                                  throws IOException

Write the object in ASCII format to the output stream. Construct a PrintWriter using the outputstream, write the object's ASCII header then write the object in ASCII format.

Type Parameters:

T - instance type expected

Parameters:

writer - the output stream

obj - the object

Throws:

IOException - error writing to stream

See Also:

PrintWriter, WriteableASCII.asciiHeader(), WriteableASCII.writeASCII(PrintWriter)

readable

public static <T extends org.openimaj.io.InternalReadable> boolean readable(File f,
                                                                            Class<T> cls)
                                                                     throws IOException

Check whether a given file is readable by a given Writeable class. Instantiates the class to get it's binary and ascii header which is then passed to the byte[] version of this method

Type Parameters:

T - instance type expected

Parameters:

f - the file to check

cls - the class to instantiate the Readable object

Returns:

is file readable by a given class

Throws:

IOException - error reading file

See Also:

ReadableASCII.asciiHeader()

readable

public static boolean readable(File f,
                               String header)
                        throws IOException

Check whether a file is readable by checking it's first bytes contains the header. Converts the header to a byte[] and calls the byte[] version of this method

Parameters:

f - the file to check

header - the header to check with

Returns:

does this file contain this header

Throws:

IOException - error reading file

See Also:

readable(File, byte[])

readable

public static boolean readable(File f,
                               byte[] header)
                        throws IOException

Check readability by checking whether a file starts with a given header. Instantiate an input stream and check whether the stream isBinary (i.e. starts with the header)

Parameters:

f - file to check

header - the expected header

Returns:

does the file start with the header

Throws:

IOException - error reading file

See Also:

isBinary(BufferedInputStream, byte[])

readable

public static <T extends org.openimaj.io.InternalReadable> boolean readable(BufferedInputStream bis,
                                                                            Class<T> cls)
                                                                     throws IOException

Check whether an InputStream can be read by an instantiated class based on it's binary and ascii headers. Buffered so the stream can be reset after the check.

Type Parameters:

T - instance type expected

Parameters:

bis - the stream

cls - the class to instantiate and check

Returns:

can an object be read from this stream of the class type

Throws:

IOException - error reading stream

readable

public static boolean readable(BufferedInputStream bis,
                               String header)
                        throws IOException

Check whether an input stream starts with a header string. Calls the byte[] version of this function

Parameters:

bis - the input stream

header - the header

Returns:

whether the stream starts with the string

Throws:

IOException - error reading stream

See Also:

isBinary(BufferedInputStream, byte[])

readable

public static boolean readable(BufferedInputStream bis,
                               byte[] header)
                        throws IOException

Check whether a stream starts with a header. Uses isBinary (therefore resetting the stream after the check)

Parameters:

bis - the input stream

header - the byte[] header

Returns:

whether the stream starts with the header

Throws:

IOException - error reading stream

serialize

public static byte[] serialize(WriteableBinary object)
                        throws IOException

Convenience function for serializing a writeable object as a byte array. Calls writeBinary(OutputStream, WriteableBinary) on a ByteArrayOutputStream then calls ByteArrayOutputStream.toByteArray()

Parameters:

object -

Returns:

serialised object

Throws:

IOException

fromString

public static <T extends ReadableASCII> T fromString(String source,
                                                     Class<T> clazz)
                                              throws IOException

Convenience function for deserializing an object from a String. Calls ReadableASCII.readASCII(Scanner) with a Scanner initialized from a StringReader

Type Parameters:

T - the type to output

Parameters:

source - where to read from

clazz - the class of the output

Returns:

a new instance of T

Throws:

IOException

deserialize

public static <T extends ReadableBinary> T deserialize(byte[] source,
                                                       Class<T> clazz)
                                                throws IOException

Convenience function for deserializing an object from a byte array. Calls read(InputStream, Class) on a ByteArrayInputStream.

Type Parameters:

T - the type to output

Parameters:

source - where to read from

clazz - the class of the output

Returns:

a new instance of T

Throws:

IOException

deserialize

public static <T extends ReadableBinary> T deserialize(byte[] source,
                                                       long skip,
                                                       Class<T> clazz)
                                                throws IOException

Convenience function for deserializing an object from a byte array. Calls read(InputStream, Class) on a ByteArrayInputStream.

Type Parameters:

T - the type to output

Parameters:

source - where to read from

clazz - the class of the output

skip - number of bytes to skip

Returns:

a new instance of T

Throws:

IOException

deserialize

public static <T extends org.openimaj.io.InternalReadable> T deserialize(byte[] source,
                                                                         T instance)
                                                                  throws IOException

Convenience function for deserializing an object from a byte array. Calls read(InputStream, Class) on a ByteArrayInputStream.

Type Parameters:

T - the type to output

Parameters:

source - where to read from

instance - a T instance

Returns:

a new instance of T

Throws:

IOException

writeToFile

public static void writeToFile(Object obj,
                               File out)
                        throws IOException

Writes an object to a file using the Kryo serialisation library. The object doesn't need to have any special serialisation attributes.

Parameters:

obj - the object to write

out - the output sink

Throws:

IOException

write

public static void write(Object obj,
                         DataOutput out)
                  throws IOException

Writes an object using the Kryo serialisation library. The object doesn't need to have any special serialisation attributes.

Parameters:

obj - the object to write

out - the output sink

Throws:

IOException

read

public static <T> T read(DataInput in)
                  throws IOException

Utility method to read any object written with write(Object, DataOutput).

Type Parameters:

T - type of object

Parameters:

in - input

Returns:

the object

Throws:

IOException

readFromFile

public static <T> T readFromFile(File in)
                          throws IOException

Utility method to read any object written with writeToFile(Object, File).

Type Parameters:

T - type of object

Parameters:

in - input file

Returns:

the object

Throws:

IOException

canRead

public static boolean canRead(InputStreamObjectReader<?> reader,
                              BufferedInputStream is,
                              String name)
                       throws IOException

Test whether the data in the given InputStream can be read by the given InputStreamObjectReader. This method tries to ensure that the stream is reset to its initial condition.

Parameters:

reader - the InputStreamObjectReader.

is - the stream

name - the name of the file/object behind the stream (can be null)

Returns:

true if the InputStreamObjectReader can read from this stream; false otherwise.

Throws:

IOException - if an error occurs resetting the stream.

canRead

public static <SRC> boolean canRead(ObjectReader<?,SRC> reader,
                                    SRC source,
                                    String name)
                             throws IOException

Test whether the data in the given source can be read by the given ObjectReader.

Parameters:

reader - the ObjectReader.

source - the source

name - the name of the file/object behind the stream (can be null)

Returns:

true if the ObjectReader can read from this stream; false otherwise.

Throws:

IOException - if an error occurs resetting the stream.