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(File file, String text)

Simple helper method to just append a text string to the end of the given filename.

void

backup(File file)

Backup a file.

void

copy(File source, File dest)

Copy a file or directory.

void

createDirectory(File dir)

Create a directory if required.

void

createDirectory(String path)

Create a directory if required.

boolean

delete(File path)

Recursively delete a path.

URL

fileToURL(File file)

Return the URL for a given File.

URI

findExternalFilename(String path)

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

Set<File>

findFiles(String name, String root)

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

Set<File>

findFiles(String name, String root, FileUtil.Location location)

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

InputStream

findInputStream(String path)

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

InputStream

findInputStream(String path, String... searchPaths)

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

InputStream

findInputStream(String path, FileUtil.Location locations)

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

InputStream

findInputStream(String path, FileUtil.Location locations, String... searchPaths)

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

URI

findURI(String path)

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

URI

findURI(String path, String... searchPaths)

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

URI

findURI(String path, FileUtil.Location locations)

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

URI

findURI(String path, FileUtil.Location locations, String... searchPaths)

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

URL

findURL(String path)

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

URL

findURL(String path, String... searchPaths)

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

URL

findURL(String path, FileUtil.Location locations)

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

URL

findURL(String path, FileUtil.Location locations, String... searchPaths)

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

String

getAbsoluteFilename(String path)

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

String

getAbsoluteFilename(Profile profile, String path)

Convert a portable filename into an absolute filename.

File

getCacheDirectory()

Get the JMRI cache location, ensuring its existence.

static FileUtilSupport

getDefault()

Get the default instance of a FileUtilSupport object.

String

getExternalFilename(String pName)

Get the resource file corresponding to a name.

String

getExternalFilename(Profile profile, String pName)

Get the resource file corresponding to a name.

File

getFile(String path)

Get the File that path refers to.

File

getFile(Profile profile, String path)

Get the File that path refers to.

String

getHomePath()

Get the user's home directory.

JarFile

getJmriJarFile()

Get the JMRI distribution jar file.

String

getPortableFilename(File file)

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

String

getPortableFilename(File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)

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

String

getPortableFilename(String filename)

Convert a filename string to our preferred storage form.

String

getPortableFilename(String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)

Convert a filename string to our preferred storage form.

String

getPortableFilename(Profile profile, File file)

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

String

getPortableFilename(Profile profile, File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)

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

String

getPortableFilename(Profile profile, String filename)

Convert a filename string to our preferred storage form.

String

getPortableFilename(Profile profile, String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)

Convert a filename string to our preferred storage form.

String

getPreferencesPath()

Get the preferences directory.

String

getProfilePath()

Get the profile directory.

String

getProfilePath(Profile profile)

Get the profile directory.

String

getProgramPath()

Get the JMRI program directory.

String

getScriptsPath()

Get the path to the scripts directory.

String

getScriptsPath(Profile profile)

Get the path to the scripts directory.

URI

getURI(String path)

Get the File that path refers to.

URL

getURL(String path)

Get the URL that path refers to.

URL

getURL(URI uri)

Convenience method to get the URL from a URI.

String

getUserFilesPath()

Get the user's files directory.

String

getUserFilesPath(Profile profile)

Get the user's files directory.

String

getUserResourcePath()

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

boolean

isPortableFilename(String filename)

Test if the given filename is a portable filename.

void

logFilePaths()

Log all paths at the INFO level.

String

readFile(File file)

Read a text file into a String.

String

readURL(URL url)

Read a text URL into a String.

protected static void

resetInstance()

void

rotate(File file, int max, String extension)

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

String

sanitizeFilename(String name)

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

void

setProgramPath(File path)

Set the JMRI program directory.

void

setProgramPath(String path)

Set the JMRI program directory.

void

setScriptsPath(Profile profile, String path)

Set the path to python scripts.

void

setUserFilesPath(Profile profile, String path)

Set the user's files directory.

URI

