de.fu_berlin.ties.io
Class IOUtils

java.lang.Object
  extended by de.fu_berlin.ties.io.IOUtils

public final class IOUtils
extends Object

A static class that provides utility constants and methods for I/O. No instances of this class can be created, only the static members should be used.

Version:
$Revision: 1.21 $, $Date: 2004/12/09 18:10:32 $, $Author: siefkes $
Author:
Christian Siefkes

Field Summary
static String CONFIG_COMPRESS_GZIP
          Configuration key: whether to compress your data in gzip format.
static char EXT_SEPARATOR
          The character separating the base name from the extension of a file (a dot).
static String KEY_LOCAL_CHARSET
          Configuration and context key: the character set to use when reading and writing local files.
static int STANDARD_BLOCK_SIZE
          The standard block size recommended for I/O.
static String STANDARD_HTTP_CHARSET
          The standard character set defined by the HTTP standard.
static String STANDARD_UNICODE_CHARSET
          The standard Unicode-compatible character set.
 
Method Summary
static File createOutFile(File directory, String localName)
          Creates a file for writing output to.
static File createOutFile(File directory, String localName, String outExtension)
          Creates a file for writing output to.
static File createOutFile(File directory, String localName, String outExtension, MutableInt last)
          Creates a file for writing output to.
static Charset determineCharset(InputStreamReader reader)
          Returns the charset used by an InputStreamReader.
static Charset determineCharset(OutputStreamWriter writer)
          Returns the charset used by an OutputStreamWriter.
static String determineCharsetName(InputStreamReader reader)
          Returns the canoncical name of the charset used by an InputStreamReader.
static String determineCharsetName(OutputStreamWriter writer)
          Returns the canoncical name of the charset used by an OutputStreamWriter.
static File determineOutputDirectory(TiesConfiguration config)
          Determines the output to directory to use, reading it from the TextProcessor.KEY_OUT_DIRECTORY configuration key in a given configuration.
static String getBaseName(File file)
          Returns the base name of a file (the local name without getExtension(File) and preceding dot).
static String getBaseName(URL url)
          Returns the base name of an URL (the local name without getExtension(File) and preceding dot).
static File getDefaultDirectory()
          Returns an default directory that can be given as "parent" when constructing file objects.
static String getExtension(File file)
          Returns the extension of a file.
static String getExtension(URL url)
          Returns the file extension of an URL.
static String getLocalName(URL url, boolean acceptDir)
          Returns the local name of an URL.
static InputStream openCompressableInStream(InputStream in)
          Opens an input stream that might have been compressed in gzip format.
static OutputStream openCompressableOutStream(OutputStream out, boolean doCompress)
          Transparently opens an input stream that may use compression to store the data (in gzip format).
static OutputStream openCompressableOutStream(OutputStream out, TiesConfiguration config)
          Transparently opens an input stream that may use compression to store the data (in gzip format).
static InputStreamReader openReader(File file, Configuration config)
          Opens an reader on a local file.
static InputStreamReader openReader(File file, String charset)
          Opens an reader on a local file, using a given charset.
static InputStreamReader openUnicodeReader(InputStream in)
          Opens a reader on an input stream that uses a Unicode character set (UTF-8, UTF-16, or UTF-32) and optionally a BOM (byte order mark) to identify the used charset.
static OutputStreamWriter openUnicodeWriter(OutputStream out)
          Opens a writer that uses the standard Unicode character set UTF-8.
static Writer openWriter(File file, Configuration config)
          Opens an writer on a local file.
static Writer openWriter(File file, String charset)
          Opens an writer on a local file, using a given charset.
static String readToString(Reader reader)
          Reads the contents of a reader into a string.
static int readToWriter(Reader reader, Writer writer)
          Reads the contents of a reader into a writer.
static String[] readURIList(CharSequence in)
          Converts an URI list as defined in RFC 2483 (MIME type text/uri-list) into an array of strings.
static String[] readURIList(Reader in)
          Converts an URI list as defined in RFC 2483 (MIME type text/uri-list) into an array of strings.
static void setDefaultDirectory(File directory)
          Modifies the default directory that can be given as "parent" when constructing file objects.
static boolean tryToClose(InputStream in)
          Convenience method for closing an input stream.
static boolean tryToClose(OutputStream out)
          Convenience method for closing an output stream.
static boolean tryToClose(Reader reader)
          Convenience method for closing a reader.
static boolean tryToClose(Writer writer)
          Convenience method for closing a writer.
static void writeToWriter(CharSequence input, Writer writer)
          Writes the contents of a character sequence to a writer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

KEY_LOCAL_CHARSET

