de.sciss.io
Class IOUtil

java.lang.Object
  de.sciss.io.IOUtil

public class IOUtil
extends java.lang.Object

This is a helper class containing utility static functions for common file operations.

Version:

0.32, 25-Feb-08

Author:

Hanns Holger Rutz

Field Summary

static java.lang.String

KEY_TEMPDIR Value: String representing the pathname of the temporary files directory.

Method Summary

static java.lang.String	abbreviate(java.lang.String fileName, int maxLen) Abbreviates a path name by replacing sub directories by an ellipsis character.
static void	createEmptyDirectory(java.io.File f) Creates a new empty directory.
static void	createEmptyFile(java.io.File f) Creates an empty file.
static java.io.File	createTempFile() Creates a new temporary file, using the preferred temp file folder (KEY_TEMPDIR).
static java.io.File	createTempFile(java.lang.String prefix, java.lang.String suffix) Create a new temporary file with specified prefix and suffix.
static void	deleteAll(java.io.File f) Deletes a file or directory.
static java.lang.String	getResourceString(java.lang.String key)
static java.util.prefs.Preferences	getUserPrefs()
static double	getVersion()
static java.io.IOException	map(java.lang.Exception e) Input/output methods sometimes contain methods from other java API that throw exceptions which are not subclasses of IOException.
static java.io.File	nonExistentFileVariant(java.io.File template, int insertPos, java.lang.String prefix, java.lang.String suffix) Iteratres a filename template as long as filenames generated by the template already exist.
static java.io.File	setFileSuffix(java.io.File f, java.lang.String ext) Sets the extension (suffix) of a file name.

Methods inherited from class java.lang.Object

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

Field Detail

KEY_TEMPDIR

public static final java.lang.String KEY_TEMPDIR

Value: String representing the pathname of the temporary files directory.
Has default value: yes!
Node: root

See Also:

Constant Field Values

Method Detail

getUserPrefs

public static final java.util.prefs.Preferences getUserPrefs()

getVersion

public static final double getVersion()

getResourceString

public static final java.lang.String getResourceString(java.lang.String key)

map

public static java.io.IOException map(java.lang.Exception e)

Input/output methods sometimes contain methods from other java API that throw exceptions which are not subclasses of IOException. The present a more consistent frontend to the caller of these methods, any exceptions can be simply mapped to IOException by creating a new IOException with the same message text as the original exception.

For example, in PrefsUtil's toXML method, BackingStoreExceptions and DOMExceptions are caught and rethrown:

  try {
      ...
  } catch( DOMException e1 ) {
      throw IOUtil.map( e1 );
  }
  

Parameters:

e - the original exception whose message is queries and copied to the returned exception.

Returns:

a newly created IOException with the message text and exception class name copied from the given original exception.

abbreviate

public static java.lang.String abbreviate(java.lang.String fileName,
                                          int maxLen)

Abbreviates a path name by replacing sub directories by an ellipsis character. This is used inside MenuFactory to shorten the pathnames attached to the Open-Recent menu.

Parameters:

fileName - the pathName to abbreviate

maxLen - maximum length of the Abbreviation. Beware: this method appends sub directories until maxLen is exceeded, therefore the returned String can well exceed maxLen!

Returns:

the abbreviated path name or the original path name if it was shorter or equal maxLen. It is guaranteed that the file name part of the path is fully included.

Todo:

BBEdit 7 has a nicer looking alternative: placing the filename in the beginning of the menu item line, followed by an abbreviated path.

createEmptyDirectory

public static void createEmptyDirectory(java.io.File f)
                                 throws java.io.IOException

Creates a new empty directory. If a file or directory of the specified name already exists it will be deleted.

Parameters:

f - pathname denoting the folder to create. this method will attempt to create nonexisting parent folders if required.

Throws:

java.io.IOException - is the directory cannot be created or emptied.

See Also:

deleteAll( File ), File.mkdirs()

createEmptyFile

public static void createEmptyFile(java.io.File f)
                            throws java.io.IOException

Creates an empty file. If file denoted by f already exists, it will be erased.

Parameters:

f - the file to be erased

Throws:

java.io.IOException - if an error occurs such as the file being protected or indicating an invalid path

createTempFile

public static java.io.File createTempFile()
                                   throws java.io.IOException

Creates a new temporary file, using the preferred temp file folder (KEY_TEMPDIR). The file will automatically deleted upon application exit.

Returns:

the newly created temp file, suitable for passing to a RandomAccessFile constructor or similar.

Throws:

java.io.IOException - if this method fails to create the file

See Also:

File.createTempFile( String, String, File ), File.deleteOnExit(), KEY_TEMPDIR

createTempFile

public static java.io.File createTempFile(java.lang.String prefix,
                                          java.lang.String suffix)
                                   throws java.io.IOException

Create a new temporary file with specified prefix and suffix. Suffix is allowed to be null in which case a default suffix (.tmp) is used.

Parameters:

prefix - string with which to filename shall begin, minimum three letters but as short as possible. might be truncated.

suffix - string with which to filename shall end (including the period if used as a file type suffix). might be truncated, but if it begins with a period, the following three letters are guaranteed to be preserved.

Returns:

the newly created temp file, suitable for passing to a RandomAccessFile constructor or similar.

Throws:

java.io.IOException - if this method fails to create the file

See Also:

File.createTempFile( String, String, File ), File.deleteOnExit(), KEY_TEMPDIR

deleteAll

public static void deleteAll(java.io.File f)
                      throws java.io.IOException

Deletes a file or directory. If the directory is not empty, all files and subfolders in the directory will be deleted recursively.

Parameters:

f - the path (file or folder) to delete

Throws:

java.io.IOException - if the deletion fails

See Also:

File.delete()

setFileSuffix

public static java.io.File setFileSuffix(java.io.File f,
                                         java.lang.String ext)

Sets the extension (suffix) of a file name. If the provided path has already a suffix, it is replaced. Otherwise, the new suffix will be appended.

Parameters:

f - the file whose suffix to change. can be null in which case null is returned

ext - the new suffix, e.g. ".aif", ".xml" etc. the leading period may be omitted. if ext is null, the suffix is removed.

Returns:

the newly composed file name or the original path, if path name didn't change

nonExistentFileVariant

public static java.io.File nonExistentFileVariant(java.io.File template,
                                                  int insertPos,
                                                  java.lang.String prefix,
                                                  java.lang.String suffix)

Iteratres a filename template as long as filenames generated by the template already exist. This method returns the template if a file denoted by the template does not exist.

Example: with template = new File( "/Users/schoko/myFile.aif" ), insertPos = -1 and prefix = " " (white space), the method will first check if file "/Users/schoko/myFile.aif" exists, if not that file will be returned. Next, it will check for the file "/Users/schoko/myFile 1.aif", then for "/Users/schoko/myFile 2.aif" etc.

Parameters:

template - template path

insertPos - the index in the name portion of the template at which variants are to be inserted; if insertPos is -1, the position of the period of the filetype suffix will be used (and if not found, the end of the template).

prefix - a string to paste before the inserted variant, can be null

suffix - a string to paste after the inserted variant, can be null