ewe.io
Class IO

java.lang.Object
  ewe.io.IO

public class IO

extends Object

Field Summary

static String	ASCII_CODEC The canonical name for the Ewe library's Ascii Codec.
static String	JAVA_UTF8_CODEC The canonical name for the Ewe library's Ascii Codec.
static int	SAVE_IN_FILE Option for saveConfigInfo().
static int	SAVE_IN_FILE_OR_REGISTRY Option for saveConfigInfo().
static int	SAVE_IN_REGISTRY Option for saveConfigInfo().

Constructor Summary

IO()

Method Summary

static boolean	canAccessRegistry()
static int	checkReadWrite(IOHandle rw, TimeOut checkTime, Handle master, TimeOut masterTime)
static byte[]	getBytes(String data, String encoding)
static TextCodec	getCodec(String codecName) Add a new copy of a named codec.
static Iterator	getCodecs() Get an Iterator to go through the installed codecs.
static boolean	getConfigInfo(LiveData data, String keyName) Get a LiveData object from configuration information in the registry or file.
static boolean	getConfigInfo(LiveData data, String keyName, int options) Get a LiveData object from configuration information in the registry or file.
static String	getConfigInfo(String keyName) Read configuration data which may be stored in the registry or in a configuration file.
static String	getConfigInfo(String keyName, int options) Read configuration data which may be stored in the registry or in a configuration file.
static Vector	getStringList(String keyName) Read a Vector containing a list of string using getConfigInfo.
static void	main(String[] args)
static String	newString(byte[] data, int start, int length, String encoding)
static String	newString(byte[] data, String encoding)
static ByteArray	processAll(DataProcessor dp, byte[] source)
static ByteArray	processAll(DataProcessor dp, byte[] source, int offset, int length)
static ByteArray	processAll(DataProcessor dp, byte[] source, int offset, int length, ByteArray dest)
static void	processInPlace(DataProcessor dp, byte[] data, int offset, int length) This is used to process data in place.
static int	read(InputStream s, byte[] dest, int start, int count, boolean useFastStream, boolean mustReadAll) This method attempts to read count bytes from the stream and will not return until either all count bytes have been read or the end of the stream has been reached.
static int	read(Stream s, byte[] dest, int start, int count, boolean useFastStream, boolean mustReadAll) This method attempts to read count bytes from the stream and will not return until either all count bytes have been read or the end of the stream has been reached.
static void	readAll(InputStream s, byte[] dest, int start, int count) This is a blocking readAll.
static void	readAll(Stream s, byte[] dest) This is a blocking readAll.
static void	readAll(Stream s, byte[] dest, int start, int count) This is a blocking readAll.
static int	readAllBytes(File in, byte[] dest, int start, boolean useFastStream) Read all the bytes from a File, possibly using a FastStream.
static ByteArray	readAllBytes(File in, ByteArray dest, boolean useFastStream) Read all the bytes from a File, possibly using a FastStream.
static Handle	readAllBytes(Stream input, int knownSize, boolean stopAfterKnownSize) Read all bytes from a Stream, closing the Stream when done.
static byte[]	readAllBytes(Stream input, StringBuffer error) This reads all the bytes in a Stream (it will close the stream afterwards).
static CharArray	readAllChars(File in, CharArray dest, boolean useFastStream)
static CharArray	readAllChars(File in, CharArray dest, boolean useFastStream, TextCodec codec, ByteArray buffer)
static int	readFully(Stream s, byte[] dest) Deprecated. use readAll instead.
static int	readFully(Stream s, byte[] dest, int start, int count) Deprecated. use readAll instead.
static void	saveConfigInfo(LiveData data, String keyName) Save a LiveData object as configuration information in the registry or file.
static void	saveConfigInfo(LiveData data, String keyName, int saveOptions) Save a LiveData object as configuration information in the registry or file.
static void	saveConfigInfo(String data, String keyName, int saveOptions) Save the text in the registry.
static void	saveStringList(Vector text, String keyName, int saveOptions) Save a Vector containing a list of strings using saveConfigInfo.
static void	setCodec(String codecName, TextCodec codec) Add a new codec to the list of codecs.
static boolean	skip(RandomAccessStream ras, int num)
static RandomAccessStream	toRandomAccessStream(Streamable s, String mode, Handle masterHandle, TimeOut masterTimeOut) Request the creation of a RandomAccessStream from the Streamable object.
static Stream	toReadableStream(Streamable s, Handle masterHandle, TimeOut masterTimeOut) Request the creation of a readable Stream from the Streamable object.
static Stream	toWritableStream(Streamable s, boolean append, Handle masterHandle, TimeOut masterTimeOut) Request the creation of a writable Stream form the Streamable object.
static void	write(OutputStream s, byte[] src, int start, int count, boolean useFastStream) Write out all the bytes to an OutputStream, optionally using the FastStream interface if available.
static void	write(Stream s, byte[] src, int start, int count, boolean useFastStream) Write out all the bytes to a Stream, optionally using the FastStream interface if available.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