public static final String KEY_LOCAL_CHARSET
Configuration and context key: the character set to use when reading and writing local files. If omitted, the default charset of the current platform is used.

See Also:
Constant Field Values

CONFIG_COMPRESS_GZIP

public static final String CONFIG_COMPRESS_GZIP
Configuration key: whether to compress your data in gzip format. Used by openCompressableOutStream(OutputStream, TiesConfiguration).

See Also:
Constant Field Values

STANDARD_BLOCK_SIZE

public static final int STANDARD_BLOCK_SIZE
The standard block size recommended for I/O.

See Also:
Constant Field Values

STANDARD_HTTP_CHARSET

public static final String STANDARD_HTTP_CHARSET
The standard character set defined by the HTTP standard.

See Also:
Constant Field Values

STANDARD_UNICODE_CHARSET

public static final String STANDARD_UNICODE_CHARSET
The standard Unicode-compatible character set.

See Also:
Constant Field Values

EXT_SEPARATOR

public static final char EXT_SEPARATOR
The character separating the base name from the extension of a file (a dot).

See Also:
Constant Field Values
Method Detail

createOutFile

public static File createOutFile(File directory,
                                 String localName)
Creates a file for writing output to. Delegates to createOutFile(File, String, String) without specifying an extension.

Parameters:
directory - the directory in which the file should be created; if null or not writable, the file is created in the current working directory instead
localName - the local name of the input file --- the extension of this file (if any) is replaced by the specified output extension
Returns:
the create file

createOutFile

public static File createOutFile(File directory,
                                 String localName,
                                 String outExtension)
Creates a file for writing output to. The file is created in the specified directory if given and writable; otherwise it is created in the current working directory. The resulting file can also be used as a directory (by calling its File.mkdir() method).

The name of the file is derivated from the given local name by replacing the extension of the input file (if any) by the specified outExtension. If a file with this name already exists, "2" or the next available number is inserted before the extension unless an unused file name is found.

E.g. for input file "test.txt" and output extension "out", the file "test.out" is created. If this file already exists, the file "test2.out" is created instead (or "test3.out" etc. unless an unsed name is found).

Parameters:
directory - the directory in which the file should be created; if null or not writable, the file is created in the current working directory instead
localName - the local name of the input file --- the extension of this file (if any) is replaced by the specified output extension
outExtension - the extension to append to the output file (without a starting dot); ignored if empty or null
Returns:
the create file

createOutFile

public static File createOutFile(File directory,
                                 String localName,
                                 String outExtension,
                                 MutableInt last)
Creates a file for writing output to. The file is created in the specified directory if given and writable; otherwise it is created in the current working directory. The resulting file can also be used as a directory (by calling its File.mkdir() method).

The name of the file is derivated from the given local name by replacing the extension of the input file (if any) by the specified outExtension. If a file with this name already exists, "2" or the next available number is inserted before the extension unless an unused file name is found.

E.g. for input file "test.txt" and output extension "out", the file "test.out" is created. If this file already exists, the file "test2.out" is created instead (or "test3.out" etc. unless an unsed name is found).

Parameters:
directory - the directory in which the file should be created; if null or not writable, the file is created in the current working directory instead
localName - the local name of the input file --- the extension of this file (if any) is replaced by the specified output extension
outExtension - the extension to append to the output file (without a starting dot); ignored if empty or null
last - if not null, assumped to wrap the last numeric prefix already in use, i.e. the first tried prefix will the the value of this + 1; after determining a file name, the value will be set to the numeric prefix used this time
Returns:
the create file

determineCharset

public static Charset determineCharset(InputStreamReader reader)
Returns the charset used by an InputStreamReader.

Parameters:
reader - the reader to check
Returns:
the charset used by the reader

determineCharsetName

public static String determineCharsetName(InputStreamReader reader)
Returns the canoncical name of the charset used by an InputStreamReader. This method always returns the canonical (standard) name. It should preferably be used instead of calling InputStreamReader.getEncoding() directly, because that method often returns a non-standard ("historical") name.

Parameters:
reader - the reader to check
Returns:
the canonical name of the charset used by the reader

determineCharset

public static Charset determineCharset(OutputStreamWriter writer)
Returns the charset used by an OutputStreamWriter.

Parameters:
writer - the writer to check
Returns:
the charset used by the writer

determineCharsetName

public static String determineCharsetName(OutputStreamWriter writer)
Returns the canoncical name of the charset used by an OutputStreamWriter. This method always returns the canonical (standard) name. It should preferably be used instead of calling OutputStreamWriter.getEncoding() directly, because that method often returns a non-standard ("historical") name.

