public abstract class InstalledFileLocator extends Object
For use in declarative formats, or from APIs which require URLs,
there is a matching URL protocol nbinst. The host field (optional but
recommended) should be the code name base of the module owning the file; the
path is then relative to that module's cluster. For example,
nbinst://my.module/docs/README should refer to the file found by
InstalledFileLocator.getDefault().locate("docs/README", "my.module", false).
| Modifier | Constructor and Description |
|---|---|
protected |
InstalledFileLocator()
No-op constructor for use by subclasses.
|
| Modifier and Type | Method and Description |
|---|---|
static InstalledFileLocator |
getDefault()
Get a master locator.
|
abstract File |
locate(String relativePath,
String codeNameBase,
boolean localized)
Try to locate a file.
|
Set<File> |
locateAll(String relativePath,
String codeNameBase,
boolean localized)
Similar to
InstalledFileLocator.locate(java.lang.String, java.lang.String, boolean) but can return multiple results. |
protected InstalledFileLocator()
public abstract File locate(String relativePath, String codeNameBase, boolean localized)
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. Use InstalledFileLocator.locateAll(java.lang.String, java.lang.String, boolean) if you need all results. 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";
FileObject fo = FileUtil.getConfigFile(path);
if (fo != null) {
// use fo.getInputStream() etc.
// FileUtil.toFile(fo) will often be null, do not rely on it!
}
relativePath - path from install root, e.g. docs/OpenAPIs.zip
or modules/ext/somelib.jar
(always using / as a separator, regardless of platform)codeNameBase - name of the supplying module, e.g. org.netbeans.modules.foo;
may be null if unknownlocalized - true to perform a localized and branded lookup (useful for documentation etc.)File, if it can be found, else nullpublic Set<File> locateAll(String relativePath, String codeNameBase, boolean localized)
InstalledFileLocator.locate(java.lang.String, java.lang.String, boolean) but can return multiple results.
The default implementation returns a list with zero or one elements according to InstalledFileLocator.locate(java.lang.String, java.lang.String, boolean).relativePath - a path from install rootcodeNameBase - name of the supplying module or nulllocalized - true to perform a localized/branded searchpublic static InstalledFileLocator getDefault()
org.openide.modules.InstalledFileLocator
to require any autoload modules which can provide locators.