SAVE_IN_REGISTRY

public static final int SAVE_IN_REGISTRY

Option for saveConfigInfo().

See Also:

Constant Field Values

SAVE_IN_FILE

public static final int SAVE_IN_FILE

Option for saveConfigInfo().

See Also:

Constant Field Values

SAVE_IN_FILE_OR_REGISTRY

public static final int SAVE_IN_FILE_OR_REGISTRY

Option for saveConfigInfo().

See Also:

Constant Field Values

ASCII_CODEC

public static final String ASCII_CODEC

The canonical name for the Ewe library's Ascii Codec.

See Also:

Constant Field Values

JAVA_UTF8_CODEC

public static final String JAVA_UTF8_CODEC

The canonical name for the Ewe library's Ascii Codec.

See Also:

Constant Field Values

Constructor Detail

IO

public IO()

Method Detail

read

public static int read(Stream s,
                       byte[] dest,
                       int start,
                       int count,
                       boolean useFastStream,
                       boolean mustReadAll)
                throws IOException

This method attempts to read count bytes from the stream and will not return until either all count bytes have been read or the end of the stream has been reached. If mustReadAll is true, then failing to read all count bytes (because the stream ends before reaching count bytes) will result in an IOException being thrown.

Use this method when IO performance is a priority.

Parameters:

s - the input Stream.

dest - the destination array to hold the incoming bytes.

start - the offset within the destination array.

count - the number of bytes to read (this must be > 0).

useFastStream - if this is true AND the Stream implements FastStream, then the quickRead() method will be used to read the data.

mustReadAll - if this is true then an IOException will be thrown if a total of count bytes is not read in.

Returns:

The actual number of bytes read in, or -1 if the end of the stream has been reached.

Throws:

IOException - if an error occurs.

read

public static int read(InputStream s,
                       byte[] dest,
                       int start,
                       int count,
                       boolean useFastStream,
                       boolean mustReadAll)
                throws IOException

This method attempts to read count bytes from the stream and will not return until either all count bytes have been read or the end of the stream has been reached. If mustReadAll is true, then failing to read all count bytes (because the stream ends before reaching count bytes) will result in an IOException being thrown. Use this method when IO performance is a priority.

Parameters:

s - the InputStream to read from.

dest - the destination array to hold the incoming bytes.

start - the offset within the destination array.

count - the number of bytes to read (this must be > 0).

useFastStream - if this is true AND the Stream implements FastStream, then the quickRead() method will be used to read the data.

mustReadAll - if this is true then an IOException will be thrown if a total of count bytes is not read in.

Returns:

The actual number of bytes read in, or -1 if the end of the stream has been reached.

Throws:

IOException - if an error occurs.

write

public static void write(Stream s,
                         byte[] src,
                         int start,
                         int count,
                         boolean useFastStream)
                  throws IOException

Write out all the bytes to a Stream, optionally using the FastStream interface if available.

Parameters:

s - the Stream to write to.

src - the source data bytes to write.

start - the offset within the src array.

count - the number of bytes to write.

useFastStream - if this is true and the Stream implements FastStream, then the FastStrea.quickWrite() method will be used.

Throws:

IOException - if an error occurs.

write

public static void write(OutputStream s,
                         byte[] src,
                         int start,
                         int count,
                         boolean useFastStream)
                  throws IOException

Write out all the bytes to an OutputStream, optionally using the FastStream interface if available.

Parameters:

s - the Stream to write to.

src - the source data bytes to write.

start - the offset within the src array.

count - the number of bytes to write.

useFastStream - if this is true and the Stream implements FastStream, then the FastStrea.quickWrite() method will be used.

Throws:

IOException - if an error occurs.

readAllBytes

public static int readAllBytes(File in,
                               byte[] dest,
                               int start,
                               boolean useFastStream)
                        throws IOException

Read all the bytes from a File, possibly using a FastStream. The destination must have enough room to hold the incoming bytes.

Parameters:

in - The input File.

dest - The destination array.

start - the start position in the array.