Parameters:
writer - the writer to check
Returns:
the canonical name of the charset used by the writer

determineOutputDirectory

public static File determineOutputDirectory(TiesConfiguration config)
Determines the output to directory to use, reading it from the TextProcessor.KEY_OUT_DIRECTORY configuration key in a given configuration.

Parameters:
config - configuration used to determine the output directory (read from the TextProcessor.KEY_OUT_DIRECTORY key)
Returns:
the output directory to use; or null if none is configured

getBaseName

public static String getBaseName(File file)
Returns the base name of a file (the local name without getExtension(File) and preceding dot).

Parameters:
file - the file to check
Returns:
the base name of the given file

getBaseName

public static String getBaseName(URL url)
Returns the base name of an URL (the local name without getExtension(File) and preceding dot).

Parameters:
url - the URL to check
Returns:
the base name of the given URL

getDefaultDirectory

public static File getDefaultDirectory()
Returns an default directory that can be given as "parent" when constructing file objects. Initially set to null so the "system-dependent default directory" (typically the working directory) will be used.

Returns:
the default directory

getExtension

public static String getExtension(File file)
Returns the extension of a file.

Parameters:
file - the file to check
Returns:
the extension of the given file; or an empty string if no extension exists

getExtension

public static String getExtension(URL url)
Returns the file extension of an URL.

Parameters:
url - the URL to check
Returns:
the extension of the given URL; or an empty string if no extension exists

getLocalName

public static String getLocalName(URL url,
                                  boolean acceptDir)
Returns the local name of an URL. This is the last existing element of from the path component of the URL, typically the local file name (without directories).

For URLs that are recognizable as directories (i.e. end in a slash), the name of the final directory is returned if acceptDir is true -- otherwise the empty string is returned.

Parameters:
url - the URL to check
acceptDir - whether to return a final directory name (see description)
Returns:
the local name

openCompressableInStream

public static InputStream openCompressableInStream(InputStream in)
                                            throws IOException
Opens an input stream that might have been compressed in gzip format. This method autodetects whether the stream has been compressed and returns a stream that allows accessing the uncompressed data.

