Package jmri.util

Class FileUtil

java.lang.Object

jmri.util.FileUtil

public final class FileUtil
extends java.lang.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 class	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 java.lang.String	HOME	Portable reference to the user's home directory.
static java.lang.String	PREFERENCES	Portable reference to the JMRI user's files and preferences directory.
static java.lang.String	PROFILE	Portable reference to the current profile directory.
static java.lang.String	PROGRAM	Portable reference to items in the JMRI program directory.
static java.lang.String	SCRIPTS	Portable reference to the current scripts directory.
static char	SEPARATOR	The portable file path component separator.
static java.lang.String	SETTINGS	Portable reference to the JMRI applications preferences directory.

Method Summary

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

Portable reference to items in the JMRI program directory.

See Also:

Constant Field Values

PREFERENCES

public static final java.lang.String PREFERENCES

Portable reference to the JMRI user's files and preferences directory.

See Also:

Constant Field Values

SETTINGS

public static final java.lang.String SETTINGS

Portable reference to the JMRI applications preferences directory.

See Also:

Constant Field Values

HOME

public static final java.lang.String HOME

Portable reference to the user's home directory.

See Also:

Constant Field Values

PROFILE

public static final java.lang.String PROFILE

Portable reference to the current profile directory.

See Also:

Constant Field Values

SCRIPTS

public static final java.lang.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 Detail

getFile

@Nonnull
@CheckReturnValue
public static java.io.File getFile(@Nonnull
                                   java.lang.String path)
                            throws java.io.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:

java.io.FileNotFoundException - if path cannot be found

See Also:

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

getFile

@Nonnull
@CheckReturnValue
public static java.io.File getFile(@CheckForNull
                                   Profile profile,
                                   @Nonnull
                                   java.lang.String path)
                            throws java.io.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:

java.io.FileNotFoundException - if path cannot be found

See Also:

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

getURI

@Nonnull
@CheckReturnValue
public static java.net.URI getURI(@Nonnull
                                  java.lang.String path)
                           throws java.io.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:

java.io.FileNotFoundException - if path cannot be found

See Also:

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

getURL

@Nonnull
@CheckReturnValue
public static java.net.URL getURL(@Nonnull
                                  java.lang.String path)
                           throws java.io.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:

java.io.FileNotFoundException - if path cannot be found

See Also:

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

getURL