urlToURI(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 Details
- 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
- resetInstance
  
  protected static void resetInstance()
- getFile
  
  @Nonnull @CheckReturnValue public File getFile(@Nonnull String path) throws FileNotFoundException
  
  Get the File that path refers to. Throws a FileNotFoundException if the file cannot be found instead of returning null (as File would). Use getURI(java.lang.String) or getURL(java.lang.String) instead of this method if possible.
  Parameters:
  
  path - the path to find
  
  Returns:
  
  File at path
  
  Throws:
  
  FileNotFoundException - if path cannot be found
  
  See Also:
  
  getURI(java.lang.String)
  
  getURL(java.lang.String)
- getFile
  
  @Nonnull @CheckReturnValue public File getFile(@CheckForNull Profile profile, @Nonnull String path) throws FileNotFoundException
  
  Get the File that path refers to. Throws a FileNotFoundException if the file cannot be found instead of returning null (as File would). Use getURI(java.lang.String) or getURL(java.lang.String) instead of this method if possible.
  Parameters:
  
  profile - the profile to use as a base
  
  path - the path to find
  
  Returns:
  
  File at path
  
  Throws:
  
  FileNotFoundException - if path cannot be found
  
  See Also:
  
  getURI(java.lang.String)
  
  getURL(java.lang.String)
- getURI
  
  @Nonnull @CheckReturnValue public URI getURI(@Nonnull String path) throws FileNotFoundException
  
  Get the File that path refers to. Throws a FileNotFoundException if the file cannot be found instead of returning null (as File would).
  Parameters:
  
  path - the path to find
  
  Returns:
  
  File at path
  
  Throws:
  
  FileNotFoundException - if path cannot be found
  
  See Also:
  
  getFile(java.lang.String)
  
  getURL(java.lang.String)
- getURL
  
  @Nonnull @CheckReturnValue public URL getURL(@Nonnull String path) throws FileNotFoundException
  
  Get the URL that path refers to. Throws a FileNotFoundException if the URL cannot be found instead of returning null.
  Parameters:
  
  path - the path to find
  
  Returns:
  
  URL at path
  
  Throws:
  
  FileNotFoundException - if path cannot be found
  
  See Also:
  
  getFile(java.lang.String)
  
  getURI(java.lang.String)
- getURL
  
  @CheckForNull @CheckReturnValue public URL getURL(@Nonnull URI uri)
  
  Convenience method to get the URL from a URI. Logs errors and returns null if any exceptions are thrown by the conversion.
  
  Parameters:
  
  uri - The URI to convert.
  
  Returns:
  
  URL or null if any errors exist.
- findFiles
  
  @Nonnull @CheckReturnValue public Set<File> findFiles(@Nonnull String name, @Nonnull String root) throws IllegalArgumentException
  
  Find all files matching the given name under the given root directory within both the user and installed file locations.
  
  Parameters:
  
  name - the name of the file to find
  
  root - the relative path to a directory in either or both of the user or installed file locations; use a single period character to refer to the root of the user or installed file locations
  
  Returns:
  
  a set of found files or an empty set if no matching files were found
  
  Throws:
  
  IllegalArgumentException - if the name is not a relative path, is empty, or contains path separators; or if the root is not a relative path, is empty, or contains a parent directory (..)
  
  NullPointerException - if any parameter is null
- findFiles
  
  @Nonnull @CheckReturnValue public Set<File> findFiles(@Nonnull String name, @Nonnull String root, @Nonnull FileUtil.Location location)
  
  Find all files matching the given name under the given root directory within the specified location.
  
  Parameters:
  
  name - the name of the file to find
  
  root - the relative path to a directory in either or both of the user or installed file locations; use a single period character to refer to the root of the location
  
  location - the location to search within
  
  Returns:
  
  a set of found files or an empty set if no matching files were found
  
  Throws:
  
  IllegalArgumentException - if the name is not a relative path, is empty, or contains path separators; if the root is not a relative path, is empty, or contains a parent directory (..); or if the location is FileUtil.Location.NONE
  
  NullPointerException - if any parameter is null
- getExternalFilename
  
  @Nonnull @CheckReturnValue public String getExternalFilename(@Nonnull 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 String getExternalFilename(@CheckForNull Profile profile, @Nonnull 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 String getAbsoluteFilename(@Nonnull String path)
  
  Convert a portable filename into an absolute filename, using ProfileManager.getActiveProfile() as the base.
  
  Parameters:
  
  path - the portable filename
  
  Returns:
  
  An absolute filename
- getAbsoluteFilename
  
  @Nonnull @CheckReturnValue public String getAbsoluteFilename(@CheckForNull Profile profile, @Nonnull 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 String getPortableFilename(@Nonnull File file)
  
  Convert a File object's path to our preferred storage form.
  This is the inverse of getFile(String pName). Deprecated forms are not created.
  
  Parameters:
  
  file - File at path to be represented
  
  Returns:
  
  Filename for storage in a portable manner. This will include portable, not system-specific, file separators.
  
  Since:
  
  2.7.2
- getPortableFilename
  
  @Nonnull @CheckReturnValue public String getPortableFilename(@Nonnull File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
  
  Convert a File object's path to our preferred storage form.
  This is the inverse of getFile(String pName). Deprecated forms are not created.
  This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the ProfileManager to write an incorrect path for the current profile or FileLocationPaneXml to write an incorrect path for the Users file directory. In most cases, the use of getPortableFilename(java.io.File) is preferable.
  
  Parameters:
  
  file - File at path to be represented
  
  ignoreUserFilesPath - true if paths in the User files path should be stored as absolute paths, which is often not desirable.
  
  ignoreProfilePath - true if paths in the profile should be stored as absolute paths, which is often not desirable.
  
  Returns:
  
  Storage format representation
  
  Since:
  
  3.5.5
- getPortableFilename
  
  @Nonnull @CheckReturnValue public String getPortableFilename(@Nonnull String filename)
  
  Convert a filename string to our preferred storage form.
  This is the inverse of getExternalFilename(String pName). Deprecated forms are not created.
  
  Parameters:
  
  filename - Filename to be represented
  
  Returns:
  
  Filename for storage in a portable manner
  
  Since:
  
  2.7.2
- getPortableFilename
  
  @Nonnull @CheckReturnValue public String getPortableFilename(@Nonnull String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
  
  Convert a filename string to our preferred storage form.
  This is the inverse of getExternalFilename(String pName). Deprecated forms are not created.
  This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the ProfileManager to write an incorrect path for the current profile or FileLocationPaneXml to write an incorrect path for the Users file directory. In most cases, the use of getPortableFilename(java.io.File) is preferable.
  
  Parameters:
  
  filename - Filename to be represented
  
  ignoreUserFilesPath - true if paths in the User files path should be stored as absolute paths, which is often not desirable.
  
  ignoreProfilePath - true if paths in the profile path should be stored as absolute paths, which is often not desirable.
  
  Returns:
  
  Storage format representation
  
  Since:
  
  3.5.5
- getPortableFilename
  
  @Nonnull @CheckReturnValue public String getPortableFilename(@CheckForNull Profile profile, @Nonnull File file)
  
  Convert a File object's path to our preferred storage form.
  This is the inverse of getFile(String pName). Deprecated forms are not created.
  
  Parameters:
  
  profile - Profile to use as 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 String getPortableFilename(@CheckForNull Profile profile, @Nonnull File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
  
  Convert a File object's path to our preferred storage form.
  This is the inverse of getFile(String pName). Deprecated forms are not created.
  This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the ProfileManager to write an incorrect path for the current profile or FileLocationPaneXml to write an incorrect path for the Users file directory. In most cases, the use of getPortableFilename(java.io.File) is preferable.
  
  Parameters:
  
  profile - Profile to use as 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 String getPortableFilename(@CheckForNull Profile profile, @Nonnull String filename)
  
  Convert a filename string to our preferred storage form.
  This is the inverse of getExternalFilename(String pName). Deprecated forms are not created.
  
  Parameters:
  
  profile - 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 String getPortableFilename(@CheckForNull Profile profile, @Nonnull String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
  
  Convert a filename string to our preferred storage form.
  This is the inverse of getExternalFilename(String pName). Deprecated forms are not created.
  This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the ProfileManager to write an incorrect path for the current profile or FileLocationPaneXml to write an incorrect path for the Users file directory. In most cases, the use of getPortableFilename(java.io.File) is preferable.
  
  Parameters:
  
  profile - 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 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 String getHomePath()
  
  Get the user's home directory.
  
  Returns:
  
  User's home directory as a String
- getUserFilesPath
  
  @Nonnull @CheckReturnValue public 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 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 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 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 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 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 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 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 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 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 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 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 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 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 URI findExternalFilename(@Nonnull 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 InputStream findInputStream(@Nonnull String path)
  
  Search for a file or JAR resource by name and return the InputStream for that file. Search order is defined by findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.
  Parameters:
  
  path - The relative path of the file or resource
  
  Returns:
  
  InputStream or null.
  
  See Also:
  
  findInputStream(java.lang.String, java.lang.String...)
  
  findInputStream(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
  
  findURL(java.lang.String)
  
  findURL(java.lang.String, java.lang.String...)
  
  findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
- findInputStream
  
  public InputStream findInputStream(@Nonnull String path, @Nonnull String... searchPaths)
  
  Search for a file or JAR resource by name and return the InputStream for that file. Search order is defined by findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.
  Parameters:
  
  path - The relative path of the file or resource
  
  searchPaths - a list of paths to search for the path in
  
  Returns:
  
  InputStream or null.
  
  See Also:
  
  findInputStream(java.lang.String)
  
  findInputStream(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
- findInputStream
  
  public InputStream findInputStream(@Nonnull 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 InputStream findInputStream(@Nonnull String path, @Nonnull FileUtil.Location locations, @Nonnull String... searchPaths)
  
  Search for a file or JAR resource by name and return the InputStream for that file. Search order is defined by findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...).
  Parameters:
  
  path - The relative path of the file or resource
  
  locations - The type of locations to limit the search to
  
  searchPaths - a list of paths to search for the path in
  
  Returns:
  
  InputStream or null.
  
  See Also:
  
  findInputStream(java.lang.String)
  
  findInputStream(java.lang.String, java.lang.String...)
- findURI
  
  public URI findURI(@Nonnull String path)
  
  Search for a file or JAR resource by name and return the URI for that file. Search order is defined by findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.
  Parameters:
  
  path - The relative path of the file or resource.
  
  Returns:
  
  The URI or null.
  
  See Also:
  
  findURI(java.lang.String, java.lang.String...)
  
  findURI(java.lang.String, jmri.util.FileUtil.Location)
  
  findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
- findURI
  
  public URI findURI(@Nonnull String path, @Nonnull String... searchPaths)
  
  Search for a file or JAR resource by name and return the URI for that file. Search order is defined by findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.
  Note that if the file for path is not found in one of the searchPaths, all standard locations are also be searched through to find the file. If you need to limit the locations where the file can be found use findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...).
  Parameters:
  
  path - The relative path of the file or resource
  
  searchPaths - a list of paths to search for the path in
  
  Returns:
  
  The URI or null
  
  See Also:
  
  findURI(java.lang.String)
  
  findURI(java.lang.String, jmri.util.FileUtil.Location)
  
  findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
- findURI
  
  public URI findURI(@Nonnull String path, @Nonnull FileUtil.Location locations)
  
  Search for a file or JAR resource by name and return the URI for that file. Search order is defined by findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...).
  Parameters:
  
  path - The relative path of the file or resource
  
  locations - The types of locations to limit the search to
  
  Returns:
  
  The URI or null
  
  See Also:
  
  findURI(java.lang.String)
  
  findURI(java.lang.String, java.lang.String...)
  
  findURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
- findURI
  
  public URI findURI(@Nonnull String path, @Nonnull FileUtil.Location locations, @Nonnull String... searchPaths)
  Search for a file or JAR resource by name and return the URI for that file.
  Search order is:
  
  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 URL findURL(@Nonnull String path)
  
  Search for a file or JAR resource by name and return the URL for that file. Search order is defined by findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.
  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 URL findURL(@Nonnull String path, @Nonnull String... searchPaths)
  
  Search for a file or JAR resource by name and return the URL for that file. Search order is defined by findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...). No limits are placed on search locations.
  Parameters:
  
  path - The relative path of the file or resource
  
  searchPaths - a list of paths to search for the path in
  
  Returns:
  
  The URL or null
  
  See Also:
  
  findURL(java.lang.String)
  
  findURL(java.lang.String, jmri.util.FileUtil.Location)
  
  findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
- findURL
  
  public URL findURL(@Nonnull 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 URL findURL(@Nonnull String path, @Nonnull FileUtil.Location locations, @Nonnull String... searchPaths)
  Search for a file or JAR resource by name and return the URL for that file.
  Search order is:
  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 URI urlToURI(@Nonnull URL url)
  
  Return the URI for a given URL
  
  Parameters:
  
  url - the URL
  
  Returns:
  
  a URI or null if the conversion would have caused a URISyntaxException
- fileToURL
  
  public URL fileToURL(@Nonnull File file)
  
  Return the URL for a given File. This method catches a MalformedURLException and returns null in its place, since we really do not expect a File object to ever give a malformed URL. This method exists solely so implementing classes do not need to catch that exception.
  
  Parameters:
  
  file - The File to convert.
  
  Returns:
  
  a URL or null if the conversion would have caused a MalformedURLException
- getJmriJarFile
  
  public 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 String readFile(@Nonnull File file) throws IOException
  
  Read a text file into a String.
  
  Parameters:
  
  file - The text file.
  
  Returns:
  
  The contents of the file.
  
  Throws:
  
  IOException - if the file cannot be read
- readURL
  
  public String readURL(@Nonnull URL url) throws IOException
  
  Read a text URL into a String.
  
  Parameters:
  
  url - The text URL.
  
  Returns:
  
  The contents of the file.
  
  Throws:
  
  IOException - if the URL cannot be read
- sanitizeFilename
  
  @Nonnull public String sanitizeFilename(@Nonnull String name)
  
  Replaces most non-alphanumeric characters in name with an underscore.
  
  Parameters:
  
  name - The filename to be sanitized.
  
  Returns:
  
  The sanitized filename.
- createDirectory
  
  public void createDirectory(@Nonnull String path)
  
  Create a directory if required. Any parent directories will also be created.
  
  Parameters:
  
  path - directory to create
- createDirectory
  
  public void createDirectory(@Nonnull File dir)
  
  Create a directory if required. Any parent directories will also be created.
  
  Parameters:
  
  dir - directory to create
- delete
  
  public boolean delete(@Nonnull File path)
  
  Recursively delete a path. It is recommended to use Files.delete(java.nio.file.Path) or Files.deleteIfExists(java.nio.file.Path) for files.
  
  Parameters:
  
  path - path to delete
  
  Returns:
  
  true if path was deleted, false otherwise
- copy
  
  public void copy(@Nonnull File source, @Nonnull File dest) throws IOException
  
  Copy a file or directory. It is recommended to use Files.copy(java.nio.file.Path, java.io.OutputStream) for files.
  
  Parameters:
  
  source - the file or directory to copy
  
  dest - must be the file or directory, not the containing directory
  
  Throws:
  
  IOException - if file cannot be copied
- appendTextToFile
  
  public void appendTextToFile(@Nonnull File file, @Nonnull String text) throws IOException
  
  Simple helper method to just append a text string to the end of the given filename. The file will be created if it does not exist.
  
  Parameters:
  
  file - File to append text to
  
  text - Text to append
  
  Throws:
  
  IOException - if file cannot be written to
- backup
  
  public void backup(@Nonnull File file) throws IOException
  
  Backup a file. The backup is in the same location as the original file, has the extension .bak appended to the file name, and up to four revisions are retained. The lowest numbered revision is the most recent.
  
  Parameters:
  
  file - the file to backup
  
  Throws:
  
  IOException - if a backup cannot be created
- rotate
  
  public void rotate(@Nonnull File file, int max, @CheckForNull String extension) throws IOException
  
  Rotate a file and its backups, retaining only a set number of backups.
  Parameters:
  
  file - the file to rotate
  
  max - maximum number of backups to retain
  
  extension - The extension to use for the rotations. If null or an empty string, the rotation number is used as the extension.
  
  Throws:
  
  IOException - if a backup cannot be created
  
  IllegalArgumentException - if max is less than one
  
  See Also:
  
  backup(java.io.File)

Class FileUtilSupport

Field Summary

Fields inherited from class jmri.beans.Bean

Method Summary

Methods inherited from class jmri.beans.Bean

Methods inherited from class jmri.beans.UnboundBean

Methods inherited from class java.lang.Object

Method Details

getDefault

resetInstance

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