ptolemy.util
Class FileUtilities

java.lang.Object
  ptolemy.util.FileUtilities

public class FileUtilities
extends java.lang.Object

A collection of utilities for manipulating files These utilities do not depend on any other ptolemy.* packages.

Since:

Ptolemy II 4.0

Version:

$Id: FileUtilities.java 59167 2010-09-21 17:08:02Z cxh $

Author:

Christopher Brooks

Accepted Rating:

Green (cxh)

Proposed Rating:

Green (cxh)

Field Summary

private static java.lang.String	_CLASSPATH_VALUE Tag value used by this class and registered as a parser constant for the identifier "CLASSPATH" to indicate searching in the classpath.
static java.io.BufferedReader	STD_IN Standard in as a reader, which will be non-null only after a call to openForReading("System.in").
static java.io.PrintWriter	STD_OUT Standard out as a writer, which will be non-null only after a call to openForWriting("System.out").

Constructor Summary

private

FileUtilities() Instances of this class cannot be created.

Method Summary

private static void	_binaryCopyStream(java.io.InputStream inputStream, java.io.File destinationFile) Copy files safely.
private static byte[]	_binaryReadStream(java.io.InputStream inputStream) Read a stream safely.
private static java.net.URL	_searchClassPath(java.lang.String name, java.lang.ClassLoader classLoader) Search the classpath.
private static java.lang.String	_trimClassPath(java.lang.String name) Remove the value of _CLASSPATH_VALUE or "$CLASSPATH".
static boolean	binaryCopyURLToFile(java.net.URL sourceURL, java.io.File destinationFile) Copy sourceURL to destinationFile without doing any byte conversion.
static byte[]	binaryReadURLToByteArray(java.net.URL sourceURL) Read a sourceURL without doing any byte conversion.
static void	extractJarFile(java.lang.String jarFileName, java.lang.String directoryName) Extract a jar file into a directory.
static void	main(java.lang.String[] args) Extract the contents of a jar file.
static java.io.File	nameToFile(java.lang.String name, java.net.URI base) Given a file name or URL, construct a java.io.File object that refers to the file name or URL.
static java.net.URL	nameToURL(java.lang.String name, java.net.URI baseDirectory, java.lang.ClassLoader classLoader) Given a file or URL name, return as a URL.
static java.io.BufferedReader	openForReading(java.lang.String name, java.net.URI base, java.lang.ClassLoader classLoader) Open the specified file for reading.
static java.io.Writer	openForWriting(java.lang.String name, java.net.URI base, boolean append) Open the specified file for writing or appending.

Methods inherited from class java.lang.Object

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

Field Detail

STD_IN

public static java.io.BufferedReader STD_IN

Standard in as a reader, which will be non-null only after a call to openForReading("System.in").

STD_OUT

public static java.io.PrintWriter STD_OUT

Standard out as a writer, which will be non-null only after a call to openForWriting("System.out").

_CLASSPATH_VALUE

private static java.lang.String _CLASSPATH_VALUE

Tag value used by this class and registered as a parser constant for the identifier "CLASSPATH" to indicate searching in the classpath. This is a hack, but it deals with the fact that Java is not symmetric in how it deals with getting files from the classpath (using getResource) and getting files from the file system.

Constructor Detail

FileUtilities

private FileUtilities()

Instances of this class cannot be created.

Method Detail

binaryCopyURLToFile

public static boolean binaryCopyURLToFile(java.net.URL sourceURL,
                                          java.io.File destinationFile)
                                   throws java.io.IOException

Copy sourceURL to destinationFile without doing any byte conversion.

Parameters:

sourceURL - The source URL

destinationFile - The destination File.

Returns:

true if the file was copied, false if the file was not copied because the sourceURL and the destinationFile refer to the same file.

Throws:

java.io.IOException - If the source file does not exist.

binaryReadURLToByteArray

public static byte[] binaryReadURLToByteArray(java.net.URL sourceURL)
                                       throws java.io.IOException

Read a sourceURL without doing any byte conversion.

Parameters:

sourceURL - The source URL

Returns:

The array of bytes read from the URL.

Throws:

java.io.IOException - If the source URL does not exist.

extractJarFile

public static void extractJarFile(java.lang.String jarFileName,
                                  java.lang.String directoryName)
                           throws java.io.IOException

Extract a jar file into a directory. This is a trivial implementation of the jar -xf command.

Parameters:

jarFileName - The name of the jar file to extract

directoryName - The name of the directory. If this argument is null, then the files are extracted in the current directory.

Throws:

java.io.IOException - If the jar file cannot be opened, or if there are problems extracting the contents of the jar file

main

public static void main(java.lang.String[] args)

Extract the contents of a jar file.

Parameters:

args - An array of arguments. The first argument names the jar file to be extracted. The first argument is required. The second argument names the directory in which to extract the files from the jar file. The second argument is optional.

nameToFile

public static java.io.File nameToFile(java.lang.String name,
                                      java.net.URI base)

Given a file name or URL, construct a java.io.File object that refers to the file name or URL. This method first attempts to directly use the file name to construct the File. If the resulting File is a relative pathname, then it is resolved relative to the specified base URI, if there is one. If there is no such base URI, then it simply returns the relative File object. See the java.io.File documentation for a details about relative and absolute pathnames.

