InstalledFileLocator (NetBeans APIs) - NetBeans API Javadoc 4.1.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.openide.modules
Class InstalledFileLocator

java.lang.Object
  org.openide.modules.InstalledFileLocator

public abstract class InstalledFileLocator
extends Object

Service providing the ability to locate a module-installed file in the NetBeans application's installation. Zero or more instances may be registered to lookup.

Since:: 3.21
See Also:: Issue #28683

Constructor Summary

protected InstalledFileLocator()
          No-op constructor for use by subclasses.

Method Summary

static InstalledFileLocator getDefault()
          Get a master locator.

abstract File locate(String relativePath, String codeNameBase, boolean localized)
          Try to locate a file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

InstalledFileLocator

protected InstalledFileLocator()

No-op constructor for use by subclasses.

Method Detail

locate

public abstract File locate(String relativePath,
                            String codeNameBase,
                            boolean localized)

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!
}

Parameters:: relativePath - path from install root, e.g. docs/OpenAPIs.zip or modules/autoload/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 unknown; localized - true to perform a localized and branded lookup (useful for documentation etc.)
Returns:: the requested File, if it can be found, else null

getDefault

public static InstalledFileLocator getDefault()

Get a master locator. Lookup is searched for all registered locators. They are merged together and called in sequence until one of them is able to service a request. If you use this call, require the token org.openide.modules.InstalledFileLocator to require any autoload modules which can provide locators.

Returns:: a master merging locator (never null)