Package nzilbb.util

Class IO

java.lang.Object

nzilbb.util.IO

public class IO
extends Object

Helper functions for Input/Output operations.

Author:

Robert Fromont robert@fromont.net.nz

Constructor Summary

Constructors

Constructor	Description
IO()

Method Summary

Modifier and Type	Method	Description
static void	Backup(File file)	If the given file exists, it's renamed to a filename with the last modification timestamp included.
static String	Base64Encode(InputStream content)	Encodes the given content as a BASE64-encoded string.
static String	Base64Encode(String url)	Encodes the content of the given url content as a BASE64-encoded string.
static String	Base64Encode(URL url)	Encodes the content of the given url content as a BASE64-encoded string.
static void	Copy(File source, File destination)	Copies a file.
static String	Extension(File file)	Determines the file extension (not including the dot) of the given file.
static String	Extension(String name)	Determines the file extension (not including the dot) of the given file.
static Object	FindImplementorInJar(File file, ClassLoader parentLoader, Class c)	Scans the given jar file for an instance of a particular class/interface.
static Vector	FindImplementorsInJar(File file, ClassLoader parentLoader, Class c)	Scans the given jar file for instances of a particular class/interface.
static String	InputStreamToString(InputStream input)	Reads the contents of the given InputStream into a String, assuming it's UTF-8 encoded text.
static String	JarCommentOfClass(Class c)	Determines the 'comment' of the jar file that the given class comes from, which is is often used to store the version of modules and libraries.
static File	JarFileOfClass(Class c)	Determines the jar file that the given class comes from.
static String	OnlyASCII(String s)	Strips all non-ASCII characters from the given string.
static Properties	ProjectProperties(Class c)	Accesses the project.properties resource of the given class.
static long	Pump(InputStream input, OutputStream output)	Copy all data from an input stream to an output stream.
static long	Pump(InputStream input, OutputStream output, boolean closeStreams)	Copy all data from an input stream to an output stream.
static long	Pump(InputStream input, OutputStream output, boolean closeStreams, LongConsumer bytesCopied)	Copy all data from an input stream to an output stream.
static boolean	RecursivelyDelete(File dir)	Recursively deletes a directory.
static void	Rename(File source, File destination)	Renames a file.
static String	SafeFileNameUrl(String s)	Converts the given string into a version that's generally safe for a file name or URL.
static long	SaveInputStreamToFile(InputStream input, File file)	Saves the content of a URL to a file.
static long	SaveInputStreamToFile(InputStream input, File file, LongConsumer bytesSaved)	Saves the content of a URL to a file.
static long	SaveUrlConnectionToFile(URLConnection connection, File file)	Saves the content of a URL to a file.
static long	SaveUrlConnectionToFile(URLConnection connection, File file, IntConsumer percentComplete)	Saves the content of a URL to a file.
static long	SaveUrlToFile(URL url, File file)	Saves the content of a URL to a file.
static long	SaveUrlToFile(URL url, File file, IntConsumer percentComplete)	Saves the content of a URL to a file.
static int	Unzip(File zip, File dir)	Unzips a .zip file into the given directory
static int	Unzip(File zip, File dir, String ignorePattern, IntConsumer percentComplete)	Unzips a .zip file into teh given directory
static int	Unzip(File zip, File dir, IntConsumer percentComplete)	Unzips a .zip file into teh given directory
static int	UnzipOnly(File zip, File dir, String includePattern, IntConsumer percentComplete)	Unzips a .zip file into teh given directory
static String	WithoutExtension(File file)	Determines the name of the given file without extension (not including the dot).
static String	WithoutExtension(String name)	Determines the name of the given file without extension (not including the dot).

Methods inherited from class java.lang.Object

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

Constructor Detail

IO

public IO()

Method Detail

Backup

public static void Backup(File file)
                   throws IOException

If the given file exists, it's renamed to a filename with the last modification timestamp included.

