addFileChangeListener

Adds a listener to changes in a given path. It permits you to listen to a file
which does not yet exist, or continue listening to it after it is deleted and recreated, etc.
When given path represents a file (path.isDirectory() == false)

fileDataCreated event is fired when the file is created

fileDeleted event is fired when the file is deleted

fileChanged event is fired when the file is modified

fileRenamed event is fired when the file is renamed

fileAttributeChanged is fired when FileObject's attribute is changed

When given path represents a folder (path.isDirectory() == true)

fileFolderCreated event is fired when the folder is created or a child folder created

fileDataCreated event is fired when a child file is created

fileDeleted event is fired when the folder is deleted or a child file/folder removed

fileChanged event is fired when a child file is modified

fileRenamed event is fired when the folder is renamed or a child file/folder is renamed

fileAttributeChanged is fired when FileObject's attribute is changed

Can only add a given [listener, path] pair once. However a listener can
listen to any number of paths. Note that listeners are always held weakly
- if the listener is collected, it is quietly removed.

addRecursiveListener

Adds a listener to changes under given path. It permits you to listen to a file
which does not yet exist, or continue listening to it after it is deleted and recreated, etc.
When given path represents a file (path.isDirectory() == false), this
code behaves exactly like addFileChangeListener(org.openide.filesystems.FileChangeListener, java.io.File).
Usually the path shall represent a folder (path.isDirectory() == true)

fileFolderCreated event is fired when the folder is created or a child folder created

fileDataCreated event is fired when a child file is created

fileDeleted event is fired when the folder is deleted or a child file/folder removed

fileChanged event is fired when a child file is modified

fileRenamed event is fired when the folder is renamed or a child file/folder is renamed

fileAttributeChanged is fired when FileObject's attribute is changed

The above events are delivered for changes in all subdirectories (recursively).
It is guaranteed that with each change at least one event is generated.
For example adding a folder does not notify about content of the folder,
hence one event is delivered.
Can only add a given [listener, path] pair once. However a listener can
listen to any number of paths. Note that listeners are always held weakly
- if the listener is collected, it is quietly removed.

As registering of the listener can take a long time, especially on deep
hierarchies, it is possible provide a callback stop.
This stop object is guaranteed to be called once per every folder on the
default (when masterfs module is included) implemention. If the call
to stop.call() returns true, then the registration of
next recursive items is interrupted. The listener may or may not get
some events from already registered folders.

Those who provide recurseInto callback can prevent
the system to enter, and register operating system level listeners
to certain subtrees under the provided path. This does
not prevent delivery of changes, if they are made via the filesystem API.
External changes however will not be detected.

Parameters:

listener - FileChangeListener to listen to changes in path

path - File path to listen to (even not existing)

stop - an interface to interrupt the process of registering
the listener. If the call returns true, the process
of registering the listener is immediately interrupted. null
value disables this kind of callback.

recurseInto - a file filter that may return false when
a folder should not be traversed into and external changes in it ignored.
null recurses into all subfolders

createFolder

Returns FileObject for a folder.
If such a folder does not exist then it is created, including any necessary but nonexistent parent
folders. Note that if this operation fails it may have succeeded in creating some of the necessary
parent folders.

createData

Returns FileObject for a data file.
If such a data file does not exist then it is created, including any necessary but nonexistent parent
folders. Note that if this operation fails it may have succeeded in creating some of the necessary
parent folders.

createMemoryFileSystem

Factory method that creates an empty implementation of a filesystem that
completely resides in a memory.

To specify the MIME type of a data file without using a MIME resolver,
set the mimeType file attribute.

Since 7.42, a URLMapper is available for files (and folders)
in memory filesystems. These URLs are valid only so long as the filesystem
has not been garbage-collected, so hold the filesystem (or a file in it)
strongly for as long as you expect the URLs to be in play.

createFolder

Returns a folder on given filesystem if such a folder exists.
If not then a folder is created, including any necessary but nonexistent parent
folders. Note that if this operation fails it may have succeeded in creating some of the necessary
parent folders.
The name of the new folder can be
specified as a multi-component pathname whose components are separated
by File.separatorChar or "/" (forward slash).

createData

