org.scijava.util

Class FileUtils

java.lang.Object

org.scijava.util.FileUtils

public final class FileUtils
extends Object

Useful methods for working with file paths.

Author:

Johannes Schindelin, Curtis Rueden, Grant Harris

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_SHORTENER_THRESHOLD
static String	SHORTENER_BACKSLASH
static String	SHORTENER_BACKSLASH_REGEX
static String	SHORTENER_ELLIPSE
static String	SHORTENER_SLASH
static String	SHORTENER_SLASH_REGEX

Method Summary

Modifier and Type	Method and Description
static Collection<URL>	appendContents(Collection<URL> result, URL directory) Recursively adds contents from the referenced directory to an existing collection.
static Collection<URL>	appendContents(Collection<URL> result, URL directory, boolean recurse, boolean filesOnly) Add contents from the referenced directory to an existing collection.
static File	createTemporaryDirectory(String prefix, String suffix) Creates a temporary directory.
static File	createTemporaryDirectory(String prefix, String suffix, File directory) Creates a temporary directory.
static boolean	deleteRecursively(File directory) Deletes a directory recursively.
static Map<String,URL>	findResources(String regex, Iterable<URL> urls) Finds URLs of resources known to the system.
static Map<String,URL>	findResources(String regex, String pathPrefix, File baseDirectory) Finds URLs of available resources.
static File[]	getAllVersions(File directory, String filename) Lists all versions of a given (possibly versioned) file name.
static String	getExtension(File file) Extracts the file extension from a file.
static String	getExtension(String path) Extracts the file extension from a file path.
static Date	getModifiedTime(File file) Gets the Date of the file's last modification.
static String	getPath(File file) Gets the absolute path to the given file, with the directory separator standardized to forward slash, like most platforms use.
static String	getPath(String path, String separator) Gets a standardized path based on the given one, with the directory separator standardized from the specific separator to forward slash, like most platforms use.
static String	limitPath(String path, int limit) Compacts a path into a given number of characters.
static Collection<URL>	listContents(URL directory) Recursively lists the contents of the referenced directory.
static Collection<URL>	listContents(URL directory, boolean recurse, boolean filesOnly) Lists all contents of the referenced directory.
static Matcher	matchVersionedFilename(String filename) Deprecated. see stripFilenameVersion(String)
static byte[]	readFile(File file) Reads the contents of the given file into a new byte array.
static String	shortenPath(String path) Shortens the path to a maximum of 4 path elements.
static String	shortenPath(String path, int threshold) Shortens the path based on the given maximum number of path elements.
static String	stripFilenameVersion(String filename)
static File	urlToFile(String url) Converts the given URL string to its corresponding File.
static File	urlToFile(URL url) Converts the given URL to its corresponding File.
static void	writeFile(File file, byte[] bytes) Writes the given byte array to the specified file.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_SHORTENER_THRESHOLD

public static final int DEFAULT_SHORTENER_THRESHOLD

See Also:

Constant Field Values

SHORTENER_BACKSLASH_REGEX

public static final String SHORTENER_BACKSLASH_REGEX

See Also:

Constant Field Values

SHORTENER_SLASH_REGEX

public static final String SHORTENER_SLASH_REGEX

See Also:

Constant Field Values

SHORTENER_BACKSLASH

public static final String SHORTENER_BACKSLASH

See Also:

Constant Field Values

SHORTENER_SLASH

public static final String SHORTENER_SLASH

See Also:

Constant Field Values

SHORTENER_ELLIPSE

public static final String SHORTENER_ELLIPSE

See Also:

Constant Field Values

Method Detail

getPath

public static String getPath(File file)

Gets the absolute path to the given file, with the directory separator standardized to forward slash, like most platforms use.

Parameters:

file - The file whose path will be obtained and standardized.

Returns:

The file's standardized absolute path.

getPath

public static String getPath(String path,
                             String separator)

Gets a standardized path based on the given one, with the directory separator standardized from the specific separator to forward slash, like most platforms use.