useFastStream - true if the FastStream interface should be used if available.

Returns:

the number of bytes read.

Throws:

IOException - if there was an error reading the file.

readAllBytes

public static ByteArray readAllBytes(File in,
                                     ByteArray dest,
                                     boolean useFastStream)
                              throws IOException

Read all the bytes from a File, possibly using a FastStream. The bytes read in are appended to the destination ByteArray.

Parameters:

in - The input File.

dest - The destination ByteArray. If it is null a new one will be created and returned.

useFastStream - true if the FastStream interface should be used if available.

Returns:

the destination ByteArray or a new ByteArray if dest was null.

Throws:

IOException - if there was an error reading the file.

readAllChars

public static CharArray readAllChars(File in,
                                     CharArray dest,
                                     boolean useFastStream,
                                     TextCodec codec,
                                     ByteArray buffer)
                              throws IOException

Throws:

IOException

readAllChars

public static CharArray readAllChars(File in,
                                     CharArray dest,
                                     boolean useFastStream)
                              throws IOException

Throws:

IOException

readAll

public static void readAll(Stream s,
                           byte[] dest,
                           int start,
                           int count)
                    throws IOException

This is a blocking readAll. It will block the current thread.

Throws:

IOException

readAll

public static void readAll(InputStream s,
                           byte[] dest,
                           int start,
                           int count)
                    throws IOException

This is a blocking readAll. It will block the current thread.

Throws:

IOException

readAll

public static void readAll(Stream s,
                           byte[] dest)
                    throws IOException

This is a blocking readAll. It will block the current thread

Throws:

IOException

readFully

public static int readFully(Stream s,
                            byte[] dest,
                            int start,
                            int count)

Deprecated. use readAll instead.

This is a blocking readFully. It will block the current thread or Coroutine.

readFully

public static int readFully(Stream s,
                            byte[] dest)

Deprecated. use readAll instead.

This is a blocking readFully. It will block the current thread or Coroutine.

skip

public static boolean skip(RandomAccessStream ras,
                           int num)

processAll

public static ByteArray processAll(DataProcessor dp,
                                   byte[] source)

processAll

public static ByteArray processAll(DataProcessor dp,
                                   byte[] source,
                                   int offset,
                                   int length)

processAll

public static ByteArray processAll(DataProcessor dp,
                                   byte[] source,
                                   int offset,
                                   int length,
                                   ByteArray dest)
                            throws IOException

Throws:

IOException

processInPlace

public static void processInPlace(DataProcessor dp,
                                  byte[] data,
                                  int offset,
                                  int length)
                           throws IOException

This is used to process data in place. In order for it to work the data processor must have a block length of 1 byte and must produce output data exactly the same length as the input data, and it should have no maximum input data size.

Throws:

IOException

readAllBytes

public static byte[] readAllBytes(Stream input,
                                  StringBuffer error)

This reads all the bytes in a Stream (it will close the stream afterwards). If Stream is null it will return a null byte array. You can provide a StringBuffer "error" to accept any possible error messages.

readAllBytes

public static Handle readAllBytes(Stream input,
                                  int knownSize,
                                  boolean stopAfterKnownSize)

Read all bytes from a Stream, closing the Stream when done. The bytes read in are placed in a ewe.util.ByteArray object that is placed as the returnValue of the returned Handle.

Parameters:

input - The input stream to read from, it will be closed upon completion.

knownSize - The number of bytes expected to read. If it is -1 then the number to read will be unknown.

stopAfterKnownSize - if this is true then the copying will stop after the known number of bytes.

Returns:

A Handle that can be used to monitor the reading of the data.

canAccessRegistry

public static boolean canAccessRegistry()

saveStringList

public static void saveStringList(Vector text,
                                  String keyName,
                                  int saveOptions)
                           throws IOException

Save a Vector containing a list of strings using saveConfigInfo. The strings will be separated using a '\n' separator.

Parameters:

text - The list of strings to save.

keyName - The key name to use. This will be passed to saveConfigInfo().

saveOptions - one of the SAVE_IN options.

Throws:

IOException - If there was an error saving the information.

getStringList

public static Vector getStringList(String keyName)
                            throws IOException

Read a Vector containing a list of string using getConfigInfo.

Parameters:

keyName - The name of the key to save under.

Returns:

null if the data is not present, else a Vector of strings.

Throws:

IOException - If there was an error reading the information.

saveConfigInfo

public static void saveConfigInfo(String data,
                                  String keyName,
                                  int saveOptions)
                           throws IOException