Returns a data file on given filesystem if such a data file exists.
If not then a data file is created, including any necessary but nonexistent parent
folders. Note that if this operation fails it may have succeeded in creating some of the necessary
parent folders. The name of
data file can be composed as resource name (e. g. org/netbeans/myfolder/mydata ).

toFileObject

If you are running with org.netbeans.modules.masterfs enabled,
this method should never return null for a file which exists on disk.
For example, to make this method work in unit tests in an Ant-based module project,
right-click Unit Test Libraries, Add Unit Test Dependency, check Show Non-API Modules, select Master Filesystem.
(Also right-click the new Master Filesystem node, Edit, uncheck Include in Compile Classpath.)
To ensure masterfs (or some other module that can handle the conversion)
is present put following line into your module manifest:

OpenIDE-Module-Needs: org.openide.filesystems.FileUtil.toFileObject

Parameters:

file - a disk file (may or may not exist). This file
must be normalized.

Returns:

a corresponding file object, or null if the file does not exist
or there is no URLMapper available to convert it

copyAttributes

Copies attributes from one file to another.
Note: several special attributes will not be copied, as they should
semantically be transient. These include attributes used by the
template wizard (but not the template attribute itself).

extractJar

Deprecated.Use of XML filesystem layers generally obsoletes this method.
For tests, use test.TestFileUtils.

Extract jar file into folder represented by file object. If the JAR contains
files with name filesystem.attributes, it is assumed that these files
has been created by DefaultAttributes implementation and the content
of these files is treated as attributes and added to extracted files.

findFreeFileName

Finds an unused file name similar to that requested in the same folder.
The specified file name is used if that does not yet exist or is
isVirtual.
Otherwise, the first available name of the form basename_nnn.ext (counting from one) is used.

Caution: this method does not lock the parent folder
to prevent race conditions: i.e. it is possible (though unlikely)
that the resulting name will have been created by another thread
just as you were about to create the file yourself (if you are,
in fact, intending to create it just after this call). Since you
cannot currently lock a folder against child creation actions,
the safe approach is to use a loop in which a free name is
retrieved; an attempt is made to create
that file; and upon an IOException during
creation, retry the loop up to a few times before giving up.

getMIMEType

Resolves MIME type. Registered resolvers are invoked and used to achieve this goal.
Resolvers must subclass MIMEResolver. By default it is possible for the
method to return content/unknown instead of null - if
you want to avoid such behavior, include null in the
list of requested withinMIMETypes - in such case the
return value is guaranteed to be one of the values in withinMIMETypes
or null.

Example: Check if some file is Java source file or text file:

FileUtil.getMIMEType(fo, null, "text/x-java", "text/plain") != null

Parameters:

fo - whose MIME type should be recognized

withinMIMETypes - an array of MIME types. Only resolvers whose
MIMEResolver.getMIMETypes() contain one or more of the requested
MIME types will be asked if they recognize the file. It is possible for
the resulting MIME type to not be a member of this list.

Returns:

the MIME type for the FileObject, or null if
the FileObject is unrecognized.

Since:

7.13

setMIMEType

Registers specified extension to be recognized as specified MIME type.
If MIME type parameter is null, it cancels previous registration.
Note that you may register a case-sensitive extension if that is
relevant (for example *.C for C++) but if you register
a lowercase extension it will by default apply to uppercase extensions
too on Windows.

Parameters:

extension - the file extension to be registered

mimeType - the MIME type to be registered for the extension or null to deregister

nbfsURLStreamHandler

isParentOf

Recursively checks whether the file is underneath the folder. It checks whether
the file and folder are located on the same filesystem, in such case it checks the
parent FileObject of the file recursively until the folder is found
or the root of the filesystem is reached.

getFileDisplayName

Get an appropriate display name for a file object.
If the file corresponds to a path on disk, this will be the disk path.
Otherwise the name will mention the filesystem name or archive name in case
the file comes from archive and relative path. Relative path will be mentioned
just in case that passed FileObject isn't root FileObject.isRoot().

normalizeFile

Normalize a file path to a clean form.
This method may for example make sure that the returned file uses
the natural case on Windows; that old Windows 8.3 filenames are changed to the long form;
that relative paths are changed to be
absolute; that . and .. sequences are removed; etc.
Unlike File.getCanonicalFile() this method will not traverse symbolic links on Unix.