Parameters:

path - The path to standardize.

separator - The directory separator to be standardized.

Returns:

The standardized path.

getExtension

public static String getExtension(File file)

Extracts the file extension from a file.

Parameters:

file - the file object

Returns:

the file extension (excluding the dot), or the empty string when the file name does not contain dots

getExtension

public static String getExtension(String path)

Extracts the file extension from a file path.

Parameters:

path - the path to the file (relative or absolute)

Returns:

the file extension (excluding the dot), or the empty string when the file name does not contain dots

getModifiedTime

public static Date getModifiedTime(File file)

Gets the Date of the file's last modification.

readFile

public static byte[] readFile(File file)
                       throws IOException

Reads the contents of the given file into a new byte array.

Throws:

IOException - If the file cannot be read.

See Also:

To convert a byte array to a string.

writeFile

public static void writeFile(File file,
                             byte[] bytes)
                      throws IOException

Writes the given byte array to the specified file.

Throws:

IOException - If the file cannot be written.

See Also:

To convert a string to a byte array.

stripFilenameVersion

public static String stripFilenameVersion(String filename)

getAllVersions

public static File[] getAllVersions(File directory,
                                    String filename)

Lists all versions of a given (possibly versioned) file name.

Parameters:

directory - the directory to scan

filename - the file name to use

Returns:

the list of matches

urlToFile

public static File urlToFile(URL url)

Converts the given URL to its corresponding File.

This method is similar to calling new File(url.toURI()) except that it also handles "jar:file:" URLs, returning the path to the JAR file.

Parameters:

url - The URL to convert.

Returns:

A file path suitable for use with e.g. FileInputStream

Throws:

IllegalArgumentException - if the URL does not correspond to a file.

urlToFile

public static File urlToFile(String url)

Converts the given URL string to its corresponding File.

Parameters:

url - The URL to convert.

Returns:

A file path suitable for use with e.g. FileInputStream

Throws:

IllegalArgumentException - if the URL does not correspond to a file.

shortenPath

public static String shortenPath(String path)

Shortens the path to a maximum of 4 path elements.

Parameters:

path - the path to the file (relative or absolute)

Returns:

shortened path

shortenPath

public static String shortenPath(String path,
                                 int threshold)

Shortens the path based on the given maximum number of path elements. E.g., "C:/1/2/test.txt" returns "C:/1/.../test.txt" if threshold is 1.

Parameters:

path - the path to the file (relative or absolute)

threshold - the number of directories to keep unshortened

Returns:

shortened path

limitPath

public static String limitPath(String path,
                               int limit)

Compacts a path into a given number of characters. The result is similar to the Win32 API PathCompactPathExA.

Parameters:

path - the path to the file (relative or absolute)

limit - the number of characters to which the path should be limited

Returns:

shortened path

createTemporaryDirectory

public static File createTemporaryDirectory(String prefix,
                                            String suffix)
                                     throws IOException

Creates a temporary directory.

Since there is no atomic operation to do that, we create a temporary file, delete it and create a directory in its place. To avoid race conditions, we use the optimistic approach: if the directory cannot be created, we try to obtain a new temporary file rather than erroring out.

It is the caller's responsibility to make sure that the directory is deleted; see deleteRecursively(File).

Parameters:

prefix - The prefix string to be used in generating the file's name; see File.createTempFile(String, String, File)

suffix - The suffix string to be used in generating the file's name; see File.createTempFile(String, String, File)

Returns:

An abstract pathname denoting a newly-created empty directory

Throws:

IOException

createTemporaryDirectory

public static File createTemporaryDirectory(String prefix,
                                            String suffix,
                                            File directory)
                                     throws IOException

Creates a temporary directory.

Since there is no atomic operation to do that, we create a temporary file, delete it and create a directory in its place. To avoid race conditions, we use the optimistic approach: if the directory cannot be created, we try to obtain a new temporary file rather than erroring out.