Save the text in the registry. If saveOptions is SAVE_IN_REGISTRY and its length is less than or equal to 1000 chars bytes, the text will be saved under the name in the registry.

Parameters:

data - The text data to save.

keyName - The registry key name to store the data in. The actual save location will be "HKEY_LOCAL_MACHINE\Software\"+name, and the value will be saved as the default value. However if the name starts with HKEY_xxx, then it is assumed that the name provided will be the full registry key name.

If the string length is greater than 1000 chars OR if SAVE_IN_FILE is specified, it will be saved in a file in the program directory with a file name equal to the last subkey name in the keyName with a ".cfg" extension. And the file name will be saved in the registry instead.

saveOptions - should be one of SAVE_IN_REGISTRY or SAVE_IN_FILE or SAVE_IN_FILE_OR_REGISTRY. SAVE_IN_FILE_OR_REGISTRY tells it to save wherever is most appropriate given the data size.

Throws:

IOException - if the data could not be saved successfully.

getConfigInfo

public static String getConfigInfo(String keyName)
                            throws IOException

Read configuration data which may be stored in the registry or in a configuration file.

Parameters:

keyName - The registry key name to store the data in. The actual save location will be "HKEY_LOCAL_MACHINE\Software\"+name, and the value will be saved as the default value. However if the name starts with HKEYS_xxx, then it is assumed that the name provided will be the full registry key name.

If the string length is greater than 1000 chars OR if SAVE_IN_FILE is specified, it will be saved in a file in the program directory with a file name equal to the last subkey name in the keyName with a ".cfg" extension. And the file name will be saved in the registry instead.

Returns:

The configuration found or null if not found.

Throws:

IOException - If there is configuration info but there was an error reading it.

getConfigInfo

public static String getConfigInfo(String keyName,
                                   int options)
                            throws IOException

Read configuration data which may be stored in the registry or in a configuration file.

Parameters:

keyName - The registry key name to store the data in. The actual save location will be "HKEY_LOCAL_MACHINE\Software\"+name, and the value will be saved as the default value. However if the name starts with HKEYS_xxx, then it is assumed that the name provided will be the full registry key name.

If the string length is greater than 1000 chars OR if SAVE_IN_FILE is specified, it will be saved in a file in the program directory with a file name equal to the last subkey name in the keyName with a ".cfg" extension. And the file name will be saved in the registry instead.

Returns:

The configuration found or null if not found.

Throws:

IOException - If there is configuration info but there was an error reading it.

saveConfigInfo

public static void saveConfigInfo(LiveData data,
                                  String keyName,
                                  int saveOptions)
                           throws IOException

Save a LiveData object as configuration information in the registry or file.

Parameters:

data - The LiveData object to save.

keyName - The registry key name to store the data in. The actual save location will be "HKEY_LOCAL_MACHINE\Software\"+name, and the value will be saved as the default value. However if the name starts with HKEY_xxx, then it is assumed that the name provided will be the full registry key name.

If the string length is greater than 1000 chars OR if SAVE_IN_FILE is specified, it will be saved in a file in the program directory with a file name equal to the last subkey name in the keyName with a ".cfg" extension. And the file name will be saved in the registry instead.

Throws:

IOException - If there was an error saving the data.

saveConfigInfo

public static void saveConfigInfo(LiveData data,
                                  String keyName)
                           throws IOException

Save a LiveData object as configuration information in the registry or file.

Parameters:

data - The LiveData object to save.

keyName - The registry key name to store the data in. The actual save location will be "HKEY_LOCAL_MACHINE\Software\"+name, and the value will be saved as the default value. However if the name starts with HKEY_xxx, then it is assumed that the name provided will be the full registry key name.

If the string length is greater than 1000 chars OR if SAVE_IN_FILE is specified, it will be saved in a file in the program directory with a file name equal to the last subkey name in the keyName with a ".cfg" extension. And the file name will be saved in the registry instead.

Throws:

IOException - If there was an error saving the data.

getConfigInfo

public static boolean getConfigInfo(LiveData data,
                                    String keyName,
                                    int options)
                             throws IOException

Get a LiveData object from configuration information in the registry or file.

Parameters:

data - The LiveData object to load.

keyName - The registry key name to store the data in. The actual save location will be "HKEY_LOCAL_MACHINE\Software\"+name, and the value will be saved as the default value. However if the name starts with HKEY_xxx, then it is assumed that the name provided will be the full registry key name.