This method involves some overhead and should not be called frivolously.
Generally it should be called on incoming pathnames that are gotten from user input
(including filechoosers), configuration files, Ant properties, etc. Internal
calculations should not need to renormalize paths since File.listFiles(),
File.getParentFile(), etc. will not produce abnormal variants.

getArchiveFile

Returns a FileObject representing an archive file containing the
FileObject given by the parameter.
Remember that any path within the archive is discarded
so you may need to check for non-root entries.

Parameters:

fo - a file in an archive filesystem

Returns:

the file corresponding to the archive itself,
or null if fo is not an archive entry

Since:

4.48

getArchiveFile

Returns the URL of the archive file containing the file
referred to by an archive (eg. jar) protocol URL.
Remember that any path within the archive is discarded
so you may need to check for non-root entries.

Parameters:

url - a URL

Returns:

the embedded archive URL, or null if the URL is not an
archive protocol URL containing !/

isArchiveFile

Tests if a URL represents a java archive.
By default the JAR or ZIP archives are supported.
If there is no such file object, the test is done by heuristic: any URL with an extension is
treated as an archive.

urlForArchiveOrDir

Convert a file such as would be shown in a classpath entry into a proper folder URL.
If the file looks to represent a directory, a file URL will be created.
If it looks to represent a ZIP archive, a jar URL will be created.

Parameters:

entry - a file or directory name

Returns:

an appropriate classpath URL which will always end in a slash (/),
or null for an existing file which does not look like a valid archive

Since:

org.openide.filesystems 7.8

archiveOrDirForURL

Convert a classpath-type URL to a corresponding file.
If it is a jar URL representing the root folder of a local disk archive,
that archive file will be returned.
If it is a file URL representing a local disk folder,
that folder will be returned.

Parameters:

entry - a classpath entry or similar URL

Returns:

a corresponding file, or null for e.g. a network URL or non-root JAR folder entry

getOrder

Normally this is done by looking for numeric file attributes named position
on the children; children with a lower position number are placed first.
Now-deprecated relative ordering attributes of the form earlier/later may
also be used; if the above attribute has a boolean value of true,
then the file named earlier will be sorted somewhere (not necessarily directly)
before the file named later. Numeric and relative attributes may also be mixed.

The sort is stable at least to the extent that if there is no ordering information
whatsoever, the returned list will be in the same order as the incoming collection.

setOrder

Imposes an order on some sibling file objects.
After this call, if no other changes have intervened,
getOrder(java.util.Collection<org.openide.filesystems.FileObject>, boolean) on these files should return a list in the same order.
Beyond the fact that this call may manipulate the position attributes
of files in the folder, and may delete deprecated relative ordering attributes on the folder,
the exact means of setting the order is unspecified.

In environment with multiple contextual Lookups, the method may return different FileObject depending
on what Lookup serves the executing thread. If the system-wide (user-independent) configuration
is required instead, getSystemConfigFile(java.lang.String) should be called instead. If an service instance is created based
on the configuration, it is important to decide whether the service instance should live for each context
independently (possibly with some private means of communication between instances/users) or all users
should share the same instance. In the later case, getSystemConfigFile(java.lang.String) must be used.

Parameters:

path - the path from the root of the NetBeans default (system, configuration)
filesystem delimited by '/' or empty string to get root folder.

Returns:

a FileObject for given path in the NetBeans default (system, configuration)
filesystem or null if does not exist

getSystemConfigFile

Returns FileObject from the default filesystem, or null if the file does not exist.
Unlike getConfigFile(java.lang.String), this call returns a FileObject from the system-wide configuration.
Because default/config filesystem is used both for configuration and services, Lookup or service providers
should use this method in preference to getConfigFile(java.lang.String) to produce singleton services even
in multiple context environment.

In multi-user setup, this method returns instance specific for the executing user.
Important: it returns user-specific instance even though the object is configured in
a XML layer, or system-wide configuration; still, the instance will be tied to the user-specific
file as served by getConfigFile(java.lang.String).

getConfigRoot

Returns the root of the NetBeans default (system, configuration)
filesystem. It returns configuration root using the current Repository, in the case
that multiple Repository instances are created to support multiple execution contexts
in the same JVM.

Returns:

a FileObject for the root of the NetBeans default (system, configuration)
filesystem