If the name begins with "xxxxxxCLASSPATHxxxxxx" or "$CLASSPATH" then search for the file relative to the classpath.

Note that "xxxxxxCLASSPATHxxxxxx" is the value of the globally defined constant $CLASSPATH available in the Ptolemy II expression language.

If the name begins with $CLASSPATH or "xxxxxxCLASSPATHxxxxxx" but that name cannot be found in the classpath, the value of the ptolemy.ptII.dir property is substituted in.

The file need not exist for this method to succeed. Thus, this method can be used to determine whether a file with a given name exists, prior to calling openForWriting(), for example.

This method is similar to nameToURL(String, URI, ClassLoader) except that in this method, the file or URL must be readable. Usually, this method is use for write a file and nameToURL(String, URI, ClassLoader) is used for reading.

Parameters:

name - The file name or URL.

base - The base for relative URLs.

Returns:

A File, or null if the filename argument is null or an empty string.

See Also:

nameToURL(String, URI, ClassLoader)

nameToURL

public static java.net.URL nameToURL(java.lang.String name,
                                     java.net.URI baseDirectory,
                                     java.lang.ClassLoader classLoader)
                              throws java.io.IOException

Given a file or URL name, return as a URL. If the file name is relative, then it is interpreted as being relative to the specified base directory. If the name begins with "xxxxxxCLASSPATHxxxxxx" or "$CLASSPATH" then search for the file relative to the classpath.

Note that "xxxxxxCLASSPATHxxxxxx" is the value of the globally defined constant $CLASSPATH available in the Ptolemy II expression language. II expression language.

If no file is found, then throw an exception.

This method is similar to nameToFile(String, URI) except that in this method, the file or URL must be readable. Usually, this method is use for reading a file and is used for writing nameToFile(String, URI).

Parameters:

name - The name of a file or URL.

baseDirectory - The base directory for relative file names, or null to specify none.

classLoader - The class loader to use to locate system resources, or null to use the system class loader that was used to load this class.

Returns:

A URL, or null if the name is null or the empty string.

Throws:

java.io.IOException - If the file cannot be read, or if the file cannot be represented as a URL (e.g. System.in), or the name specification cannot be parsed.

See Also:

nameToFile(String, URI)

openForReading

public static java.io.BufferedReader openForReading(java.lang.String name,
                                                    java.net.URI base,
                                                    java.lang.ClassLoader classLoader)
                                             throws java.io.IOException

Open the specified file for reading. If the specified name is "System.in", then a reader from standard in is returned. If the name begins with "$CLASSPATH" or "xxxxxxCLASSPATHxxxxxx", then the name is passed to nameToURL(String, URI, ClassLoader) If the file name is not absolute, the it is assumed to be relative to the specified base URI.

Parameters:

name - File name.

base - The base URI for relative references.

classLoader - The class loader to use to locate system resources, or null to use the system class loader that was used to load this class.

Returns:

If the name is null or the empty string, then null is returned, otherwise a buffered reader is returned.

Throws:

java.io.IOException - If the file cannot be opened.

See Also:

nameToURL(String, URI, ClassLoader)

openForWriting

public static java.io.Writer openForWriting(java.lang.String name,
                                            java.net.URI base,
                                            boolean append)
                                     throws java.io.IOException

Open the specified file for writing or appending. If the specified name is "System.out", then a writer to standard out is returned; otherwise, pass the name and base to nameToFile(String, URI) and create a file writer. If the file does not exist, then create it. If the file name is not absolute, the it is assumed to be relative to the specified base directory. If permitted, this method will return a Writer that will simply overwrite the contents of the file. It is up to the user of this method to check whether this is OK (by first calling nameToFile(String, URI) and calling exists() on the returned value).

Parameters:

name - File name.

base - The base URI for relative references.

append - If true, then append to the file rather than overwriting.

Returns:

If the name is null or the empty string, then null is returned, otherwise a writer is returned.

Throws:

java.io.IOException - If the file cannot be opened or created.

_binaryCopyStream

private static void _binaryCopyStream(java.io.InputStream inputStream,
                                      java.io.File destinationFile)
                               throws java.io.IOException

Copy files safely. If there are problems, the streams are close appropriately.

Parameters:

inputStream - The input stream.

destinationFile - The destination File.

Throws:

java.io.IOException - If the input stream cannot be created or read, or * if there is a problem writing to the destination file.

_binaryReadStream

private static byte[] _binaryReadStream(java.io.InputStream inputStream)
                                 throws java.io.IOException

Read a stream safely. If there are problems, the streams are close appropriately.

Parameters:

inputStream - The input stream.

Throws:

java.io.IOException - If the input stream cannot be read.

_searchClassPath

private static java.net.URL _searchClassPath(java.lang.String name,
                                             java.lang.ClassLoader classLoader)
                                      throws java.io.IOException

Search the classpath.

Parameters:

name - The name to be searched

classLoader - The class loader to use to locate system resources, or null to use the system class loader that was used to load this class.

Returns:

null if name does not start with "$CLASSPATH" or _CLASSPATH_VALUE or if name cannot be found.

Throws:

java.io.IOException

_trimClassPath

private static java.lang.String _trimClassPath(java.lang.String name)

Remove the value of _CLASSPATH_VALUE or "$CLASSPATH".