Class FileUtil
- java.lang.Object
-
- jmri.util.FileUtil
-
public final class FileUtil extends java.lang.Object
Common utility methods for working with Files.All methods in this class call the identical method from the default instance of
FileUtilSupport
.- See Also:
FileUtilSupport
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
FileUtil.Location
The types of locations to use when falling back on default locations infindURI(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
.static class
FileUtil.Property
PropertyChangeEvents for properties that are Profile-specific use a Property to enclose both the Profile and the value of the property.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
HOME
Portable reference to the user's home directory.static java.lang.String
PREFERENCES
Portable reference to the JMRI user's files and preferences directory.static java.lang.String
PROFILE
Portable reference to the current profile directory.static java.lang.String
PROGRAM
Portable reference to items in the JMRI program directory.static java.lang.String
SCRIPTS
Portable reference to the current scripts directory.static char
SEPARATOR
The portable file path component separator.static java.lang.String
SETTINGS
Portable reference to the JMRI applications preferences directory.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
appendTextToFile(java.io.File file, java.lang.String text)
Simple helper method to just append a text string to the end of the given filename.static void
backup(java.io.File file)
Backup a file.static void
copy(java.io.File source, java.io.File dest)
Copy a file or directory.static void
createDirectory(java.io.File dir)
Create a directory if required.static void
createDirectory(java.lang.String path)
Create a directory if required.static boolean
delete(java.io.File path)
Recursively delete a path.static java.net.URL
fileToURL(java.io.File file)
Return theURL
for a givenFile
.static java.net.URI
findExternalFilename(java.lang.String path)
Get the URL of a portable filename if it can be located usingfindURL(java.lang.String)
static java.util.Set<java.io.File>
findFiles(java.lang.String name, java.lang.String root)
Find all files matching the given name under the given root directory within both the user and installed file locations.static java.util.Set<java.io.File>
findFiles(java.lang.String name, java.lang.String root, FileUtil.Location location)
Find all files matching the given name under the given root directory within the specified location.static java.io.InputStream
findInputStream(java.lang.String path)
Search for a file or JAR resource by name and return theInputStream
for that file.static java.io.InputStream
findInputStream(java.lang.String path, java.lang.String... searchPaths)
Search for a file or JAR resource by name and return theInputStream
for that file.static java.io.InputStream
findInputStream(java.lang.String path, FileUtil.Location locations)
Search for a file or JAR resource by name and return theInputStream
for that file.static java.io.InputStream
findInputStream(java.lang.String path, FileUtil.Location locations, java.lang.String... searchPaths)
Search for a file or JAR resource by name and return theInputStream
for that file.static java.net.URI
findURI(java.lang.String path)
Search for a file or JAR resource by name and return theURI
for that file.static java.net.URI
findURI(java.lang.String path, java.lang.String... searchPaths)
Search for a file or JAR resource by name and return theURI
for that file.static java.net.URI
findURI(java.lang.String path, FileUtil.Location locations)
Search for a file or JAR resource by name and return theURI
for that file.static java.net.URI
findURI(java.lang.String path, FileUtil.Location locations, java.lang.String... searchPaths)
Search for a file or JAR resource by name and return theURI
for that file.static java.net.URL
findURL(java.lang.String path)
Search for a file or JAR resource by name and return theURL
for that file.static java.net.URL
findURL(java.lang.String path, java.lang.String... searchPaths)
Search for a file or JAR resource by name and return theURL
for that file.static java.net.URL
findURL(java.lang.String path, FileUtil.Location locations)
Search for a file or JAR resource by name and return theURL
for that file.static java.net.URL
findURL(java.lang.String path, FileUtil.Location locations, java.lang.String... searchPaths)
Search for a file or JAR resource by name and return theURL
for that file.static java.lang.String
getAbsoluteFilename(java.lang.String path)
Convert a portable filename into an absolute filename, usingProfileManager.getActiveProfile()
as the base.static java.lang.String
getAbsoluteFilename(Profile profile, java.lang.String path)
Convert a portable filename into an absolute filename.static FileUtilSupport
getDefault()
Get the default instance of FileUtilSupport.static java.lang.String
getExternalFilename(java.lang.String pName)
Get the resource file corresponding to a name.static java.lang.String
getExternalFilename(Profile profile, java.lang.String pName)
Get the resource file corresponding to a name.static java.io.File
getFile(java.lang.String path)
Get theFile
that path refers to.static java.io.File
getFile(Profile profile, java.lang.String path)
Get theFile
that path refers to.static java.lang.String
getHomePath()
Get the user's home directory.static java.lang.String
getPortableFilename(java.io.File file)
Convert a File object's path to our preferred storage form.static java.lang.String
getPortableFilename(java.io.File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
Convert a File object's path to our preferred storage form.static java.lang.String
getPortableFilename(java.lang.String filename)
Convert a filename string to our preferred storage form.static java.lang.String
getPortableFilename(java.lang.String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
Convert a filename string to our preferred storage form.static java.lang.String
getPortableFilename(Profile profile, java.io.File file)
Convert a File object's path to our preferred storage form.static java.lang.String
getPortableFilename(Profile profile, java.io.File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
Convert a File object's path to our preferred storage form.static java.lang.String
getPortableFilename(Profile profile, java.lang.String filename)
Convert a filename string to our preferred storage form.static java.lang.String
getPortableFilename(Profile profile, java.lang.String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
Convert a filename string to our preferred storage form.static java.lang.String
getPreferencesPath()
Get the preferences directory.static java.lang.String
getProfilePath()
Get the profile directory.static java.lang.String
getProfilePath(Profile profile)
Get the profile directory.static java.lang.String
getProgramPath()
Get the JMRI program directory.static java.lang.String
getScriptsPath()
Get the path to the scripts directory using the Profile returned byProfileManager.getActiveProfile()
as the base.static java.lang.String
getScriptsPath(Profile profile)
Get the path to the scripts directory.static java.net.URI
getURI(java.lang.String path)
Get theFile
that path refers to.static java.net.URL
getURL(java.lang.String path)
Get theURL
that path refers to.static java.net.URL
getURL(java.net.URI uri)
Convenience method to get theURL
from aURI
.static java.lang.String
getUserFilesPath()
Get the user's files directory.static java.lang.String
getUserFilesPath(Profile profile)
Get the user's files directory.static java.lang.String
getUserResourcePath()
Get the resources directory within the user's files directory.static boolean
isPortableFilename(java.lang.String filename)
Test if the given filename is a portable filename.static java.util.jar.JarFile
jmriJarFile()
Get the JMRI distribution jar file.static void
logFilePaths()
Log all paths at the INFO level.static java.lang.String
readFile(java.io.File file)
Read a text file into a String.static java.lang.String
readURL(java.net.URL url)
Read a text URL into a String.static void
rotate(java.io.File file, int max, java.lang.String extension)
Rotate a file and its backups, retaining only a set number of backups.static java.lang.String
sanitizeFilename(java.lang.String name)
Replaces most non-alphanumeric characters in name with an underscore.static void
setProgramPath(java.io.File path)
Set the JMRI program directory.static void
setProgramPath(java.lang.String path)
Set the JMRI program directory.static void
setScriptsPath(Profile profile, java.lang.String path)
Set the path to python scripts.static void
setUserFilesPath(Profile profile, java.lang.String path)
Set the user's files directory.static java.net.URI
urlToURI(java.net.URL url)
Return theURI
for a given URL
-
-
-
Field Detail
-
PROGRAM
public static final java.lang.String PROGRAM
Portable reference to items in the JMRI program directory.- See Also:
- Constant Field Values
-
PREFERENCES
public static final java.lang.String PREFERENCES
Portable reference to the JMRI user's files and preferences directory.- See Also:
- Constant Field Values
-
SETTINGS
public static final java.lang.String SETTINGS
Portable reference to the JMRI applications preferences directory.- See Also:
- Constant Field Values
-
HOME
public static final java.lang.String HOME
Portable reference to the user's home directory.- See Also:
- Constant Field Values
-
PROFILE
public static final java.lang.String PROFILE
Portable reference to the current profile directory.- See Also:
- Constant Field Values
-
SCRIPTS
public static final java.lang.String SCRIPTS
Portable reference to the current scripts directory.- See Also:
- Constant Field Values
-
SEPARATOR
public static final char SEPARATOR
The portable file path component separator.- See Also:
- Constant Field Values
-
-
Method Detail
-
getFile
@Nonnull @CheckReturnValue public static java.io.File getFile(@Nonnull java.lang.String path) throws java.io.FileNotFoundException
Get 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 static 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 static 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 static 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 static 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 static java.util.Set<java.io.File> findFiles(@Nonnull java.lang.String name, @Nonnull java.lang.String root) throws java.lang.IllegalArgumentException
Find all files matching the given name under the given root directory within both the user and installed file locations.- Parameters:
name
- the name of the file to 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 static java.util.Set<java.io.File> findFiles(@Nonnull java.lang.String name, @Nonnull java.lang.String root, @Nonnull FileUtil.Location location)
Find all files matching the given name under the given root directory within the specified location.- Parameters:
name
- the name of the file to 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 static java.lang.String getExternalFilename(@Nonnull java.lang.String pName)
Get the resource file corresponding to a name. There are five cases:- Starts with "program:", treat the rest as a relative pathname below the program directory
- Starts with "preference:", treat the rest as a relative path below the user's files directory
- Starts with "settings:", treat the rest as a relative path below the JMRI system preferences directory
- Starts with "home:", treat the rest as a relative path below the user.home directory
- Starts with "profile:", treat the rest as a relative path below the
profile directory as specified in the
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 home:, profile:, program:, preference:, scripts:, or settings:- Returns:
- Absolute file name to use, or null. This will include system-specific file separators.
- Since:
- 2.7.2
-
getExternalFilename
@Nonnull @CheckReturnValue public static java.lang.String getExternalFilename(@CheckForNull Profile profile, @Nonnull java.lang.String pName)
Get the resource file corresponding to a name. There are five cases:- Starts with "program:", treat the rest as a relative pathname below the program directory
- Starts with "preference:", treat the rest as a relative path below the user's files directory
- Starts with "settings:", treat the rest as a relative path below the JMRI system preferences directory
- Starts with "home:", treat the rest as a relative path below the user.home directory
- Starts with "profile:", treat the rest as a relative path below the
profile directory as specified in the
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 base.pName
- the name, possibly starting with home:, profile:, program:, preference:, scripts:, or settings:- Returns:
- Absolute file name to use, or null. This will include system-specific file separators.
- Since:
- 4.17.3
-
getAbsoluteFilename
@Nonnull @CheckReturnValue public static java.lang.String getAbsoluteFilename(@Nonnull java.lang.String path)
Convert a portable filename into an absolute filename, usingProfileManager.getActiveProfile()
as the base.- Parameters:
path
- the portable filename- Returns:
- An absolute filename
-
getAbsoluteFilename
@Nonnull @CheckReturnValue public static java.lang.String getAbsoluteFilename(@CheckForNull Profile profile, @Nonnull java.lang.String path)
Convert a portable filename into an absolute filename.- Parameters:
profile
- the profile to use the basepath
- the portable filename- Returns:
- An absolute filename
-
getPortableFilename
@Nonnull @CheckReturnValue public static java.lang.String getPortableFilename(@Nonnull java.io.File file)
Convert a File object's path to our preferred storage form.This is the inverse of
getFile(String pName)
. Deprecated forms are not created.- Parameters:
file
- File at path to be represented- Returns:
- Filename for storage in a portable manner. This will include portable, not system-specific, file separators.
- Since:
- 2.7.2
-
getPortableFilename
@Nonnull @CheckReturnValue public static java.lang.String getPortableFilename(@Nonnull java.io.File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
Convert a File object's path to our preferred storage form.This is the inverse of
getFile(String pName)
. Deprecated forms are not created.This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the
ProfileManager
to write an incorrect path for the current profile 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 static java.lang.String getPortableFilename(@Nonnull java.lang.String filename)
Convert a filename string to our preferred storage form.This is the inverse of
getExternalFilename(String pName)
. Deprecated forms are not created.- Parameters:
filename
- Filename to be represented- Returns:
- Filename for storage in a portable manner
- Since:
- 2.7.2
-
getPortableFilename
@Nonnull @CheckReturnValue public static java.lang.String getPortableFilename(@Nonnull java.lang.String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
Convert a filename string to our preferred storage form.This is the inverse of
getExternalFilename(String pName)
. Deprecated forms are not created.This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the
ProfileManager
to write an incorrect path for the current profile 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 static java.lang.String getPortableFilename(@CheckForNull Profile profile, @Nonnull java.io.File file)
Convert a File object's path to our preferred storage form.This is the inverse of
getFile(String pName)
. Deprecated forms are not created.- Parameters:
profile
- Profile to use as a 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 static java.lang.String getPortableFilename(@CheckForNull Profile profile, @Nonnull java.io.File file, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
Convert a File object's path to our preferred storage form.This is the inverse of
getFile(String pName)
. Deprecated forms are not created.This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the
ProfileManager
to write an incorrect path for the current profile 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 a 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:
- 4.17.3
-
getPortableFilename
@Nonnull @CheckReturnValue public static java.lang.String getPortableFilename(@CheckForNull Profile profile, @Nonnull java.lang.String filename)
Convert a filename string to our preferred storage form.This is the inverse of
getExternalFilename(String pName)
. Deprecated forms are not created.- Parameters:
profile
- the Profile to use as a basefilename
- Filename to be represented- Returns:
- Filename for storage in a portable manner
- Since:
- 4.17.3
-
getPortableFilename
@Nonnull @CheckReturnValue public static java.lang.String getPortableFilename(@CheckForNull Profile profile, @Nonnull java.lang.String filename, boolean ignoreUserFilesPath, boolean ignoreProfilePath)
Convert a filename string to our preferred storage form.This is the inverse of
getExternalFilename(String pName)
. Deprecated forms are not created.This method supports a specific use case concerning profiles and other portable paths that are stored within the User files directory, which will cause the
ProfileManager
to write an incorrect path for the current profile orFileLocationPaneXml
to write an incorrect path for the Users file directory. In most cases, the use ofgetPortableFilename(java.io.File)
is preferable.- Parameters:
profile
- the profile to use as a 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 static boolean isPortableFilename(@Nonnull java.lang.String filename)
Test if the given filename is a portable filename.- Parameters:
filename
- the name to test- Returns:
- true if filename is portable
-
getHomePath
@Nonnull @CheckReturnValue public static java.lang.String getHomePath()
Get the user's home directory.- Returns:
- User's home directory as a String
-
getUserFilesPath
@Nonnull @CheckReturnValue public static java.lang.String getUserFilesPath()
Get the user's files directory. If not set by the user, this is the same as the profile path for the Profile specified byProfileManager.getActiveProfile()
.- Returns:
- User's files directory as a String
- See Also:
getProfilePath()
-
getUserFilesPath
@Nonnull @CheckReturnValue public static java.lang.String getUserFilesPath(@CheckForNull Profile profile)
Get the user's files directory. If not set by the user, this is the same as the profile path.- Parameters:
profile
- the profile to use as a base- Returns:
- User's files directory as a String
- See Also:
getProfilePath()
-
setUserFilesPath
public static void setUserFilesPath(@CheckForNull Profile profile, @Nonnull java.lang.String path)
Set the user's files directory.- Parameters:
profile
- The profile to use as a basepath
- The path to the user's files directory- See Also:
getUserFilesPath()
-
getProfilePath
@Nonnull @CheckReturnValue public static java.lang.String getProfilePath()
Get the profile directory. Uses the Profile returned byProfileManager.getActiveProfile()
as a base. If that is null, gets the preferences path.- Returns:
- Profile directory
- See Also:
getPreferencesPath()
-
getProfilePath
@Nonnull @CheckReturnValue public static java.lang.String getProfilePath(@CheckForNull Profile profile)
Get the profile directory. If the profile is null or has a null directory, this is the same as the preferences path.- Parameters:
profile
- the profile to use as a base- Returns:
- Profile directory
- See Also:
getPreferencesPath()
-
getPreferencesPath
@Nonnull @CheckReturnValue public static java.lang.String getPreferencesPath()
Get the preferences directory. This directory is set based on the OS and is not normally settable by the user.- On Microsoft Windows systems, this is
JMRI
in the User's home directory. - On OS X systems, this is
Library/Preferences/JMRI
in the User's home directory. - On Linux, Solaris, and other UNIXes, this is
.jmri
in the User's home directory. - This can be overridden with by setting the
jmri.prefsdir
Java property when starting JMRI.
getHomePath()
to get the User's home directory.- Returns:
- Path to the preferences directory.
- See Also:
getHomePath()
- On Microsoft Windows systems, this is
-
getProgramPath
@Nonnull @CheckReturnValue public static java.lang.String getProgramPath()
Get the JMRI program directory. If the program directory has not been previously sets, first sets the program directory to the value specified in the Java System propertyjmri.path.program
, or.
if that property is not set.- Returns:
- JMRI program directory as a String.
-
setProgramPath
public static void setProgramPath(@Nonnull java.lang.String path)
Set the JMRI program directory.Convenience method that calls
setProgramPath(java.io.File)
with the passed in path.- Parameters:
path
- the path to the JMRI installation
-
setProgramPath
public static void setProgramPath(@Nonnull java.io.File path)
Set the JMRI program directory.If set, allows JMRI to be loaded from locations other than the directory containing JMRI resources. This must be set very early in the process of loading JMRI (prior to loading any other JMRI code) to be meaningfully used.
- Parameters:
path
- the path to the JMRI installation
-
findExternalFilename
@Nonnull @CheckReturnValue public static java.net.URI findExternalFilename(@Nonnull java.lang.String path)
Get the URL of a portable filename if it can be located usingfindURL(java.lang.String)
- Parameters:
path
- the path to find- Returns:
- URL of portable or absolute path
-
findInputStream
public static java.io.InputStream findInputStream(@Nonnull java.lang.String path)
Search for a file or JAR resource by name and return 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 static java.io.InputStream findInputStream(@Nonnull java.lang.String path, @Nonnull java.lang.String... searchPaths)
Search for a file or JAR resource by name and return 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 static java.io.InputStream findInputStream(@Nonnull java.lang.String path, 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 static java.io.InputStream findInputStream(@Nonnull java.lang.String path, FileUtil.Location locations, @Nonnull java.lang.String... searchPaths)
Search for a file or JAR resource by name and return 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...)
-
getUserResourcePath
@Nonnull @CheckReturnValue public static java.lang.String getUserResourcePath()
Get the resources directory within the user's files directory.- Returns:
- path to [user's file]/resources/
-
findURI
public static java.net.URI findURI(@Nonnull java.lang.String path)
Search for a file or JAR resource by name and return 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 static java.net.URI findURI(@Nonnull java.lang.String path, @Nonnull java.lang.String... searchPaths)
Search for a file or JAR resource by name and return 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 static java.net.URI findURI(@Nonnull java.lang.String path, @Nonnull FileUtil.Location locations)
Search for a file or JAR resource by name and return 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 static java.net.URI findURI(@Nonnull java.lang.String path, @Nonnull FileUtil.Location locations, @Nonnull java.lang.String... searchPaths)
Search for a file or JAR resource by name and return 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 thePROGRAM
directory and JARs in the class pathFileUtil.Location.USER
limits the search to thePREFERENCES
,PROFILE
, andSETTINGS
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 static 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.TODO: add @CheckForNull annotation / fix Possible null pointers.
- Parameters:
path
- The relative path of the file or resource.- Returns:
- The URL or null.
- See Also:
findURL(java.lang.String, java.lang.String...)
,findURL(java.lang.String, jmri.util.FileUtil.Location)
,findURL(java.lang.String, jmri.util.FileUtil.Location, java.lang.String...)
-
findURL
public static java.net.URL findURL(@Nonnull java.lang.String path, @Nonnull java.lang.String... searchPaths)
Search for a file or JAR resource by name and return 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 static java.net.URL findURL(@Nonnull java.lang.String path, @Nonnull FileUtil.Location locations)
Search for a file or JAR resource by name and return 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 static java.net.URL findURL(@Nonnull java.lang.String path, @Nonnull FileUtil.Location locations, @Nonnull java.lang.String... searchPaths)
Search for a file or JAR resource by name and return 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 thePROGRAM
directory and JARs in the class pathFileUtil.Location.USER
limits the search to thePROFILE
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 static 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 static 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
-
jmriJarFile
public static java.util.jar.JarFile jmriJarFile()
Get the JMRI distribution jar file.- Returns:
- the JAR file containing the JMRI library or null if not running from a JAR file
-
logFilePaths
public static void logFilePaths()
Log all paths at the INFO level.
-
getScriptsPath
@Nonnull @CheckReturnValue public static java.lang.String getScriptsPath()
Get the path to the scripts directory using the Profile returned byProfileManager.getActiveProfile()
as the base.- Returns:
- the scriptsPath
-
getScriptsPath
@Nonnull @CheckReturnValue public static java.lang.String getScriptsPath(@CheckForNull Profile profile)
Get the path to the scripts directory.- Parameters:
profile
- the Profile to use as the base- Returns:
- the scriptsPath
-
setScriptsPath
public static void setScriptsPath(@CheckForNull Profile profile, @CheckForNull java.lang.String path)
Set the path to python scripts.- Parameters:
profile
- the profile to set the path forpath
- the scriptsPath to set
-
readFile
public static java.lang.String readFile(@Nonnull java.io.File file) throws java.io.IOException
Read a text file into a String.- Parameters:
file
- The text file.- Returns:
- The contents of the file.
- Throws:
java.io.IOException
- if the file cannot be read
-
readURL
public static java.lang.String readURL(@Nonnull java.net.URL url) throws java.io.IOException
Read a text URL into a String. Would be significantly simpler with Java 7. File is assumed to be encoded using UTF-8- Parameters:
url
- The text URL.- Returns:
- The contents of the file.
- Throws:
java.io.IOException
- if the URL cannot be read
-
sanitizeFilename
@Nonnull public static java.lang.String sanitizeFilename(@Nonnull java.lang.String name)
Replaces most non-alphanumeric characters in name with an underscore.- Parameters:
name
- The filename to be sanitized.- Returns:
- The sanitized filename.
-
createDirectory
public static void createDirectory(@Nonnull java.lang.String path)
Create a directory if required. Any parent directories will also be created.- Parameters:
path
- directory to create
-
createDirectory
public static void createDirectory(@Nonnull java.io.File dir)
Create a directory if required. Any parent directories will also be created.- Parameters:
dir
- directory to create
-
delete
public static boolean delete(@Nonnull java.io.File path)
Recursively delete a path. It is recommended to 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 static void copy(@Nonnull java.io.File source, @Nonnull java.io.File dest) throws java.io.IOException
Copy a file or directory. It is recommended to 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 static void appendTextToFile(@Nonnull java.io.File file, @Nonnull java.lang.String text) throws java.io.IOException
Simple helper method to just append a text string to the end of the given filename. The file will be created if it does not exist.- Parameters:
file
- File to append text totext
- Text to append- Throws:
java.io.IOException
- if file cannot be written to
-
backup
public static void backup(@Nonnull java.io.File file) throws java.io.IOException
Backup a file. The backup is in the same location as the original file, has the extension.bak
appended to the file name, and up to four revisions are retained. The lowest numbered revision is the most recent.- Parameters:
file
- the file to backup- Throws:
java.io.IOException
- if a backup cannot be created- See Also:
FileUtilSupport.backup(java.io.File)
-
rotate
public static void rotate(@Nonnull java.io.File file, int max, @CheckForNull java.lang.String extension) throws java.io.IOException
Rotate a file and its backups, retaining only a set number of backups.- Parameters:
file
- the file to 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:
FileUtilSupport.rotate(java.io.File, int, java.lang.String)
,FileUtilSupport.backup(java.io.File)
-
getDefault
public static FileUtilSupport getDefault()
Get the default instance of FileUtilSupport.- Returns:
- the default instance of FileUtilSupport
-
-