jmri.util
Class FileUtil

Show UML class diagram

java.lang.Object
  jmri.util.FileUtil

public class FileUtil
extends Object

Common utility methods for working with Files.

We needed a place to refactor common File-processing idioms in JMRI code, so this class was created. It's more of a library of procedures than a real class, as (so far) all of the operations have needed no state information.

Field Summary

static String	FILE Deprecated.
static String	HOME Portable reference to the user's home directory.
static String	PREFERENCES Portable reference to items in the JMRI user's preferences directory.
static String	PROGRAM Portable reference to items in the JMRI program directory.
static String	RESOURCE Deprecated.
static char	SEPARATOR The portable file path component separator.

Constructor Summary

FileUtil()

Method Summary

static void	createDirectory(String path) Create a directory if required.
static URL	fileToURL(File file) Return the URL for a given File.
static URL	findExternalFilename(String path) Get the URL of a portable filename if it can be located using findURL(java.lang.String)
static InputStream	findInputStream(String path) Search for a file or JAR resource by name and return the InputStream for that file.
static InputStream	findInputStream(String path, String... searchPaths) Search for a file or JAR resource by name and return the InputStream for that file.
static URL	findURL(String path) Search for a file or JAR resource by name and return the URL for that file.
static URL	findURL(String path, String... searchPaths) Search for a file or JAR resource by name and return the URL for that file.
static String	getAbsoluteFilename(String path) Convert a portable filename into an absolute filename
static String	getExternalFilename(String pName) Get the resource file corresponding to a name.
static String	getHomePath() Get the user's home directory.
static String	getPortableFilename(File file) Convert a File object to our preferred storage form.
static String	getPortableFilename(String filename) Convert a filename string to our preferred storage form.
static String	getPreferencesPath() Get the preferences directory.
static String	getProgramPath() Get the JMRI program directory.
static String	getScriptsPath() Get the path to the scripts directory.
static String	getUserFilesPath() Get the user's files directory.
static String	getUserResourcePath() Get the resources directory within the user's files directory.
static JarFile	jmriJarFile() Get the JMRI distribution jar file.
static void	logFilePaths()
static void	setProgramPath(File path) Set the JMRI program directory.
static void	setProgramPath(String path) Set the JMRI program directory.
static void	setScriptsPath(String path) Set the path to python scripts.
static void	setUserFilesPath(String path) Set the user's files directory.
static URI	urlToURI(URL url) Return the URI for a given URL

Methods inherited from class java.lang.Object

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

Field Detail

PROGRAM

public static final String PROGRAM

Portable reference to items in the JMRI program directory.

See Also:

Constant Field Values

PREFERENCES

public static final String PREFERENCES

Portable reference to items in the JMRI user's preferences directory.

See Also:

Constant Field Values

HOME

public static final String HOME

Portable reference to the user's home directory.

See Also:

Constant Field Values

RESOURCE

@Deprecated
public static final String RESOURCE

Deprecated.

Replaced with PROGRAM.

See Also:

PROGRAM, Constant Field Values

FILE

@Deprecated
public static final String FILE

Deprecated.

See Also:

Constant Field Values

SEPARATOR

public static final char SEPARATOR

The portable file path component separator.

See Also:

Constant Field Values

Constructor Detail

FileUtil

public FileUtil()

Method Detail

getExternalFilename

public static String getExternalFilename(String pName)

Get the resource file corresponding to a name. There are five cases:

• Starts with "resource:", treat the rest as a pathname relative to the program directory (deprecated; see "program:" below)
• Starts with "program:", treat the rest as a relative pathname below the program directory
• Starts with "preference:", treat the rest as a relative path below the preferences directory
• Starts with "home:", treat the rest as a relative path below the user.home directory
• Starts with "file:", treat the rest as a relative path below the resource directory in the preferences directory (deprecated; see "preference:" above)
• Otherwise, treat the name as a relative path below the program directory

In any case, absolute pathnames will work.

Parameters:

pName - The name string, possibly starting with program:, preference:, home:, file: or resource:

Returns:

Absolute or relative file name to use, or null.

Since:

2.7.2

getAbsoluteFilename

public static String getAbsoluteFilename(String path)

Convert a portable filename into an absolute filename

Parameters:

path -

Returns:

An absolute filename

getPortableFilename

public static String getPortableFilename(File file)

Convert a File object to our preferred storage form. This is the inverse of getExternalFilename(String pName). Deprecated forms are not created.

Parameters:

file - File to be represented

Since:

2.7.2

getPortableFilename

public static String getPortableFilename(String filename)

Convert a filename string to our preferred storage form. This is the inverse of getExternalFilename(String pName). Deprecated forms are not created.

Parameters:

filename - Filename to be represented

Since:

2.7.2

getHomePath

public static String getHomePath()

Get the user's home directory.

Returns:

User's home directory as a String

getUserFilesPath

public static String getUserFilesPath()

