NetBeans Lookups Explained!

Lookups are one of the most important parts of the NetBeans Platform. They're used almost everywhere and most of the time when you ask something on a mailing list the answer is "Use Lookups!". Many times when the use of Lookups is explained it's in a very specific context, e.g. selection management or ServiceLoaders. That makes Lookups look complicated and hard to understand, while actually they are very simple and extremely powerful.

That's why I guess it's time to write an article that explains what lookups actually are and how they work. In the subsequent parts I'll explain how they can be used to solve some common problems.

Lookup as a Data Structure

So first let's have a look at Lookup as a data structure. A Lookup is a map with Class Objects as keys and a Set of instances of the key Class object as values. An additional feature of a Lookup is that you can listen for changes of what's in there. It's as simple as that! If you want to ask a lookup for it's contents, you can do so like this:

Lookup  lookup = //get a lookup somewhere...
Collection <String> strings =lookup.lookupAll(String.class);
        

If you want to listen for changes, you add your Listener to Lookup.Result an inner class that represents a query result. This way you add a Listener that listens for addition or removal of objects of a certain class:

Lookup.Result <String> strings = lookup.lookupResult(String.class);
strings.allItems();
strings.addLookupListener(new LookupListener(){   
  @override
  public void resultChanged(LookupEvent e){
    // do something
   }}
); 

This is how you usually use an existing lookup. If you want to create one, there are some implementations to help you. The most basic one is Lookups.Singleton, a Lookup that only contains one object:

Lookup simple = Lookups.singleton("Hello World!"); 

There's also an implementation for creating a lookup with more than one entry, still with fixed content:

Lookups moreElements = Lookups.fixed( "Hello", "World", new Integer(5) ); 

If you want to use a Lookup to dynamically put in stuff you'll need to choose an implementation that supports that. The most flexible one is using an InstanceContent Object to add and remove stuff:

InstanceContent content = new InstanceContent();
Lookup dynamicLookup = new AbstractLookup(content);
content.add("Hello");
content.add(5);  

Listeners registered for the matching class will be informed when something changes. If you would like to query more than one Lookup at a time you can use a ProxyLookup. This for example, combines two of the Lookups created above into one:

ProxyLookup proxy = new ProxyLookup(dynamicLookup, moreElements); 

Lookup.Provider

If your Object has a Lookup to store a bunch of stuff, you can make it accessible to others by implementing Lookup.Provider an interface with only one method:

public Lookup getLookup();

Again, extremely simple. Someone interested in what's in your Objects Lookup can ask for it and register a listener. In NetBeans TopComponents implement this interface, so you can ask any TopComponent for it's Lookup. The easiest way to get hold of most of the TopComponents is via their ID:

TopComponent tc = WindowManager.getDefault().findTopComponent("AnInterestingTopComponent");
Lookup tcLookup = tc.getlookup();

As most TopComponents put into their Lookup whatever is selected, for example the entries in a list, you can add a Listener to track the Selection in a TopComponent. If your for example interested in the selected Nodes you can do it like this:

Lookup.result <Node> noderesult = tcLookup.lookupResult(Node.class);
result.allInstances();
noderesult.addLookuplistener(myLookupListener); 

That's especially handy when you want to provide a Master-Detail-View. If you want to provide your own Lookup in your TopComponent you do it like this:

associateLookup(mylookup); 

Global Selection

Sometimes you might be interested not only in what is selected in one specific TopComponent, but in whatever TopComponent currently has the focus. That's easy as well because NetBeans provides a Lookup that proxies the Lookup of the TopComponent that currently has the focus. To use this you simply need to do this:

Lookup global = Utilities.actionsGlobalContext();

You can use this like any other Lookup and register your listeners, no magic involved.

Nodes

Nodes also implement Lookup.Provider so you can ask them for their Lookup as well. Something useful to store inside a Node's Lookup is the DataObject it may represent. If you're using Nodes you probably do so in combination with the Explorer API to display them. If you do that you'll usually create a lookup for your TopComponent with the help of the ExplorerManager:

associateLookup(ExplorerUtils.createLookup ( explorermanager, this.getActionMap() ) );

The resulting Lookup also proxies the content of the selected Nodes Lookup. This way everything someone might be interested in shows up in your TopComponent's Lookup.

Service Loader and other uses

As you've seen Lookups are actually a very simple yet powerful concept. Some articles here on NetBeans Zone also cover the use of Lookups for loading services in a NetBeans RCP application, which is also an important use. To do that NetBeans provides a default Lookup that looks in certain places for service registrations, e.g. in the META-INF/services folder of a modules jar file and in the modules layer.xml. If you're interested in getting an instance of a Service implementation you can do it like this:

Collection <ServiceInterface> services= Lookup.getDefault.lookupAll(ServiceInterface.class); 

If you register your service in the layer.xml you can get a lookup for a certain Folder like this:

Lookup lkp = Lookups.forPath("ServiceProviders");

I guess that's all you need to know to get started with Lookups, so have fun trying it out, it's really simple.