If the string length is greater than 1000 chars OR if SAVE_IN_FILE is specified, it will be saved in a file in the program directory with a file name equal to the last subkey name in the keyName with a ".cfg" extension. And the file name will be saved in the registry instead.

Throws:

IOException - If there is configuration info but there was an error reading it.

getConfigInfo

public static boolean getConfigInfo(LiveData data,
                                    String keyName)
                             throws IOException

Get a LiveData object from configuration information in the registry or file.

Parameters:

data - The LiveData object to load.

keyName - The registry key name to store the data in. The actual save location will be "HKEY_LOCAL_MACHINE\Software\"+name, and the value will be saved as the default value. However if the name starts with HKEY_xxx, then it is assumed that the name provided will be the full registry key name.

If the string length is greater than 1000 chars OR if SAVE_IN_FILE is specified, it will be saved in a file in the program directory with a file name equal to the last subkey name in the keyName with a ".cfg" extension. And the file name will be saved in the registry instead.

Throws:

IOException - If there is configuration info but there was an error reading it.

toRandomAccessStream

public static RandomAccessStream toRandomAccessStream(Streamable s,
                                                      String mode,
                                                      Handle masterHandle,
                                                      TimeOut masterTimeOut)
                                               throws IllegalArgumentException,
                                                      HandleStoppedException,
                                                      IOException,
                                                      InterruptedException

Request the creation of a RandomAccessStream from the Streamable object.

Parameters:

s - The Streamable object.

mode - The RandomAccess mode, "r" or "rw".

masterHandle - an optional Handle used to abort the process if necessary.

masterTimeOut - the length of time to wait for.

Returns:

The created Stream or null if the masterTimeOut timed out.

Throws:

HandleStoppedException - If the masterHandle was stopped externally.

IOException - If the Streamable failed to provide the requested Stream.

InterruptedException - If this mThread was interrupted.

IllegalArgumentException - If the mode is not correct.

toReadableStream

public static Stream toReadableStream(Streamable s,
                                      Handle masterHandle,
                                      TimeOut masterTimeOut)
                               throws HandleStoppedException,
                                      IOException,
                                      InterruptedException

Request the creation of a readable Stream from the Streamable object.

Parameters:

s - The Streamable object.

masterHandle - an optional Handle used to abort the process if necessary.

masterTimeOut - the length of time to wait for.

Returns:

The created Stream or null if the masterTimeOut timed out.

Throws:

HandleStoppedException - If the masterHandle was stopped externally.

IOException - If the Streamable failed to provide the requested Stream.

InterruptedException - If this mThread was interrupted.

toWritableStream

public static Stream toWritableStream(Streamable s,
                                      boolean append,
                                      Handle masterHandle,
                                      TimeOut masterTimeOut)
                               throws HandleStoppedException,
                                      IOException,
                                      InterruptedException

Request the creation of a writable Stream form the Streamable object.

Parameters:

s - The Streamable object.

append - if appending to the current data is requested.

masterHandle - an optional Handle used to abort the process if necessary.

masterTimeOut - the length of time to wait for.

Returns:

The created Stream or null if the masterTimeOut timed out.

Throws:

HandleStoppedException - If the masterHandle was stopped externally.

IOException - If the Streamable failed to provide the requested Stream.

InterruptedException - If this mThread was interrupted.

checkReadWrite

public static int checkReadWrite(IOHandle rw,
                                 TimeOut checkTime,
                                 Handle master,
                                 TimeOut masterTime)

main

public static void main(String[] args)
                 throws IOException

Throws:

IOException

setCodec

public static void setCodec(String codecName,
                            TextCodec codec)

Add a new codec to the list of codecs.

Parameters:

codecName - The canonical name of the codec.

codec - The codec itself.

getCodec

public static TextCodec getCodec(String codecName)

Add a new copy of a named codec.

Parameters:

codecName - The canonical name of the codec.

Returns:

a new copy of a named codec or null if not found.

getCodecs

public static Iterator getCodecs()

Get an Iterator to go through the installed codecs. The object returned by each call to next() on the Iterator will be of type ewe.util.Map.MapEntry object.

newString

public static String newString(byte[] data,
                               int start,
                               int length,
                               String encoding)
                        throws UnsupportedEncodingException

Throws:

UnsupportedEncodingException

newString

public static String newString(byte[] data,
                               String encoding)
                        throws UnsupportedEncodingException

Throws:

UnsupportedEncodingException

getBytes

public static byte[] getBytes(String data,
                              String encoding)
                       throws UnsupportedEncodingException

Throws:

UnsupportedEncodingException