Lookup is a mechanism for finding instances of objects. It is pervasively used in NetBeans APIs. The general pattern is that you pass a Class object and get back an instance of that class or null. See the javadoc for links to articles describing its inspiration and purpose.

The simplest way to think of Lookup is that it is a Map where the keys are Class objects and the value for each key is an instance of the key class.

There is the global lookup which is used to find objects (often, but not always, singletons) that are registered throughout the system. Also, many types of objects have a method getLookup() that enables other code to get things specific to that object. In particular, Nodes and Project objects have a Lookup.

The primary purpose of Lookup is decoupling - it makes it possible to use generic objects to get very specific information, without having to cast objects to a specific type. Confused yet? It's simple. Take the example of OpenCookie - it has one method, open() that will open a file in the editor.

Say that I want to write some code that will open the selected file when the user does something. It could be an Action, a button, or maybe my code has just created a file and I want to open it. This is what I will do:

 Node[] n = TopComponent.getRegistry().getActivatedNodes();
if (n.length == 1) {
   OpenCookie oc = (OpenCookie) n[0].getLookup().lookup(OpenCookie.class);
   if (oc != null) {

I could even write this code more simply, without the Nodes API at all, using Utilities.actionsGlobalContext():

 OpenCookie oc = (OpenCookie) Utilities.actionsGlobalContext().

if (oc != null) oc.open();

The power of all this is in the level of decoupling it provides: My code that wants to open the file does not have to know anything at all about what happens when the file is opened, or what kind of file it is, or what module supports opening it. And the module that supports opening it does not need to know anything about who is going to open it. They both simply share a dependency on the abstract interface OpenCookie. So either one can be replaced without affecting the other at all.

A good example of this is in the POV-Ray tutorial. It launches an external process that generates a .png file. When the process ends, it wants to open it, so it does the following:

 FileObject fob = FileUtil.toFileObject (new File(pathWePassedToProcess));
if (fob != null) {  //the process succeeded
   DataObject dob = DataObject.find (fob);
   OpenCookie oc = (OpenCookie) dob.getCookie (OpenCookie.class);
   if (oc != null) { //the Image module is installed

The fact is that it is the Image module that makes it possible to open .png files in NetBeans. But the POV-Ray tutorial does not need to know or care that the Image module exists, or what it does - it simply says "open this".

The common pattern you'll see for Lookup usage is one where there are three components:

  • Module A is pure API - it provides some interfaces
  • Module B depends on A and implements those interfaces, providing them from a Node or Project or such
  • Module C wants to display some UI or do something with objects that implement those interfaces. It also depends on A, but does not need to know about B at all; either can be replaced independently, and the other will still function

For global services, the model is more simple - typically there will be some singleton object, implemented as an abstract class:

 public abstract class GlobalService {

   public abstract void doSomething(Something arg);
   public static GlobalService getDefault() {  

     //Convenience method so users don't have to lookup/cast it themselves
     GlobalService result = (GlobalService) Lookup.getDefault().
        lookup (GlobalService.class);

     if (result = null) {
        //Nothing registered, fail gracefully
        return new NoOpGlobalService();  

   private static class NoOpGlobalService extends GlobalService {
      public void doSomething (Something arg) {}

Some other module entirely actually registers an implementation of this interface in the default Lookup. StatusDisplayer is a good example of this pattern.

A Lookup is not limited to containing one singleton of any type. If there may be more than one of a given type in a Lookup, the syntax is slightly different:

 Lookup.Template tpl = new Lookup.Template (SomeIface.class);
Lookup.Result result = Lookup.getDefault().lookup (tpl);
Collection c = result.allInstances();

The Lookup.Result can be listened on for changes in the result of the query. It is often useful to think of a Lookup as a space in which objects appear and disappear, and your code can respond as that happens.

Objects in a Lookup often are not instantiated until the first time they are requested; depending on the implementation, they may be weakly referenced, so that if an object is not used for a while, it can be garbage collected to save memory. So Lookup additionally enables lazy instantiation of objects, which is useful for performance reasons.

Source: NetBeans FAQ