Package jmri.util

Class FileUtilSupport

java.lang.Object

jmri.beans.UnboundBean

jmri.beans.Bean

jmri.util.FileUtilSupport

All Implemented Interfaces:

BeanInterface, PropertyChangeFirer, PropertyChangeProvider

public class FileUtilSupport
extends Bean

Support the FileUtil static API while providing PropertyChangeSupport for listening to changes in the paths. Also provides the underlying implementation of all FileUtil methods so they can be exposed to scripts as an object methods instead of as static methods of a class.

Field Summary

Fields inherited from class jmri.beans.Bean

propertyChangeSupport

Method Summary

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

Methods inherited from class jmri.beans.Bean

addPropertyChangeListener, addPropertyChangeListener, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getPropertyChangeListeners, getPropertyChangeListeners, isNotifyOnEDT, removePropertyChangeListener, removePropertyChangeListener

Methods inherited from class jmri.beans.UnboundBean

getIndexedProperty, getProperty, getPropertyNames, hasIndexedProperty, hasProperty, setIndexedProperty, setProperty

Methods inherited from class java.lang.Object

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

Method Detail

getFile

@Nonnull
@CheckReturnValue
public 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 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 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 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 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 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 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 java.lang.String getExternalFilename(@Nonnull
                                            java.lang.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 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 "file:", treat the rest as a relative path below the resource directory in the preferences directory (deprecated; see "preference:" above)
• 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 file:, home:, profile:, program:, preference:, scripts:, settings, or resource:

Returns:

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

Since:

2.7.2

getExternalFilename

@Nonnull
@CheckReturnValue
public 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 "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 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 "file:", treat the rest as a relative path below the resource directory in the preferences directory (deprecated; see "preference:" above)
• 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 file:, home:, profile:, program:, preference:, scripts:, settings, or resource:

Returns:

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

Since:

4.17.3

getAbsoluteFilename

@Nonnull
@CheckReturnValue
public 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 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 as the base

path - the portable filename

Returns:

An absolute filename

getPortableFilename

@Nonnull
@CheckReturnValue
public 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 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 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 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 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 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 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 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:

3.5.5

getPortableFilename

@Nonnull
@CheckReturnValue
public 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 - Profile to use as base

filename - Filename to be represented

Returns:

Filename for storage in a portable manner

Since:

4.17.3

getPortableFilename

@Nonnull
@CheckReturnValue
public 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 - Profile to use as 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 boolean isPortableFilename(@Nonnull
                                  java.lang.String filename)

Test if the given filename is a portable filename.

Note that this method may return a false positive if the filename is a file: URL.

Parameters:

filename - the name to test

Returns:

true if filename is portable

getHomePath

@Nonnull
@CheckReturnValue
public java.lang.String getHomePath()

Get the user's home directory.

Returns:

User's home directory as a String

getUserFilesPath

@Nonnull
@CheckReturnValue
public java.lang.String getUserFilesPath()

Get the user's files directory. If not set by the user, this is the same as the profile path returned by ProfileManager.getActiveProfile(). Note that if the profile path has been set to null, that returns the preferences directory, see getProfilePath().

Returns:

User's files directory

See Also:

getProfilePath()

getUserFilesPath

@Nonnull
@CheckReturnValue
public 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. Note that if the profile path has been set to null, that returns the preferences directory, see getProfilePath().

Parameters:

profile - the profile to use

Returns:

User's files directory

See Also:

getProfilePath()

setUserFilesPath

public void setUserFilesPath(@CheckForNull
                             Profile profile,
                             @Nonnull
                             java.lang.String path)

Set the user's files directory.

Parameters:

profile - the profile to set the user's files directory for

path - The path to the user's files directory using system-specific separators

See Also:

getUserFilesPath()

getProfilePath

@Nonnull
@CheckReturnValue
public java.lang.String getProfilePath(@CheckForNull
                                       Profile profile)

Get the profile directory. If not set, provide the preferences path.

Parameters:

profile - the Profile to use as a base

Returns:

Profile directory using system-specific separators

See Also:

getPreferencesPath()

getProfilePath

@Nonnull
@CheckReturnValue
public java.lang.String getProfilePath()

Get the profile directory. If not set, provide the preferences path. Uses the Profile returned by ProfileManager.getActiveProfile() as a base.

Returns:

Profile directory using system-specific separators

See Also:

getPreferencesPath()

getPreferencesPath

@Nonnull
@CheckReturnValue
public 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 using system-specific separators.

See Also:

getHomePath()

getCacheDirectory

@Nonnull
public java.io.File getCacheDirectory()

Get the JMRI cache location, ensuring its existence.

This is not part of the FileUtil API since it should generally be accessed using ProfileUtils.getCacheDirectory(jmri.profile.Profile, java.lang.Class).

Uses the following locations (where [version] is from Version.getCanonicalVersion()):

System Property (if set)

value of jmri_default_cachedir

macOS

~/Library/Caches/JMRI/[version]

Windows

%Local AppData%/JMRI/[version]

UNIX/Linux/POSIX

${XDG_CACHE_HOME}/JMRI/[version] or $HOME/.cache/JMRI/[version]

Fallback

JMRI portable path setting:cache/[version]

Returns:

the cache directory for this version of JMRI

getProgramPath

@Nonnull
@CheckReturnValue
public java.lang.String getProgramPath()

Get the JMRI program directory.

If the program directory has not been previously set, first sets the program directory to the value specified in the Java System property jmri.path.program

If this property is unset, finds from jar or class files location.

If this fails, returns . .

Returns:

JMRI program directory as a String.

setProgramPath

public 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 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

getUserResourcePath

@Nonnull
@CheckReturnValue
public java.lang.String getUserResourcePath()

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

Returns:

path to [user's file]/resources/ using system-specific separators

logFilePaths

public void logFilePaths()

Log all paths at the INFO level.

getScriptsPath

@Nonnull
@CheckReturnValue
public java.lang.String getScriptsPath()

Get the path to the scripts directory. If not set previously with setScriptsPath(jmri.profile.Profile, java.lang.String), this is the "jython" subdirectory in the program directory. Uses the Profile returned by ProfileManager.getActiveProfile() as the base.

Returns:

the scripts directory using system-specific separators

getScriptsPath

@Nonnull
@CheckReturnValue
public java.lang.String getScriptsPath(@CheckForNull
                                       Profile profile)

Get the path to the scripts directory. If not set previously with setScriptsPath(jmri.profile.Profile, java.lang.String), this is the "jython" subdirectory in the program directory.

Parameters:

profile - the Profile to use as the base

Returns:

the path to scripts directory using system-specific separators

setScriptsPath

public void setScriptsPath(@CheckForNull
                           Profile profile,
                           @CheckForNull
                           java.lang.String path)

Set the path to python scripts.

Parameters:

profile - the profile to use as a base

path - the scriptsPaths to set; null resets to the default, defined in getScriptsPath()

findExternalFilename

@Nonnull
@CheckReturnValue
public java.net.URI findExternalFilename(@Nonnull
                                         java.lang.String path)

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

Parameters:

path - the path to find

Returns:

URL of portable or absolute path

findInputStream

public 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 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 java.io.InputStream findInputStream(@Nonnull
                                           java.lang.String path,
                                           @Nonnull
                                           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 java.io.InputStream findInputStream(@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 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...)

findURI

public 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 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 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 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 FileUtil.PROGRAM directory and JARs in the class path
4. FileUtil.Location.USER limits the search to the FileUtil.PREFERENCES, FileUtil.PROFILE, and FileUtil.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 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.

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 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 java.net.URL findURL(@Nonnull
                            java.lang.String path,
                            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 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 FileUtil.PROGRAM directory and JARs in the class path
4. FileUtil.Location.USER limits the search to the FileUtil.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 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 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

getJmriJarFile

public java.util.jar.JarFile getJmriJarFile()

Get the JMRI distribution jar file.

Returns:

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

readFile

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

Read a text URL into a String.

Parameters:

url - The text URL.

Returns:

The contents of the file.

Throws:

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

sanitizeFilename

@Nonnull
public 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 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 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 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 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 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 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

rotate

public 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:

backup(java.io.File)

getDefault

public static FileUtilSupport getDefault()

Get the default instance of a FileUtilSupport object.

Unlike most implementations of getDefault(), this does not return an object held by InstanceManager due to the need for this default instance to be available prior to the creation of an InstanceManager.

Returns:

the default FileUtilSupport instance, creating it if necessary