Skip navigation links
org.openide.util.lookup 8.36.1

Lookup API
Official

See: Description

Lookup API 
Package Description
org.openide.util
Client API part of the Lookup interfaces.
org.openide.util.lookup
Support classes for the Registration and Lookup extension mechanism.

This module defines the Lookup which is the NetBeans way for dynamic registration and lookup of components in our modularized component system. It allows lookup and discovery of features by description of their interfaces. The classes are devided into two parts. The LookupAPI allows the discovery and the LookupSPI simplifies creation and registration of own lookup objects.

What is New (see all changes)?

Use Cases

Cover of NetBeans Platform for Beginners book There is a great introduction to Lookup and its usage in its javadoc. For details on this topic, together with code samples, see chapter 4, of NetBeans Platform for Beginners by Jason Wexbridge and Walter Nyland. In addition to that here is a list of frequently asked or interesting questions slowly expanding as people ask them:

Lookup faq:

How to specify that a service in Lookup should be available only on Windows?
Q: Most of the time I specify interfaces that I want to add to the Lookup class in the layer.xml file. But, let's say I have a platform-specific interface (something on Windows only, for instance).

How can I specify (in the xml, or programmatically) that this service should only be added to the Lookup if the platform is Windows? >

In general there are three ways to achieve this.
  • It is possible to write a specific module and enable it only on windows. See os specific modules documentation. Then you can put a registration of your instance into your module's META-INF/services directory and it will be available only on Windows.

  • Another possibility that does not require new module, but which executes a code on startup (which may have performance implications) is to use methodvalue attribute. Register your instance in layer using your-Object.instance file as described at services documentation and in your factory method either return the instance your want or null depending on result of Utilities.isWindows() call.

  • In some cases, the interface for which you will register an implementation permits a no-operation semantics. For example, InstalledFileLocator.locate(...) can return a valid File, or null. You could always register an InstalledFileLocator instance yet disable it on non-Windows platforms (always returning null).

How shall I write an extension point for my module?

Q: I have more modules one of them providing the core functionality and few more that wish to extend it. What is the right way to do it? How does the Netbeans platform declare such extension point?

Start with declaring an extension interface in your core module and put it into the module's public packages. Imagine for example that the core module is in JAR file org-my-netbeans-coremodule.jar and already contains in manifests line like OpenIDE-Module: org.my.netbeans.coremodule/1 and wants to display various tips of the day provided by other modules and thus defines:

 

package org.my.netbeans.coremodule;

public interface TipsOfTheDayProvider {
    public String provideTipOfTheDay ();
}

And in its manifest adds line OpenIDE-Module-Public-Packages: org.my.netbeans.coremodule.* to specify that this package contains exported API and shall be accessible to other modules.

When the core module is about to display the tip of the day it can ask the system for all registered instances of the TipsOfTheDayProvider, randomly select one of them:


import java.util.Collection;
import java.util.Collections;
import org.openide.util.Lookup;

Lookup.Result result = Lookup.getDefault ().lookup (new Lookup.Template (TipsOfTheDayProvider.class));
Collection c = result.allInstances ();
Collections.shuffle (c);
TipsOfTheDayProvider selected = (TipsOfTheDayProvider)c.iterator ().next ();

and then display the tip. Simple, trivial, just by the usage of Lookup interface once creates a registry that other modules can enhance. But such enhancing of course requires work on the other side. Each module that would like to register its TipsOfTheDayProvider needs to depend on the core module - add OpenIDE-Module-Module-Dependencies: org.my.netbeans.coremodule/1 into its manifest and write a class with its own implementation of the provider:


package org.my.netbeans.extramodule;

class ExtraTip implements TipsOfTheDayProvider {
    public String provideTipOfTheDay () {
        return "Do you know that in order to write extension point you should use Lookup?";
    }
}

Then, the only necessary thing is to register such class by using the J2SE standard into plain text file META-INF/services/org.my.netbeans.coremodule.TipsOfTheDayProvider in the module JAR containing just one line:

org.my.netbeans.extramodule.ExtraTip

and your modules are now ready to communicate using your own extension point.

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...
Group of java interfaces
Interface NameIn/OutStabilitySpecified in What Document?
LookupAPIExportedOfficial .../util/lookup/doc-files/lookup-api.html

allows the discovery

LookupSPIExportedOfficial .../util/lookup/doc-files/lookup-spi.html

simplifies creation and registration of own lookup objects

ProviderRegistrationRemovalExportedUnder Development .../org/openide/util/doc-files/api.html

Lookups.metaInfServicesExportedUnder Development .../org/openide/util/lookup/Lookups.html

calls constructor of registered classes using reflection

Lookup.resetDefaultLookupExportedFriend

There is a static private method Lookup.resetDefaultLookup that is called by NbJUnit's MockServices to properly reset default lookup and fire changes to all registred listeners.

Group of java.io.File interfaces
Interface NameIn/OutStabilitySpecified in What Document?
FileLocationExportedUnder Development

the JAR file is located in platform cluster under lib/org-openide-util-lookup.jar

Group of systemproperty interfaces
Interface NameIn/OutStabilitySpecified in What Document?
org.openide.util.LookupExportedUnder Development

checked by the initialization of the Lookup.getDefault() and can contain name of a class that extends org.openide.util.Lookup and has public constructor, that should be instantiated and returned from Lookup.getDefault() the class will be loaded by Thread.currentThread().getContextClassLoader() classloader the first time Lookup.getDefault is invoked.

The property can also contain value "-" which means to completely disable the lookup instantiation and return Lookup.EMPTY from Lookup.getDefault().

If the property is unspecified, the default MetaInfServicesLookup is constructed for Thread.currentThread().getContextclassLoader() that implements the JDK's standard. If, by a chance an instance of Lookup.Provider is found in there, its lookup is returned as result. Otherwise the MetaInfServicesLookup is the result of Lookup.getDefault().

org.openide.util.Lookup.pathsExportedUnder Development

Sometimes it may be useful for the Lookup to contains objects from some system file system folder. This can be done with org.openide.util.Lookup.paths=Folder1:Folder2:Folder3. If this property is set prior to first call to Lookup.getDefault(), it is split into pieces (separator is ':') and individual parts are then used to construct Lookups.forPath("Folder1"), etc. All these lookups then become part of the Lookup.getDefault() one. This property works since version 7.24

Group of lookup interfaces
Interface NameIn/OutStabilitySpecified in What Document?
LookupInitializationLookupExportedUnder Development#systemproperty-org.openide.util.Lookup

during initialization of the Lookup.getDefault() the Lookup.Provider is being searched

LookupSharedClassObjectExportedUnder Development

singleton subclasses of SharedClassObject are searched for using Lookup.

LookupClassLoaderExportedUnder Development

Nearly all resource looking functions and reflective code uses ClassLoader obtained from Lookup.getDefault() for loading system wide resources.

Implementation Details

Where are the sources for the module?

The sources for the module are in the NetBeans Mercurial repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

Nothing.

Read more about the implementation in the answers to architecture questions.

Skip navigation links
org.openide.util.lookup 8.36.1