@CheckForNull
@CheckReturnValue
public static java.net.URL getURL(@Nonnull
                                  java.net.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 java.util.Set<java.io.File> findFiles(@Nonnull
                                                    java.lang.String name,
                                                    @Nonnull
                                                    java.lang.String root)
                                             throws java.lang.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:

java.lang.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 (..)

java.lang.NullPointerException - if any parameter is null

findFiles

@Nonnull
@CheckReturnValue
public static java.util.Set<java.io.File> findFiles(@Nonnull
                                                    java.lang.String name,
                                                    @Nonnull
                                                    java.lang.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:

java.lang.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

java.lang.NullPointerException - if any parameter is null

getExternalFilename

@Nonnull
@CheckReturnValue
public static java.lang.String getExternalFilename(@Nonnull
                                                   java.lang.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 java.lang.String getExternalFilename(@CheckForNull
                                                   Profile profile,
                                                   @Nonnull
                                                   java.lang.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 java.lang.String getAbsoluteFilename(@Nonnull
                                                   java.lang.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 java.lang.String getAbsoluteFilename(@CheckForNull
                                                   Profile profile,
                                                   @Nonnull
                                                   java.lang.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 java.lang.String getPortableFilename(@Nonnull
                                                   java.io.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 java.lang.String getPortableFilename(@Nonnull
                                                   java.io.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 java.lang.String getPortableFilename(@Nonnull
                                                   java.lang.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 java.lang.String getPortableFilename(@Nonnull
                                                   java.lang.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 java.lang.String getPortableFilename(@CheckForNull
                                                   Profile profile,
                                                   @Nonnull
                                                   java.io.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 java.lang.String getPortableFilename(@CheckForNull
                                                   Profile profile,
                                                   @Nonnull
                                                   java.io.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 java.lang.String getPortableFilename(@CheckForNull
                                                   Profile profile,
                                                   @Nonnull
                                                   java.lang.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 java.lang.String getPortableFilename(@CheckForNull
                                                   Profile profile,
                                                   @Nonnull
                                                   java.lang.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
                                         java.lang.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 java.lang.String getHomePath()

Get the user's home directory.

Returns:

User's home directory as a String

getUserFilesPath

@Nonnull
@CheckReturnValue
public static java.lang.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 java.lang.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
                                    java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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
                                  java.lang.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
                                  java.io.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 java.net.URI findExternalFilename(@Nonnull
                                                java.lang.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 java.io.InputStream findInputStream(@Nonnull
                                                  java.lang.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 java.io.InputStream findInputStream(@Nonnull
                                                  java.lang.String path,
                                                  @Nonnull
                                                  java.lang.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 java.io.InputStream findInputStream(@Nonnull
                                                  java.lang.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 java.io.InputStream findInputStream(@Nonnull
                                                  java.lang.String path,
                                                  FileUtil.Location locations,
                                                  @Nonnull
                                                  java.lang.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 java.lang.String getUserResourcePath()

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

Returns:

path to [user's file]/resources/

findURI

public static java.net.URI findURI(@Nonnull
                                   java.lang.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 java.net.URI findURI(@Nonnull
                                   java.lang.String path,
                                   @Nonnull
                                   java.lang.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 java.net.URI findURI(@Nonnull
                                   java.lang.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 java.net.URI findURI(@Nonnull
                                   java.lang.String path,
                                   @Nonnull
                                   FileUtil.Location locations,
                                   @Nonnull
                                   java.lang.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 java.net.URL findURL(@Nonnull
                                   java.lang.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 java.net.URL findURL(@Nonnull
                                   java.lang.String path,
                                   @Nonnull
                                   java.lang.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 java.net.URL findURL(@Nonnull
                                   java.lang.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 java.net.URL findURL(@Nonnull
                                   java.lang.String path,
                                   @Nonnull
                                   FileUtil.Location locations,
                                   @Nonnull
                                   java.lang.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 java.net.URI urlToURI(@Nonnull
                                    java.net.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 java.net.URL fileToURL(@Nonnull
                                     java.io.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 java.util.jar.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 java.lang.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 java.lang.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
                                  java.lang.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 java.lang.String readFile(@Nonnull
                                        java.io.File file)
                                 throws java.io.IOException

Read a text file into a String.

Parameters:

file - The text file.

Returns:

The contents of the file.

Throws:

java.io.IOException - if the file cannot be read

readURL

public static java.lang.String readURL(@Nonnull
                                       java.net.URL url)
                                throws java.io.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:

java.io.IOException - if the URL cannot be read

sanitizeFilename

@Nonnull
public static java.lang.String sanitizeFilename(@Nonnull
                                                java.lang.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
                                   java.lang.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
                                   java.io.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
                             java.io.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
                        java.io.File source,
                        @Nonnull
                        java.io.File dest)
                 throws java.io.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:

java.io.IOException - if file cannot be copied

appendTextToFile

public static void appendTextToFile(@Nonnull
                                    java.io.File file,
                                    @Nonnull
                                    java.lang.String text)
                             throws java.io.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:

java.io.IOException - if file cannot be written to

backup

public static void backup(@Nonnull
                          java.io.File file)
                   throws java.io.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:

java.io.IOException - if a backup cannot be created

See Also:

FileUtilSupport.backup(java.io.File)

rotate

public static void rotate(@Nonnull
                          java.io.File file,
                          int max,
                          @CheckForNull
                          java.lang.String extension)
                   throws java.io.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:

java.io.IOException - if a backup cannot be created

java.lang.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