Class FileUtilSupport
- java.lang.Object
-
- jmri.beans.UnboundBean
-
- jmri.beans.Bean
-
- jmri.util.FileUtilSupport
-
- All Implemented Interfaces:
BeanInterface
,PropertyChangeFirer
,PropertyChangeProvider
public class FileUtilSupport extends Bean
Support theFileUtil
static API while providingPropertyChangeSupport
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
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 theURL
for a givenFile
.java.net.URI
findExternalFilename(java.lang.String path)
Get the URL of a portable filename if it can be located usingfindURI(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 theInputStream
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 theInputStream
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 theInputStream
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 theInputStream
for that file.java.net.URI
findURI(java.lang.String path)
Search for a file or JAR resource by name and return theURI
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 theURI
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 theURI
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 theURI
for that file.java.net.URL
findURL(java.lang.String path)
Search for a file or JAR resource by name and return theURL
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 theURL
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 theURL
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 theURL
for that file.java.lang.String
getAbsoluteFilename(java.lang.String path)
Convert a portable filename into an absolute filename, usingProfileManager.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 theFile
that path refers to.java.io.File
getFile(Profile profile, java.lang.String path)
Get theFile
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 theFile
that path refers to.java.net.URL
getURL(java.lang.String path)
Get theURL
that path refers to.java.net.URL
getURL(java.net.URI uri)
Convenience method to get theURL
from aURI
.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 theURI
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
-
-
-
-
Method Detail
-
getFile
@Nonnull @CheckReturnValue public java.io.File getFile(@Nonnull java.lang.String path) throws java.io.FileNotFoundException
Get theFile
that path refers to. Throws aFileNotFoundException
if the file cannot be found instead of returning null (as File would). UsegetURI(java.lang.String)
orgetURL(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 theFile
that path refers to. Throws aFileNotFoundException
if the file cannot be found instead of returning null (as File would). UsegetURI(java.lang.String)
orgetURL(java.lang.String)
instead of this method if possible.- Parameters:
profile
- the profile to use as a basepath
- 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 theFile
that path refers to. Throws aFileNotFoundException
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 theURL
that path refers to. Throws aFileNotFoundException
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 theURL
from aURI
. 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 findroot
- 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 findroot
- 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 locationlocation
- 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 isFileUtil.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
active
Profile
- 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
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
active
Profile
- 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
- Parameters:
profile
- the Profile to use as a basepName
- 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, usingProfileManager.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 basepath
- 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 orFileLocationPaneXml
to write an incorrect path for the Users file directory. In most cases, the use ofgetPortableFilename(java.io.File)
is preferable.- Parameters:
file
- File at path to be representedignoreUserFilesPath
- 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 orFileLocationPaneXml
to write an incorrect path for the Users file directory. In most cases, the use ofgetPortableFilename(java.io.File)
is preferable.- Parameters:
filename
- Filename to be representedignoreUserFilesPath
- 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 basefile
- 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 orFileLocationPaneXml
to write an incorrect path for the Users file directory. In most cases, the use ofgetPortableFilename(java.io.File)
is preferable.- Parameters:
profile
- Profile to use as basefile
- File at path to be representedignoreUserFilesPath
- 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 basefilename
- 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 orFileLocationPaneXml
to write an incorrect path for the Users file directory. In most cases, the use ofgetPortableFilename(java.io.File)
is preferable.- Parameters:
profile
- Profile to use as basefilename
- Filename to be representedignoreUserFilesPath
- 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 byProfileManager.getActiveProfile()
. Note that if the profile path has been set to null, that returns the preferences directory, seegetProfilePath()
.- 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, seegetProfilePath()
.- 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 forpath
- 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 byProfileManager.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.
getHomePath()
to get the User's home directory.- Returns:
- Path to the preferences directory using system-specific separators.
- See Also:
getHomePath()
- On Microsoft Windows systems, this is
-
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 usingProfileUtils.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 withsetScriptsPath(jmri.profile.Profile, java.lang.String)
, this is the "jython" subdirectory in the program directory. Uses the Profile returned byProfileManager.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 withsetScriptsPath(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 basepath
- the scriptsPaths to set; null resets to the default, defined ingetScriptsPath()
-
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 usingfindURI(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 theInputStream
for that file. Search order is defined byfindURL(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 theInputStream
for that file. Search order is defined byfindURL(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 resourcesearchPaths
- 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 theInputStream
for that file. Search order is defined byfindURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
.- Parameters:
path
- The relative path of the file or resourcelocations
- 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 theInputStream
for that file. Search order is defined byfindURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
.- Parameters:
path
- The relative path of the file or resourcelocations
- The type of locations to limit the search tosearchPaths
- 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 theURI
for that file. Search order is defined byfindURI(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 theURI
for that file. Search order is defined byfindURI(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 resourcesearchPaths
- 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 theURI
for that file. Search order is defined byfindURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
.- Parameters:
path
- The relative path of the file or resourcelocations
- 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 theURI
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
- As a
- 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 searchFileUtil.Location.NONE
effectively requires thatpath
be a portable pathnameFileUtil.Location.INSTALLED
limits the search to theFileUtil.PROGRAM
directory and JARs in the class pathFileUtil.Location.USER
limits the search to theFileUtil.PREFERENCES
,FileUtil.PROFILE
, andFileUtil.SETTINGS
directories (in that order)
- Parameters:
path
- The relative path of the file or resourcelocations
- The types of locations to limit the search tosearchPaths
- 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...)
- For any provided searchPaths, iterate over the searchPaths by
prepending each searchPath to the path and following the following search
order:
-
findURL
public java.net.URL findURL(@Nonnull java.lang.String path)
Search for a file or JAR resource by name and return theURL
for that file. Search order is defined byfindURL(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 theURL
for that file. Search order is defined byfindURL(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 resourcesearchPaths
- 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 theURL
for that file. Search order is defined byfindURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
.- Parameters:
path
- The relative path of the file or resourcelocations
- 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 theURL
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
- As a
- 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 searchFileUtil.Location.NONE
effectively requires thatpath
be a portable pathnameFileUtil.Location.INSTALLED
limits the search to theFileUtil.PROGRAM
directory and JARs in the class pathFileUtil.Location.USER
limits the search to theFileUtil.PROFILE
directory
- Parameters:
path
- The relative path of the file or resourcelocations
- The types of locations to limit the search tosearchPaths
- 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...)
- For any provided searchPaths, iterate over the searchPaths by
prepending each searchPath to the path and following the following search
order:
-
urlToURI
public java.net.URI urlToURI(@Nonnull java.net.URL url)
Return theURI
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 theURL
for a givenFile
. This method catches aMalformedURLException
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 useFiles.delete(java.nio.file.Path)
orFiles.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 useFiles.copy(java.nio.file.Path, java.io.OutputStream)
for files.- Parameters:
source
- the file or directory to copydest
- 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 totext
- 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 rotatemax
- maximum number of backups to retainextension
- 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 createdjava.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
-
-