It is the caller's responsibility to make sure that the directory is deleted; see deleteRecursively(File).

Parameters:

prefix - The prefix string to be used in generating the file's name; see File.createTempFile(String, String, File)

suffix - The suffix string to be used in generating the file's name; see File.createTempFile(String, String, File)

directory - The directory in which the file is to be created, or null if the default temporary-file directory is to be used

Throws:

IOException

deleteRecursively

public static boolean deleteRecursively(File directory)

Deletes a directory recursively.

Parameters:

directory - The directory to delete.

Returns:

whether it succeeded (see also File.delete())

listContents

public static Collection<URL> listContents(URL directory)

Recursively lists the contents of the referenced directory. Directories are excluded from the result. Supported protocols include file and jar.

Parameters:

directory - The directory whose contents should be listed.

Returns:

A collection of URLs representing the directory's contents.

See Also:

listContents(URL, boolean, boolean)

listContents

public static Collection<URL> listContents(URL directory,
                                           boolean recurse,
                                           boolean filesOnly)

Lists all contents of the referenced directory. Supported protocols include file and jar.

Parameters:

directory - The directory whose contents should be listed.

recurse - Whether to list contents recursively, as opposed to only the directory's direct contents.

filesOnly - Whether to exclude directories in the resulting collection of contents.

Returns:

A collection of URLs representing the directory's contents.

appendContents

public static Collection<URL> appendContents(Collection<URL> result,
                                             URL directory)

Recursively adds contents from the referenced directory to an existing collection. Directories are excluded from the result. Supported protocols include file and jar.

Parameters:

result - The collection to which contents should be added.

directory - The directory whose contents should be listed.

Returns:

A collection of URLs representing the directory's contents.

See Also:

appendContents(Collection, URL, boolean, boolean)

appendContents

public static Collection<URL> appendContents(Collection<URL> result,
                                             URL directory,
                                             boolean recurse,
                                             boolean filesOnly)

Add contents from the referenced directory to an existing collection. Supported protocols include file and jar.

Parameters:

result - The collection to which contents should be added.

directory - The directory whose contents should be listed.

recurse - Whether to append contents recursively, as opposed to only the directory's direct contents.

filesOnly - Whether to exclude directories in the resulting collection of contents.

Returns:

A collection of URLs representing the directory's contents.

findResources

public static Map<String,URL> findResources(String regex,
                                            String pathPrefix,
                                            File baseDirectory)

Finds URLs of available resources. Both JAR files and files on disk are searched, according to the following mechanism:

1. Resources at the given pathPrefix are discovered using ClassLoader.getResources(String) with the current thread's context class loader. In particular, this invocation discovers resources in JAR files beneath the given pathPrefix.
2. The directory named pathPrefix beneath the given baseDirectory is scanned last, so that users can more easily override resources provided inside JAR files by placing a resource of the same name within that directory.

In both cases, resources are then recursively scanned using listContents(URL), and anything matching the given regex pattern is added to the output map.

Parameters:

regex - The regex to use when matching resources, or null to match everything.

pathPrefix - The path to search for resources.

baseDirectory - The baseDirectory/pathPrefix directory to scan after the URL resources.

Returns:

A map of URLs referencing the matched resources.

See Also:

AppUtils.getBaseDirectory(java.lang.String, java.lang.Class<?>, java.lang.String)

findResources

public static Map<String,URL> findResources(String regex,
                                            Iterable<URL> urls)

Finds URLs of resources known to the system.

Each of the given URLs is recursively scanned using listContents(URL), and anything matching the given regex pattern is added to the output map.

Parameters:

regex - The regex to use when matching resources, or null to match everything.

urls - Paths to search for resources.

Returns:

A map of URLs referencing the matched resources.

matchVersionedFilename

@Deprecated
public static Matcher matchVersionedFilename(String filename)

Deprecated. see stripFilenameVersion(String)

Returns the Matcher object dissecting a versioned file name.

Parameters:

filename - the file name

Returns:

the Matcher object