Parameters:

file - The file to backup.

Throws:

IOException - On IO error.

Extension

public static String Extension(File file)

Determines the file extension (not including the dot) of the given file.

The extension is assumed to have at least one alphabetic character - i.e. .trs of something.trs but not .678 of something__1.234-5.678.

Parameters:

file - The file.

Returns:

The extension (not including the dot) of the given file.

Extension

public static String Extension(String name)

Determines the file extension (not including the dot) of the given file.

The extension is assumed to have at least one alphabetic character - i.e. .trs of something.trs but not .678 of something__1.234-5.678.

Parameters:

name - The file name.

Returns:

The extension (not including the dot) of the given file.

WithoutExtension

public static String WithoutExtension(File file)

Determines the name of the given file without extension (not including the dot).

The extension is assumed to have at least one alphabetic character - i.e. .trs of something.trs but not .678 of something__1.234-5.678.

Parameters:

file - The file.

Returns:

The name of the given file without extension (not including the dot).

WithoutExtension

public static String WithoutExtension(String name)

Determines the name of the given file without extension (not including the dot).

The extension is assumed to have at least one alphabetic character - i.e. .trs of something.trs but not .678 of something__1.234-5.678.

Parameters:

name - The file name.

Returns:

The name of the given file without extension (not including the dot).

Copy

public static void Copy(File source,
                        File destination)
                 throws IOException

Copies a file.

Parameters:

source - The original file.

destination - The new file.

Throws:

IOException - On file IO error.

Rename

public static void Rename(File source,
                          File destination)
                   throws IOException

Renames a file.

Parameters:

source - The original file.

destination - The new file.

Throws:

IOException - On file IO error.

SaveUrlToFile

public static long SaveUrlToFile(URL url,
                                 File file,
                                 IntConsumer percentComplete)
                          throws IOException

Saves the content of a URL to a file.

Parameters:

url - The URL of the content.

file - The file to save the content to.

percentComplete - A monitor object that receives progress updates, as an integer representing percent complete. Can be null.

Returns:

The number size of the content in bytes.

Throws:

IOException - On file IO error.

SaveUrlConnectionToFile

public static long SaveUrlConnectionToFile(URLConnection connection,
                                           File file,
                                           IntConsumer percentComplete)
                                    throws IOException

Saves the content of a URL to a file.

Parameters:

connection - The URL connection to the content.

file - The file to save the content to.

percentComplete - A monitor object that receives progress updates, as an integer representing percent complete. Can be null.

Returns:

The number size of the content in bytes.

Throws:

IOException - On file IO error.

SaveInputStreamToFile

public static long SaveInputStreamToFile(InputStream input,
                                         File file,
                                         LongConsumer bytesSaved)
                                  throws IOException

Saves the content of a URL to a file.

Parameters:

input - The input stream containing the file content.

file - The file to save the content to.

bytesSaved - A monitor object that receives progress updates, as a long representing the number of bytes saved. Can be null.

Returns:

The number size of the content in bytes.

Throws:

IOException - On file IO error.

SaveUrlToFile

public static long SaveUrlToFile(URL url,
                                 File file)
                          throws IOException

Saves the content of a URL to a file.

Parameters:

url - The URL of the content.

file - The file to save the content to.

Returns:

The number size of the content in bytes.

Throws:

IOException - On file IO error.

SaveUrlConnectionToFile

public static long SaveUrlConnectionToFile(URLConnection connection,
                                           File file)
                                    throws IOException

Saves the content of a URL to a file.

Parameters:

connection - The URL connection to the content.

file - The file to save the content to.

Returns:

The number size of the content in bytes.

Throws:

IOException - On file IO error.

SaveInputStreamToFile

public static long SaveInputStreamToFile(InputStream input,
                                         File file)
                                  throws IOException

Saves the content of a URL to a file.

Parameters:

input - The input stream containing the file content.

file - The file to save the content to.

Returns:

The number size of the content in bytes.

Throws:

IOException - On file IO error.

InputStreamToString

public static String InputStreamToString(InputStream input)
                                  throws IOException

Reads the contents of the given InputStream into a String, assuming it's UTF-8 encoded text.

The InputStream is closed by the this method.

Parameters:

input -

Returns:

The contents of the given InputStream.

Throws:

IOException

Pump

public static long Pump(InputStream input,
                        OutputStream output)
                 throws IOException

Copy all data from an input stream to an output stream.

Parameters:

input - Source of data.

output - Destination for data.

Returns:

The number of bytes copied.

Throws:

IOException - On file IO error.

Pump

public static long Pump(InputStream input,
                        OutputStream output,
                        boolean closeStreams)
                 throws IOException

Copy all data from an input stream to an output stream.

Parameters:

input - Source of data.

output - Destination for data.

closeStreams - true if the streams should be closed after the data is exhausted, false otherwise.

Returns:

The number of bytes copied.

Throws:

IOException - On file IO error.

Pump

public static long Pump(InputStream input,
                        OutputStream output,
                        boolean closeStreams,
                        LongConsumer bytesCopied)
                 throws IOException

Copy all data from an input stream to an output stream.

Parameters:

input - Source of data.

output - Destination for data.

closeStreams - true if the streams should be closed after the data is exhausted, false otherwise.

bytesCopied - A monitor object that receives progress updates, as a long representing the number of bytes copied. Can be null.

Returns:

The number of bytes copied.

Throws:

IOException - On file IO error.

FindImplementorInJar

public static Object FindImplementorInJar(File file,
                                          ClassLoader parentLoader,
                                          Class c)
                                   throws IOException

Scans the given jar file for an instance of a particular class/interface. The implementor must be registered in the jar file, by way of a manifest attribute named after the class (with dots converted to hyphens to meet the attribute name requirements of jar manifests). e.g. if c = nzilbb.ag.serialize.IDeserializer and file contains a class called nzilbb.praat.TextGridDeserializer that implements nzilbb.ag.serialize.IDeserializer, in order to be returned by this method, file must also have a manifest attribute called nzilbb-ag-serialize-IDeserializer whose value is nzilbb.praat.TextGridDeserializer.

If there are multiple implementing classes registered in the file, only the first one is returned.

Parameters:

file - The jar file.

parentLoader - The parent class loader.

c - The class/interface to search for.

Returns:

An of objects that implement the given class/interface, or null if none was found.

Throws:

IOException - On file IO error.

FindImplementorsInJar

public static Vector FindImplementorsInJar(File file,
                                           ClassLoader parentLoader,
                                           Class c)
                                    throws IOException

Scans the given jar file for instances of a particular class/interface. The implementors must be registered in the jar file, by way of a manifest attribute named after the class (with dots converted to hyphens to meet the attribute name requirements of jar manifests). e.g. if c = nzilbb.ag.serialize.IDeserializer and file contains a class called nzilbb.praat.TextGridDeserializer that implements nzilbb.ag.serialize.IDeserializer, in order to be returned by this method, file must also have a manifest attribute called nzilbb-ag-serialize-IDeserializer whose value is nzilbb.praat.TextGridDeserializer.

There can be multiple implementing classes registered in the file; the value of the manifest attribute is assumed to be a space-delimited list.

Parameters:

file - The jar file.

parentLoader - The parent class loader.

c - The class/interface to search for.

Returns:

A list of objects that implement the given class/interface, which may be empty.

Throws:

IOException - On file IO error.

JarFileOfClass

public static File JarFileOfClass(Class c)

Determines the jar file that the given class comes from.

Parameters:

c - The class implemented.

Returns:

The jar file the given class implementation comes from, or null if it's not from a jar file.

JarCommentOfClass

public static String JarCommentOfClass(Class c)

Determines the 'comment' of the jar file that the given class comes from, which is is often used to store the version of modules and libraries.

