Try to locate a file.
When using the normal NetBeans installation structure and NBM file format,
this path will be relative to the installation directory (or user directory,
for a locally installed module). Other possible installation mechanisms, such
as JNLP (Java WebStart), might arrange the physical files differently, but
generally the path indicated by a module's normal NBM file (beneath netbeans/
in the NBM) should be interpreted by the locator implementation to point to the actual
location of the file, so the module need not be aware of such details. Some
locator implementations may perform the search more accurately or quickly
when given a code name base for the module that supplies the file.
The file may refer to a directory (no trailing slash!), in which case the locator
should attempt to find that directory in the installation. Note that only one
file may be located from a given path, so generally this method will not be
useful where a directory can contain many items that may be merged between e.g.
the installation and user directories. For example, the docs folder
(used e.g. for Javadoc) might contain several ZIP files in both the installation and
user areas. There is currently no supported way to enumerate all such files. Therefore
searching for a directory should be attempted only when there is just one module which
is expected to provide that directory and all of its contents. The module may assume
that all contained files are in the same relative structure in the directory as in
the normal NBM-based installation; unusual locator implementations may need to create
temporary directories with matching structures to return from this method, in case the
physical file locations are not in such a directory structure.
See issue #36701 for details.
Localized and branded lookups should follow the normal naming conventions,
e.g. docs/OpenAPIs_ja.zip would be used for Japanese Javadoc
and locate("docs/OpenAPIs.zip", …, true)
would find it when running in Japanese locale.
For cases where the search is for a module JAR or one of its extensions, client
code may prefer to use the code source given by a class loader. This will permit
a client to find the base URL (may or may not refer to a file) responsible for loading
the contents of the protection domain, typically a JAR file, containing a class
which is accessible to the module class loader. For example:
Class c = ClassMyModuleDefines.class;
URL u = c.getProtectionDomain().getCodeSource().getLocation();
When running from a JAR file, this will typically give e.g.
file:/path/to/archive.jar. This information may be useful,
but it is not conclusive, since there is no guarantee what the URL protocol
will be, nor that the returned URL uniquely identifies a JAR shipped with
the module in its canonical NBM format. InstalledFileLocator
provides stronger guarantees than this technique, since you can explicitly
name a JAR file to be located on disk.
This class should not be used just to find resources on the system
filesystem, which in the normal NetBeans installation structure means the
result of merging ${netbeans.home}/system/ with ${netbeans.user}/system/
as well as module layers and perhaps project-specific storage. To find data in
the system filesystem, use the Filesystems API, e.g. in your layer you can predefine:
<filesystem>
<folder name="MyModule">
<file name="data.xml" url="contents-in-module-jar.xml"/>
</folder>
</filesystem>
Then in your code use:
String path = "MyModule/data.xml";
FileSystem sfs = Repository.getDefault().getDefaultFileSystem();
FileObject fo = sfs.findResource(path);
if (fo != null) {
// use fo.getInputStream() etc.
// FileUtil.toFile(fo) will often be null, do not rely on it!
}