Parameters:
in - the raw input stream (either uncompressed or in gzip format
Returns:
a stream that allows accessing the uncompressed data
Throws:
IOException - if an I/O error has occurred

openCompressableOutStream

public static OutputStream openCompressableOutStream(OutputStream out,
                                                     boolean doCompress)
                                              throws IOException
Transparently opens an input stream that may use compression to store the data (in gzip format).

Parameters:
out - the original output stream
doCompress - whether or not to use compression
Returns:
to output stream to use for storing data; will be a GZIPOutputStream wrapping out if doCompress is true; otherwise it will be the raw out stream
Throws:
IOException - if an I/O error has occurred

openCompressableOutStream

public static OutputStream openCompressableOutStream(OutputStream out,
                                                     TiesConfiguration config)
                                              throws IOException
Transparently opens an input stream that may use compression to store the data (in gzip format). Checks the CONFIG_COMPRESS_GZIP parameter to decide whether or not to use compression.

Parameters:
out - the original output stream
config - the configuration to use
Returns:
to output stream to use for storing data;
Throws:
IOException - if an I/O error has occurred

openReader

public static InputStreamReader openReader(File file,
                                           Configuration config)
                                    throws IOException
Opens an reader on a local file. Uses the configured character set -- if not specified, the default charset of the current platform is used instead. Compressed files are automatically decompressed (using the openCompressableInStream(InputStream) method). Don't forget to finally close any reader you open!

Parameters:
file - the file to read
config - the configuration to use
Returns:
a reader on the local file
Throws:
IOException - if an I/O error has occurred

openReader

public static InputStreamReader openReader(File file,
                                           String charset)
                                    throws IOException
Opens an reader on a local file, using a given charset. Compressed files are automatically decompressed (using the openCompressableInStream(InputStream) method). Don't forget to finally close any reader you open!

Parameters:
file - the file to read
charset - the character set to use for reading the file; if null, the default charset of the current platform is used
Returns:
a reader on the local file
Throws:
IOException - if an I/O error has occurred

openUnicodeReader

public static InputStreamReader openUnicodeReader(InputStream in)
                                           throws IOException
Opens a reader on an input stream that uses a Unicode character set (UTF-8, UTF-16, or UTF-32) and optionally a BOM (byte order mark) to identify the used charset. UTF-8 is used if BOM is not found.

Adapted from the UnicodeReader class created by Thomas Weidenfeller and Aki Nieminen.

Parameters:
in - the input stream to wrap
Returns:
a reader on the stream
Throws:
IOException - if an I/O error has occurred

openUnicodeWriter

public static OutputStreamWriter openUnicodeWriter(OutputStream out)
Opens a writer that uses the standard Unicode character set UTF-8.

Parameters:
out - the output stream to wrap
Returns:
a writer on the stream

openWriter

public static Writer openWriter(File file,
                                Configuration config)
                         throws IOException,
                                UnsupportedEncodingException
Opens an writer on a local file. Uses the configured character set -- if not specified, the default charset of the current platform is used instead. Don't forget to finally close any writer you open!

Parameters:
file - the file to write to
config - the configuration to use
Returns:
a writer on the local file
Throws:
IOException - if the file is a directory or for some other reason cannot be opened for writing
UnsupportedEncodingException - if the named charset is not supported

openWriter

public static Writer openWriter(File file,
                                String charset)
                         throws IOException,
                                UnsupportedEncodingException
Opens an writer on a local file, using a given charset. Don't forget to finally close any writer you open!

Parameters:
file - the file to write to
charset - the character set to use for writing the file; if null, the default charset of the current platform is used
Returns:
a writer on the local file
Throws:
IOException - if the file is a directory or for some other reason cannot be opened for writing
UnsupportedEncodingException - if the named charset is not supported

readToString

public static String readToString(Reader reader)
                           throws IOException
Reads the contents of a reader into a string. The reader is not closed by this method.

Parameters:
reader - the reader to use
Returns:
the contents of the reader
Throws:
IOException - if an I/O error occurs

readToWriter

public static int readToWriter(Reader reader,
                               Writer writer)
                        throws IOException
Reads the contents of a reader into a writer. Neither reader nor writer are closed by this method.

Parameters:
reader - the reader to read from
writer - the writer to write to write to
Returns:
the number of characters read
Throws:
IOException - if an I/O error occurs

readURIList

public static String[] readURIList(CharSequence in)
Converts an URI list as defined in RFC 2483 (MIME type text/uri-list) into an array of strings. Comment lines in the input are ignored.

Parameters:
in - the URI list to convert
Returns:
an array of strings containing the URIs/URLs listed in the input

readURIList

public static String[] readURIList(Reader in)
                            throws IOException
Converts an URI list as defined in RFC 2483 (MIME type text/uri-list) into an array of strings. Comment lines in the input are ignored.

Parameters:
in - a reader containing the URI list to convert
Returns:
an array of strings containing the URIs/URLs listed in the input
Throws:
IOException - if an I/O error occurs

setDefaultDirectory

public static void setDefaultDirectory(File directory)
                                throws IllegalArgumentException
Modifies the default directory that can be given as "parent" when constructing file objects. Can be set to null so the "system-dependent default directory" (typically the working directory) will be used.

Parameters:
directory - the new directory to use
Throws:
IllegalArgumentException - if the given directory is neither null nor an existing directory

tryToClose

public static boolean tryToClose(InputStream in)
Convenience method for closing an input stream. If the specified stream is null, this method does nothing. Any IOException thrown during closing is swallowed by this method.

Parameters:
in - the input stream to close (might be null)
Returns:
true if the stream was closed successfully, false otherwise (the stream was null or an exception was thrown during closing)

tryToClose

public static boolean tryToClose(OutputStream out)
Convenience method for closing an output stream. If the specified stream is null, this method does nothing. Any IOException thrown during closing is swallowed by this method.

Parameters:
out - the output stream to close (might be null)
Returns:
true if the stream was closed successfully, false otherwise (the stream was null or an exception was thrown during closing)

tryToClose

public static boolean tryToClose(Reader reader)
Convenience method for closing a reader. If the specified reader is null, this method does nothing. Any IOException thrown during closing is swallowed by this method.

Parameters:
reader - the reader to close (might be null)
Returns:
true if the reader was closed successfully, false otherwise (reader was null or an exception was thrown during closing)

tryToClose

public static boolean tryToClose(Writer writer)
Convenience method for closing a writer. If the specified writer is null, this method does nothing. Any IOException thrown during closing is swallowed by this method.

Parameters:
writer - the writer to close (might be null)
Returns:
true if the writer was closed successfully, false otherwise (writer was null or an exception was thrown during closing)

writeToWriter

public static void writeToWriter(CharSequence input,
                                 Writer writer)
                          throws IOException
Writes the contents of a character sequence to a writer. The writer is flushed but not closed by this method.

Parameters:
input - the text to send to the wrier
writer - the writer to write to write to
Throws:
IOException - if an I/O error occurs


Copyright © 2003-2004 Christian Siefkes. All Rights Reserved.