Package jmri.util

Class FileUtil

java.lang.Object

jmri.util.FileUtil

public final class FileUtil
extends Object

Common utility methods for working with Files.

All methods in this class call the identical method from the default instance of FileUtilSupport.

See Also:

• FileUtilSupport

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	FileUtil.Location	The types of locations to use when falling back on default locations in findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...).
static class	FileUtil.Property	PropertyChangeEvents for properties that are Profile-specific use a Property to enclose both the Profile and the value of the property.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	HOME	Portable reference to the user's home directory.
static final String	PREFERENCES	Portable reference to the JMRI user's files and preferences directory.
static final String	PROFILE	Portable reference to the current profile directory.
static final String	PROGRAM	Portable reference to items in the JMRI program directory.
static final String	SCRIPTS	Portable reference to the current scripts directory.
static final char	SEPARATOR	The portable file path component separator.
static final String	SETTINGS	Portable reference to the JMRI applications preferences directory.

Method Summary

Modifier and Type	Method	Description
static void	appendTextToFile(File file, String text)	Simple helper method to just append a text string to the end of the given filename.
static void	backup(File file)	Backup a file.
static void	copy(File source, File dest)	Copy a file or directory.
static void	createDirectory(File dir)	Create a directory if required.
static void	createDirectory(String path)	Create a directory if required.
static boolean	delete(File path)	Recursively delete a path.
static URL	fileToURL(File file)	Return the URL for a given File.
static URI	findExternalFilename(String path)	Get the URL of a portable filename if it can be located using findURL(java.lang.String)
static Set<File>	findFiles(String name, String root)	Find all files matching the given name under the given root directory within both the user and installed file locations.
static Set<File>	findFiles(String name, String root, FileUtil.Location location)	Find all files matching the given name under the given root directory within the specified location.
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 InputStream	findInputStream(String path, FileUtil.Location locations)	Search for a file or JAR resource by name and return the InputStream for that file.
static InputStream	findInputStream(String path, FileUtil.Location locations, String... searchPaths)	Search for a file or JAR resource by name and return the InputStream for that file.
static URI	findURI(String path)	Search for a file or JAR resource by name and return the URI for that file.
static URI	findURI(String path, String... searchPaths)	Search for a file or JAR resource by name and return the URI for that file.
static URI	findURI(String path, FileUtil.Location locations)	Search for a file or JAR resource by name and return the URI for that file.
static URI	findURI(String path, FileUtil.Location locations, String... searchPaths)	Search for a file or JAR resource by name and return the URI 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 URL	findURL(String path, FileUtil.Location locations)	Search for a file or JAR resource by name and return the URL for that file.
static URL	findURL(String path, FileUtil.Location locations, 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, using ProfileManager.getActiveProfile() as the base.
static String	getAbsoluteFilename(Profile profile, String path)	Convert a portable filename into an absolute filename.
static FileUtilSupport	getDefault()	Get the default instance of FileUtilSupport.
static String	getExternalFilename(String pName)	Get the resource file corresponding to a name.
static String	getExternalFilename(Profile profile, String pName)	Get the resource file corresponding to a name.
static File	getFile(String path)	Get the File that path refers to.
static File	getFile(Profile profile, String path)	Get the File that path refers to.
static String	getHomePath()	Get the user's home directory.
static String	getPortableFilename(File file)	Convert a File object's path to our preferred storage form.
static String	getPortableFilename(File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)	Convert a File object's path to our preferred storage form.
static String	getPortableFilename(String filename)	Convert a filename string to our preferred storage form.
static String	getPortableFilename(String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)	Convert a filename string to our preferred storage form.
static String	getPortableFilename(Profile profile, File file)	Convert a File object's path to our preferred storage form.
static String	getPortableFilename(Profile profile, File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)	Convert a File object's path to our preferred storage form.
static String	getPortableFilename(Profile profile, String filename)	Convert a filename string to our preferred storage form.
static String	getPortableFilename(Profile profile, String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)	Convert a filename string to our preferred storage form.
static String	getPreferencesPath()	Get the preferences directory.
static String	getProfilePath()	Get the profile directory.
static String	getProfilePath(Profile profile)	Get the profile directory.
static String	getProgramPath()	Get the JMRI program directory.
static String	getScriptsPath()	Get the path to the scripts directory using the Profile returned by ProfileManager.getActiveProfile() as the base.
static String	getScriptsPath(Profile profile)	Get the path to the scripts directory.
static URI	getURI(String path)	Get the File that path refers to.
static URL	getURL(String path)	Get the URL that path refers to.
static URL	getURL(URI uri)	Convenience method to get the URL from a URI.
static String	getUserFilesPath()	Get the user's files directory.
static String	getUserFilesPath(Profile profile)	Get the user's files directory.
static String	getUserResourcePath()	Get the resources directory within the user's files directory.
static boolean	isPortableFilename(String filename)	Test if the given filename is a portable filename.
static JarFile	jmriJarFile()	Get the JMRI distribution jar file.
static void	logFilePaths()	Log all paths at the INFO level.
static String	readFile(File file)	Read a text file into a String.
static String	readURL(URL url)	Read a text URL into a String.
static void	rotate(File file, int max, String extension)	Rotate a file and its backups, retaining only a set number of backups.
static String	sanitizeFilename(String name)	Replaces most non-alphanumeric characters in name with an underscore.
static void	setProgramPath(File path)	Set the JMRI program directory.
static void	setProgramPath(String path)	Set the JMRI program directory.
static void	setScriptsPath(Profile profile, String path)	Set the path to python scripts.
static void	setUserFilesPath(Profile profile, 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 Details

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 the JMRI user's files and preferences directory.

See Also:

• Constant Field Values

SETTINGS

public static final String SETTINGS

Portable reference to the JMRI applications 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

PROFILE

public static final String PROFILE

Portable reference to the current profile directory.

See Also:

• Constant Field Values

SCRIPTS

public static final String SCRIPTS

Portable reference to the current scripts directory.

See Also:

• Constant Field Values

SEPARATOR

public static final char SEPARATOR

The portable file path component separator.

See Also:

• Constant Field Values

Method Details

getFile

@Nonnull
@CheckReturnValue
public static File getFile(@Nonnull
 String path)
                    throws FileNotFoundException

Get the File that path refers to. Throws a FileNotFoundException if the file cannot be found instead of returning null (as File would). Use getURI(java.lang.String) or getURL(java.lang.String) instead of this method if possible.

Parameters:

path - the path to find

Returns:

File at path

Throws:

FileNotFoundException - if path cannot be found

See Also:

• getURI(java.lang.String)
• getURL(java.lang.String)

getFile

@Nonnull
@CheckReturnValue
public static File getFile(@CheckForNull
 Profile profile,
 @Nonnull
 String path)
                    throws FileNotFoundException

Get the File that path refers to. Throws a FileNotFoundException if the file cannot be found instead of returning null (as File would). Use getURI(java.lang.String) or getURL(java.lang.String) instead of this method if possible.

Parameters:

profile - the profile to use as a base

path - the path to find

Returns:

File at path

Throws:

FileNotFoundException - if path cannot be found

See Also:

• getURI(java.lang.String)
• getURL(java.lang.String)

getURI

@Nonnull
@CheckReturnValue
public static URI getURI(@Nonnull
 String path)
                  throws FileNotFoundException

Get the File that path refers to. Throws a FileNotFoundException if the file cannot be found instead of returning null (as File would).

Parameters:

path - the path to find

Returns:

File at path

Throws:

FileNotFoundException - if path cannot be found

See Also:

• getFile(java.lang.String)
• getURL(java.lang.String)

getURL

@Nonnull
@CheckReturnValue
public static URL getURL(@Nonnull
 String path)
                  throws FileNotFoundException

Get the URL that path refers to. Throws a FileNotFoundException if the URL cannot be found instead of returning null.

Parameters:

path - the path to find

Returns:

URL at path

Throws:

FileNotFoundException - if path cannot be found

See Also:

• getFile(java.lang.String)
• getURI(java.lang.String)

getURL

@CheckForNull
@CheckReturnValue
public static URL getURL(@Nonnull
 URI uri)

Convenience method to get the URL from a URI. Logs errors and returns null if any exceptions are thrown by the conversion.

Parameters:

uri - The URI to convert.

Returns:

URL or null if any errors exist.

findFiles

@Nonnull
@CheckReturnValue
public static Set<File> findFiles(@Nonnull
 String name,
 @Nonnull
 String root)
                           throws IllegalArgumentException

Find all files matching the given name under the given root directory within both the user and installed file locations.

Parameters:

name - the name of the file to find

root - the relative path to a directory in either or both of the user or installed file locations; use a single period character to refer to the root of the user or installed file locations

Returns:

a set of found files or an empty set if no matching files were found

Throws:

IllegalArgumentException - if the name is not a relative path, is empty, or contains path separators; or if the root is not a relative path, is empty, or contains a parent directory (..)

NullPointerException - if any parameter is null

findFiles

@Nonnull
@CheckReturnValue
public static Set<File> findFiles(@Nonnull
 String name,
 @Nonnull
 String root,
 @Nonnull
 FileUtil.Location location)

Find all files matching the given name under the given root directory within the specified location.

Parameters:

name - the name of the file to find

root - the relative path to a directory in either or both of the user or installed file locations; use a single period character to refer to the root of the location

location - the location to search within

Returns:

a set of found files or an empty set if no matching files were found

Throws:

IllegalArgumentException - if the name is not a relative path, is empty, or contains path separators; if the root is not a relative path, is empty, or contains a parent directory (..); or if the location is FileUtil.Location.NONE

NullPointerException - if any parameter is null

getExternalFilename

@Nonnull
@CheckReturnValue
public static String getExternalFilename(@Nonnull
 String pName)

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

• 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 user's files directory
• Starts with "settings:", treat the rest as a relative path below the JMRI system preferences directory
• Starts with "home:", treat the rest as a relative path below the user.home directory
• Starts with "profile:", treat the rest as a relative path below the profile directory as specified in the activeProfile
• Starts with "scripts:", treat the rest as a relative path below the scripts directory
• Otherwise, treat the name as a relative path below the program directory

In any case, absolute pathnames will work. Uses the Profile returned by ProfileManager.getActiveProfile() as the base.

Parameters:

pName - the name, possibly starting with home:, profile:, program:, preference:, scripts:, or settings:

Returns:

Absolute file name to use, or null. This will include system-specific file separators.

Since:

2.7.2

getExternalFilename

@Nonnull
@CheckReturnValue
public static String getExternalFilename(@CheckForNull
 Profile profile,
 @Nonnull
 String pName)

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

• 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 user's files directory
• Starts with "settings:", treat the rest as a relative path below the JMRI system preferences directory
• Starts with "home:", treat the rest as a relative path below the user.home directory
• Starts with "profile:", treat the rest as a relative path below the profile directory as specified in the activeProfile
• Starts with "scripts:", treat the rest as a relative path below the scripts directory
• Otherwise, treat the name as a relative path below the program directory

In any case, absolute pathnames will work.

Parameters:

profile - the Profile to use as a base.

pName - the name, possibly starting with home:, profile:, program:, preference:, scripts:, or settings:

Returns:

Absolute file name to use, or null. This will include system-specific file separators.

Since:

4.17.3

getAbsoluteFilename

@Nonnull
@CheckReturnValue
public static String getAbsoluteFilename(@Nonnull
 String path)

Convert a portable filename into an absolute filename, using ProfileManager.getActiveProfile() as the base.

Parameters:

path - the portable filename

Returns:

An absolute filename

getAbsoluteFilename

@Nonnull
@CheckReturnValue
public static String getAbsoluteFilename(@CheckForNull
 Profile profile,
 @Nonnull
 String path)

Convert a portable filename into an absolute filename.

Parameters:

profile - the profile to use the base

path - the portable filename

Returns:

An absolute filename

getPortableFilename

@Nonnull
@CheckReturnValue
public static String getPortableFilename(@Nonnull
 File file)

Convert a File object's path to our preferred storage form.

This is the inverse of getFile(String pName). Deprecated forms are not created.

Parameters:

file - File at path to be represented

Returns:

Filename for storage in a portable manner. This will include portable, not system-specific, file separators.

Since:

2.7.2

getPortableFilename

@Nonnull
@CheckReturnValue
public static String getPortableFilename(@Nonnull
 File file,
 boolean ignoreUserFilesPath,
 boolean ignoreProfilePath)

Convert a File object's path to our preferred storage form.

This is the inverse of getFile(String pName). Deprecated forms are not created.

This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the ProfileManager to write an incorrect path for the current profile or FileLocationPaneXml to write an incorrect path for the Users file directory. In most cases, the use of getPortableFilename(java.io.File) is preferable.

Parameters:

file - File at path to be represented

ignoreUserFilesPath - true if paths in the User files path should be stored as absolute paths, which is often not desirable.

ignoreProfilePath - true if paths in the profile should be stored as absolute paths, which is often not desirable.

Returns:

Storage format representation

Since:

3.5.5

getPortableFilename

@Nonnull
@CheckReturnValue
public static String getPortableFilename(@Nonnull
 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

Returns:

Filename for storage in a portable manner

Since:

2.7.2

getPortableFilename

@Nonnull
@CheckReturnValue
public static String getPortableFilename(@Nonnull
 String filename,
 boolean ignoreUserFilesPath,
 boolean ignoreProfilePath)

Convert a filename string to our preferred storage form.

This is the inverse of getExternalFilename(String pName). Deprecated forms are not created.

This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the ProfileManager to write an incorrect path for the current profile or FileLocationPaneXml to write an incorrect path for the Users file directory. In most cases, the use of getPortableFilename(java.io.File) is preferable.

Parameters:

filename - Filename to be represented

ignoreUserFilesPath - true if paths in the User files path should be stored as absolute paths, which is often not desirable.

ignoreProfilePath - true if paths in the profile path should be stored as absolute paths, which is often not desirable.

Returns:

Storage format representation

Since:

3.5.5

getPortableFilename

@Nonnull
@CheckReturnValue
public static String getPortableFilename(@CheckForNull
 Profile profile,
 @Nonnull
 File file)

Convert a File object's path to our preferred storage form.

This is the inverse of getFile(String pName). Deprecated forms are not created.

Parameters:

profile - Profile to use as a base

file - File at path to be represented

Returns:

Filename for storage in a portable manner. This will include portable, not system-specific, file separators.

Since:

4.17.3

getPortableFilename

@Nonnull
@CheckReturnValue
public static String getPortableFilename(@CheckForNull
 Profile profile,
 @Nonnull
 File file,
 boolean ignoreUserFilesPath,
 boolean ignoreProfilePath)

Convert a File object's path to our preferred storage form.

This is the inverse of getFile(String pName). Deprecated forms are not created.

This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the ProfileManager to write an incorrect path for the current profile or FileLocationPaneXml to write an incorrect path for the Users file directory. In most cases, the use of getPortableFilename(java.io.File) is preferable.

Parameters:

profile - Profile to use as a base

file - File at path to be represented

ignoreUserFilesPath - true if paths in the User files path should be stored as absolute paths, which is often not desirable.

ignoreProfilePath - true if paths in the profile should be stored as absolute paths, which is often not desirable.

Returns:

Storage format representation

Since:

4.17.3

getPortableFilename

@Nonnull
@CheckReturnValue
public static String getPortableFilename(@CheckForNull
 Profile profile,
 @Nonnull
 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:

profile - the Profile to use as a base

filename - Filename to be represented

Returns:

Filename for storage in a portable manner

Since:

4.17.3

getPortableFilename

@Nonnull
@CheckReturnValue
public static String getPortableFilename(@CheckForNull
 Profile profile,
 @Nonnull
 String filename,
 boolean ignoreUserFilesPath,
 boolean ignoreProfilePath)

Convert a filename string to our preferred storage form.

This is the inverse of getExternalFilename(String pName). Deprecated forms are not created.

This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the ProfileManager to write an incorrect path for the current profile or FileLocationPaneXml to write an incorrect path for the Users file directory. In most cases, the use of getPortableFilename(java.io.File) is preferable.

Parameters:

profile - the profile to use as a base

filename - Filename to be represented

ignoreUserFilesPath - true if paths in the User files path should be stored as absolute paths, which is often not desirable.

ignoreProfilePath - true if paths in the profile path should be stored as absolute paths, which is often not desirable.

Returns:

Storage format representation

Since:

4.17.3

isPortableFilename

public static boolean isPortableFilename(@Nonnull
 String filename)

Test if the given filename is a portable filename.

Parameters:

filename - the name to test

Returns:

true if filename is portable

getHomePath

@Nonnull
@CheckReturnValue
public static String getHomePath()

Get the user's home directory.

Returns:

User's home directory as a String

getUserFilesPath

@Nonnull
@CheckReturnValue
public static String getUserFilesPath()

Get the user's files directory. If not set by the user, this is the same as the profile path for the Profile specified by ProfileManager.getActiveProfile().

Returns:

User's files directory as a String

See Also:

• getProfilePath()

getUserFilesPath

@Nonnull
@CheckReturnValue
public static String getUserFilesPath(@CheckForNull
 Profile profile)

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

Parameters:

profile - the profile to use as a base

Returns:

User's files directory as a String

See Also:

• getProfilePath()

setUserFilesPath

public static void setUserFilesPath(@CheckForNull
 Profile profile,
 @Nonnull
 String path)

Set the user's files directory.

Parameters:

profile - The profile to use as a base

path - The path to the user's files directory

See Also:

• getUserFilesPath()

getProfilePath

@Nonnull
@CheckReturnValue
public static String getProfilePath()

Get the profile directory. Uses the Profile returned by ProfileManager.getActiveProfile() as a base. If that is null, gets the preferences path.

Returns:

Profile directory

See Also:

• getPreferencesPath()

getProfilePath

@Nonnull
@CheckReturnValue
public static String getProfilePath(@CheckForNull
 Profile profile)

Get the profile directory. If the profile is null or has a null directory, this is the same as the preferences path.

Parameters:

profile - the profile to use as a base

Returns:

Profile directory

See Also:

• getPreferencesPath()

getPreferencesPath

@Nonnull
@CheckReturnValue
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 other 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

@Nonnull
@CheckReturnValue
public static String getProgramPath()

Get the JMRI program directory. If the program directory has not been previously sets, first sets the program directory to the value specified in the Java System property jmri.path.program, or . if that property is not set.

Returns:

JMRI program directory as a String.

setProgramPath

public static void setProgramPath(@Nonnull
 String path)

Set the JMRI program directory.

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

Parameters:

path - the path to the JMRI installation

setProgramPath

public static void setProgramPath(@Nonnull
 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 - the path to the JMRI installation

findExternalFilename

@Nonnull
@CheckReturnValue
public static URI findExternalFilename(@Nonnull
 String path)

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

Parameters:

path - the path to find

Returns:

URL of portable or absolute path

findInputStream

public static InputStream findInputStream(@Nonnull
 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, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.

Parameters:

path - The relative path of the file or resource

Returns:

InputStream or null.

See Also:

• findInputStream(java.lang.String, java.lang.String...)
• findInputStream(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
• findURL(java.lang.String)
• findURL(java.lang.String, java.lang.String...)
• findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)

findInputStream

public static InputStream findInputStream(@Nonnull
 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, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.

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)
• findInputStream(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)

findInputStream

public static InputStream findInputStream(@Nonnull
 String path,
 FileUtil.Location locations)

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, jmri.util.FileUtil.Location, java.lang.String...).

Parameters:

path - The relative path of the file or resource

locations - The type of locations to limit the search to

Returns:

InputStream or null.

See Also:

• findInputStream(java.lang.String)
• findInputStream(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)

findInputStream

public static InputStream findInputStream(@Nonnull
 String path,
 FileUtil.Location locations,
 @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, jmri.util.FileUtil.Location, java.lang.String...).

Parameters:

path - The relative path of the file or resource

locations - The type of locations to limit the search to

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

Returns:

InputStream or null.

See Also:

• findInputStream(java.lang.String)
• findInputStream(java.lang.String, java.lang.String...)

getUserResourcePath

@Nonnull
@CheckReturnValue
public static String getUserResourcePath()

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

Returns:

path to [user's file]/resources/

findURI

public static URI findURI(@Nonnull
 String path)

Search for a file or JAR resource by name and return the URI for that file. Search order is defined by findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.

Parameters:

path - The relative path of the file or resource.

Returns:

The URI or null.

See Also:

• findURI(java.lang.String, java.lang.String...)
• findURI(java.lang.String, jmri.util.FileUtil.Location)
• findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)

findURI

public static URI findURI(@Nonnull
 String path,
 @Nonnull
 String... searchPaths)

Search for a file or JAR resource by name and return the URI for that file. Search order is defined by findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.

Note that if the file for path is not found in one of the searchPaths, all standard locations are also be searched through to find the file. If you need to limit the locations where the file can be found use findURI(java.lang.String, jmri.util.FileUtil.Location, 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:

The URI or null

See Also:

• findURI(java.lang.String)
• findURI(java.lang.String, jmri.util.FileUtil.Location)
• findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)

findURI

public static URI findURI(@Nonnull
 String path,
 @Nonnull
 FileUtil.Location locations)

Search for a file or JAR resource by name and return the URI for that file. Search order is defined by findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...).

Parameters:

path - The relative path of the file or resource

locations - The types of locations to limit the search to

Returns:

The URI or null

See Also:

• findURI(java.lang.String)
• findURI(java.lang.String, java.lang.String...)
• findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)

findURI

public static URI findURI(@Nonnull
 String path,
 @Nonnull
 FileUtil.Location locations,
 @Nonnull
 String... searchPaths)

Search for a file or JAR resource by name and return the URI 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
3. As a File with an absolute path

The locations parameter limits the above logic by limiting the location searched.

1. FileUtil.Location.ALL will not place any limits on the search
2. FileUtil.Location.NONE effectively requires that path be a portable pathname
3. FileUtil.Location.INSTALLED limits the search to the PROGRAM directory and JARs in the class path
4. FileUtil.Location.USER limits the search to the PREFERENCES, PROFILE, and SETTINGS directories (in that order)

Parameters:

path - The relative path of the file or resource

locations - The types of locations to limit the search to

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

Returns:

The URI or null

See Also:

• findURI(java.lang.String)
• findURI(java.lang.String, jmri.util.FileUtil.Location)
• findURI(java.lang.String, java.lang.String...)

findURL

public static URL findURL(@Nonnull
 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, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.

TODO: add @CheckForNull annotation / fix Possible null pointers.

Parameters:

path - The relative path of the file or resource.

Returns:

The URL or null.

See Also:

• findURL(java.lang.String, java.lang.String...)
• findURL(java.lang.String, jmri.util.FileUtil.Location)
• findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)

findURL

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

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, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.

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:

• findURL(java.lang.String)
• findURL(java.lang.String, jmri.util.FileUtil.Location)
• findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)

findURL

public static URL findURL(@Nonnull
 String path,
 @Nonnull
 FileUtil.Location locations)

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, jmri.util.FileUtil.Location, java.lang.String...).

Parameters:

path - The relative path of the file or resource

locations - The types of locations to limit the search to

Returns:

The URL or null

See Also:

• findURL(java.lang.String)
• findURL(java.lang.String, java.lang.String...)
• findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)