Parameters:

c - The class implemented.

Returns:

The comment of the jar file the given class implementation comes from, or null if it's not from a jar file or there's no comment.

Unzip

public static int Unzip(File zip,
                        File dir)
                 throws IOException

Unzips a .zip file into the given directory

Parameters:

zip - The zip file to unzip.

dir - The destination directory into which the contents should be unzipped, which must already exist.

Returns:

The number of files unzipped.

Throws:

IOException

Unzip

public static int Unzip(File zip,
                        File dir,
                        IntConsumer percentComplete)
                 throws IOException

Unzips a .zip file into teh given directory

Parameters:

zip - The zip file to unzip.

dir - The destination directory into which the contents should be unzipped, which must already exist.

percentComplete - A monitor object that receives progress updates, as an integer representing percent complete. Can be null.

Returns:

The number of files unzipped.

Throws:

IOException

Unzip

public static int Unzip(File zip,
                        File dir,
                        String ignorePattern,
                        IntConsumer percentComplete)
                 throws IOException

Unzips a .zip file into teh given directory

Parameters:

zip - The zip file to unzip.

dir - The destination directory into which the contents should be unzipped, which must already exist.

ignorePattern - A regular expression for identifying entries that should not be unzipped, or null to unzip all entries.

percentComplete - A monitor object that receives progress updates, as an integer representing percent complete. Can be null.

Returns:

The number of files unzipped.

Throws:

IOException

UnzipOnly

public static int UnzipOnly(File zip,
                            File dir,
                            String includePattern,
                            IntConsumer percentComplete)
                     throws IOException

Unzips a .zip file into teh given directory

Parameters:

zip - The zip file to unzip.

dir - The destination directory into which the contents should be unzipped, which must already exist.

includePattern - A regular expression for identifying the only entries that should be unzipped.

percentComplete - A monitor object that receives progress updates, as an integer representing percent complete. Can be null.

Returns:

The number of files unzipped.

Throws:

IOException

ProjectProperties

public static Properties ProjectProperties(Class c)

Accesses the project.properties resource of the given class.

Parameters:

c -

Returns:

The project properties.

RecursivelyDelete

public static boolean RecursivelyDelete(File dir)

Recursively deletes a directory.

Parameters:

dir - The directory to delete.

Returns:

true if the the directory was successfully deleted, false otherwise.

Base64Encode

public static String Base64Encode(String url)
                           throws IOException

Encodes the content of the given url content as a BASE64-encoded string.

Parameters:

url - A URL to the content to be encoded.

Returns:

A BASE64-encoded representation of the content.

Throws:

IOException

Base64Encode

public static String Base64Encode(URL url)
                           throws IOException

Encodes the content of the given url content as a BASE64-encoded string.

Parameters:

url - A URL to the content to be encoded.

Returns:

A BASE64-encoded representation of the content.

Throws:

IOException

Base64Encode

public static String Base64Encode(InputStream content)
                           throws IOException

Encodes the given content as a BASE64-encoded string.

Parameters:

content - The content to encode.

Returns:

A BASE64-encoded representation of the content.

Throws:

IOException

SafeFileNameUrl

public static String SafeFileNameUrl(String s)

Converts the given string into a version that's generally safe for a file name or URL.

Specifically:

• the following characters are removed: \?*+$
• the following characters are converted to underscore: |:!=^
• the following characters are converted to text alternatives: @&><

No URL-encoding is performed.

Parameters:

s - The possibly unsafe string.

Returns:

The given string with characters that are unsafe for file names or URLs removed. If s is null, an empty string is returned.

OnlyASCII

public static String OnlyASCII(String s)

Strips all non-ASCII characters from the given string. Letters with accents are converted to the corresponding letter without the accent.

Parameters:

s - The possibly-non-ASCII string.

Returns:

The given string with accents and other non-ASCII characters removed. If s is null, an empty string is returned.