Get the user's files directory. If not set by the user, this is the same as the preferences path.

Returns:

User's files directory as a String

See Also:

getPreferencesPath()

setUserFilesPath

public static void setUserFilesPath(String path)

Set the user's files directory.

Parameters:

path - The path to the user's files directory

See Also:

getUserFilesPath()

getPreferencesPath

public static String getPreferencesPath()

Get the preferences directory. This directory is set based on the OS and is not normally settable by the user.

• On Microsoft Windows systems, this is JMRI in the User's home directory.
• On OS X systems, this is Library/Preferences/JMRI in the User's home directory.
• On Linux, Solaris, and othe UNIXes, this is .jmri in the User's home directory.
• This can be overridden with by setting the jmri.prefsdir Java property when starting JMRI.

Use getHomePath() to get the User's home directory.

Returns:

Path to the preferences directory.

See Also:

getHomePath()

getProgramPath

public static String getProgramPath()

Get the JMRI program directory.

Returns:

JMRI program directory as a String.

setProgramPath

public static void setProgramPath(String path)

Set the JMRI program directory. Convenience method that calls setProgramPath(java.io.File) with the passed in path.

Parameters:

path -

setProgramPath

public static void setProgramPath(File path)

Set the JMRI program directory. If set, allows JMRI to be loaded from locations other than the directory containing JMRI resources. This must be set very early in the process of loading JMRI (prior to loading any other JMRI code) to be meaningfully used.

Parameters:

path -

findExternalFilename

public static URL findExternalFilename(String path)

Get the URL of a portable filename if it can be located using findURL(java.lang.String)

Parameters:

path -

findInputStream

public static InputStream findInputStream(String path)

Search for a file or JAR resource by name and return the InputStream for that file. Search order is defined by findURL(java.lang.String, java.lang.String[]).

Parameters:

path - The relative path of the file or resource.

Returns:

InputStream or null.

See Also:

findInputStream(java.lang.String, java.lang.String[]), findURL(java.lang.String), findURL(java.lang.String, java.lang.String[])

findInputStream

public static InputStream findInputStream(String path,
                                          @NonNull
                                          String... searchPaths)

Search for a file or JAR resource by name and return the InputStream for that file. Search order is defined by findURL(java.lang.String, java.lang.String[]).

Parameters:

path - The relative path of the file or resource.

searchPaths - a list of paths to search for the path in

Returns:

InputStream or null.

See Also:

findInputStream(java.lang.String, java.lang.String[]), findURL(java.lang.String), findURL(java.lang.String, java.lang.String[])

getUserResourcePath

public static String getUserResourcePath()

Get the resources directory within the user's files directory.

Returns:

path to [user's file]/resources/

findURL

public static URL findURL(String path)

Search for a file or JAR resource by name and return the URL for that file. Search order is defined by findURL(java.lang.String, java.lang.String[]).

Parameters:

path - The relative path of the file or resource.

Returns:

The URL or null.

See Also:

findInputStream(java.lang.String), findInputStream(java.lang.String, java.lang.String[]), findURL(java.lang.String, java.lang.String[])

findURL

public static URL findURL(String path,
                          @NonNull
                          String... searchPaths)

Search for a file or JAR resource by name and return the URL for that file.

Search order is:

1. For any provided searchPaths, iterate over the searchPaths by prepending each searchPath to the path and following the following search order:
1. As a File in the user preferences directory
2. As a File in the current working directory (usually, but not always the JMRI distribution directory)
3. As a File in the JMRI distribution directory
4. As a resource in jmri.jar
2. If the file or resource has not been found in the searchPaths, search in the four locations listed without prepending any path

Parameters:

path - The relative path of the file or resource

searchPaths - a list of paths to search for the path in

Returns:

The URL or null

See Also:

findInputStream(java.lang.String), findInputStream(java.lang.String, java.lang.String[]), findURL(java.lang.String)

urlToURI

public static URI urlToURI(URL url)

Return the URI for a given URL

Parameters:

url -

Returns:

a URI or null if the conversion would have caused a URISyntaxException

fileToURL

public static URL fileToURL(File file)

Return the URL for a given File. This method catches a MalformedURLException and returns null in its place, since we really do not expect a File object to ever give a malformed URL. This method exists solely so implementing classes do not need to catch that exception.

Parameters:

file - The File to convert.

Returns:

a URL or null if the conversion would have caused a MalformedURLException

jmriJarFile

public static JarFile jmriJarFile()

Get the JMRI distribution jar file.

Returns:

a JarFile pointing to jmri.jar or null

logFilePaths

public static void logFilePaths()

getScriptsPath

public static String getScriptsPath()

Get the path to the scripts directory.

Returns:

the scriptsPath

setScriptsPath

public static void setScriptsPath(String path)

Set the path to python scripts.

Parameters:

path - the scriptsPath to set

createDirectory

public static void createDirectory(String path)

Create a directory if required. Any parent directories will also be created.

Parameters:

path -