findURL

public static URL findURL(@Nonnull
 String path,
 @Nonnull
 FileUtil.Location locations,
 @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

The locations parameter limits the above logic by limiting the location searched.

1. FileUtil.Location.ALL will not place any limits on the search
2. FileUtil.Location.NONE effectively requires that path be a portable pathname
3. FileUtil.Location.INSTALLED limits the search to the PROGRAM directory and JARs in the class path
4. FileUtil.Location.USER limits the search to the PROFILE directory

Parameters:

path - The relative path of the file or resource

locations - The types of locations to limit the search to

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

Returns:

The URL or null

See Also:

• findURL(java.lang.String)
• findURL(java.lang.String, jmri.util.FileUtil.Location)
• findURL(java.lang.String, java.lang.String...)

urlToURI

public static URI urlToURI(@Nonnull
 URL url)

Return the URI for a given URL

Parameters:

url - the URL

Returns:

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

fileToURL

public static URL fileToURL(@Nonnull
 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:

the JAR file containing the JMRI library or null if not running from a JAR file

logFilePaths

public static void logFilePaths()

Log all paths at the INFO level.

getScriptsPath

@Nonnull
@CheckReturnValue
public static String getScriptsPath()

Get the path to the scripts directory using the Profile returned by ProfileManager.getActiveProfile() as the base.

Returns:

the scriptsPath

getScriptsPath

@Nonnull
@CheckReturnValue
public static String getScriptsPath(@CheckForNull
 Profile profile)

Get the path to the scripts directory.

Parameters:

profile - the Profile to use as the base

Returns:

the scriptsPath

setScriptsPath

public static void setScriptsPath(@CheckForNull
 Profile profile,
 @CheckForNull
 String path)

Set the path to python scripts.

Parameters:

profile - the profile to set the path for

path - the scriptsPath to set

readFile

public static String readFile(@Nonnull
 File file)
                       throws IOException

Read a text file into a String.

Parameters:

file - The text file.

Returns:

The contents of the file.

Throws:

IOException - if the file cannot be read

readURL

public static String readURL(@Nonnull
 URL url)
                      throws IOException

Read a text URL into a String. Would be significantly simpler with Java 7. File is assumed to be encoded using UTF-8

Parameters:

url - The text URL.

Returns:

The contents of the file.

Throws:

IOException - if the URL cannot be read

sanitizeFilename

@Nonnull
public static String sanitizeFilename(@Nonnull
 String name)

Replaces most non-alphanumeric characters in name with an underscore.

Parameters:

name - The filename to be sanitized.

Returns:

The sanitized filename.

createDirectory

public static void createDirectory(@Nonnull
 String path)

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

Parameters:

path - directory to create

createDirectory

public static void createDirectory(@Nonnull
 File dir)

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

Parameters:

dir - directory to create

delete

public static boolean delete(@Nonnull
 File path)

Recursively delete a path. It is recommended to use Files.delete(java.nio.file.Path) or Files.deleteIfExists(java.nio.file.Path) for files.

Parameters:

path - path to delete

Returns:

true if path was deleted, false otherwise

copy

public static void copy(@Nonnull
 File source,
 @Nonnull
 File dest)
                 throws IOException

Copy a file or directory. It is recommended to use Files.copy(java.nio.file.Path, java.io.OutputStream) for files.

Parameters:

source - the file or directory to copy

dest - must be the file or directory, not the containing directory

Throws:

IOException - if file cannot be copied

appendTextToFile

public static void appendTextToFile(@Nonnull
 File file,
 @Nonnull
 String text)
                             throws IOException

Simple helper method to just append a text string to the end of the given filename. The file will be created if it does not exist.

Parameters:

file - File to append text to

text - Text to append

Throws:

IOException - if file cannot be written to

backup

public static void backup(@Nonnull
 File file)
                   throws IOException

Backup a file. The backup is in the same location as the original file, has the extension .bak appended to the file name, and up to four revisions are retained. The lowest numbered revision is the most recent.

Parameters:

file - the file to backup

Throws:

IOException - if a backup cannot be created

See Also:

• FileUtilSupport.backup(java.io.File)

rotate

public static void rotate(@Nonnull
 File file,
 int max,
 @CheckForNull
 String extension)
                   throws IOException

Rotate a file and its backups, retaining only a set number of backups.

Parameters:

file - the file to rotate

max - maximum number of backups to retain

extension - The extension to use for the rotations. If null or an empty string, the rotation number is used as the extension.

Throws:

IOException - if a backup cannot be created

IllegalArgumentException - if max is less than one

See Also:

• FileUtilSupport.rotate(java.io.File, int, java.lang.String)
• FileUtilSupport.backup(java.io.File)

getDefault

public static FileUtilSupport getDefault()

Get the default instance of FileUtilSupport.

Returns:

the default instance of FileUtilSupport