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

Constructor Summary

Constructors
Constructor Description

FileUtilSupport()

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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

- Constructor Detail
  - FileUtilSupport
```
public FileUtilSupport()
```
- 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:
    
    For any provided searchPaths, iterate over the searchPaths by prepending each searchPath to the path and following the following search order:
    
    As a File in the user preferences directory
    
    As a File in the current working directory (usually, but not always the JMRI distribution directory)
    
    As a File in the JMRI distribution directory
    
    As a resource in jmri.jar
    
    If the file or resource has not been found in the searchPaths, search in the four locations listed without prepending any path
    
    As a File with an absolute path
    
    The locations parameter limits the above logic by limiting the location searched.
    
    FileUtil.Location.ALL will not place any limits on the search
    
    FileUtil.Location.NONE effectively requires that path be a portable pathname
    
    FileUtil.Location.INSTALLED limits the search to the FileUtil.PROGRAM directory and JARs in the class path
    
    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:
    For any provided searchPaths, iterate over the searchPaths by prepending each searchPath to the path and following the following search order:
    As a File in the user preferences directory
    
    As a File in the current working directory (usually, but not always the JMRI distribution directory)
    
    As a File in the JMRI distribution directory
    
    As a resource in jmri.jar
    
    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.
    FileUtil.Location.ALL will not place any limits on the search
    FileUtil.Location.NONE effectively requires that path be a portable pathname
    FileUtil.Location.INSTALLED limits the search to the FileUtil.PROGRAM directory and JARs in the class path
    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

Class FileUtilSupport

Field Summary

Fields inherited from class jmri.beans.Bean

Constructor Summary

Method Summary

Methods inherited from class jmri.beans.Bean

Methods inherited from class jmri.beans.UnboundBean

Methods inherited from class java.lang.Object

Constructor Detail

FileUtilSupport

Method Detail

getFile

getFile

getURI

getURL

getURL

findFiles

findFiles

getExternalFilename

getExternalFilename

getAbsoluteFilename

getAbsoluteFilename

getPortableFilename

getPortableFilename

getPortableFilename

getPortableFilename

getPortableFilename

getPortableFilename

getPortableFilename

getPortableFilename

isPortableFilename

getHomePath

getUserFilesPath

getUserFilesPath

setUserFilesPath

getProfilePath

getProfilePath

getPreferencesPath

getCacheDirectory

getProgramPath

setProgramPath

setProgramPath

getUserResourcePath

logFilePaths

getScriptsPath

getScriptsPath

setScriptsPath

findExternalFilename

findInputStream

findInputStream

findInputStream

findInputStream

findURI

findURI

findURI

findURI

findURL

findURL

findURL

findURL

urlToURI

fileToURL

getJmriJarFile

readFile

readURL

sanitizeFilename

createDirectory

createDirectory

delete

copy

appendTextToFile

backup

rotate

getDefault