org.openide.util.lookup

## Class Lookups

- java.lang.Object
- - org.openide.util.lookup.Lookups

-     public class Lookups
      extends Object

  Static factory methods for creating common lookup implementations.
  Since:
    2.21
  Author:
    David Strupl

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Lookup` | `exclude(Lookup lookup, Class... classes)` Creates a lookup that wraps another one and filters out instances of specified classes.
    `static void` | `executeWith(Lookup defaultLookup, Runnable code)` Temporarily (while the `code` is running) changes value of `Lookup.getDefault()` to here-in provided lookup.
    `static Lookup` | `fixed(Object... objectsToLookup)` Creates a lookup that contains an array of objects specified via the parameter.
    `static <T,R> Lookup` | `fixed(T[] keys, InstanceContent.Convertor<? super T,R> convertor)` Creates a lookup that contains an array of objects specified via the parameter.
    `static Lookup` | `forPath(String path)` Creates a named lookup.
    `static <T> Lookup.Item<T>` | `lookupItem(T instance, String id)` Creates `Lookup.Item` representing the instance passed in.
    `static Lookup` | `metaInfServices(ClassLoader classLoader)` Returns a lookup that implements the JDK1.3 JAR services mechanism and delegates to META-INF/services/name.of.class files.
    `static Lookup` | `metaInfServices(ClassLoader classLoader, String prefix)` Returns a lookup that behaves exactly like `metaInfServices(ClassLoader)` except that it does not read data from `META-INF/services/`, but instead from the specified prefix.
    `static Lookup` | `proxy(Lookup.Provider provider)` Creates a lookup that delegates to another one but that one can change from time to time.
    `static Lookup` | `singleton(Object objectToLookup)` Creates a singleton lookup.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### singleton

          public static Lookup singleton(Object objectToLookup)

      Creates a singleton lookup. It means lookup that contains only one object specified via the supplied parameter. The lookup will either return the object or null if the supplied template does not match the class. If the specified argument is null the method will end with NullPointerException.
      Returns:
        Fully initialized lookup object ready to use
      Throws:
        `NullPointerException` - if the supplied argument is null
      Since:
        2.21

    - #### fixed

          public static Lookup fixed(Object... objectsToLookup)

      Creates a lookup that contains an array of objects specified via the parameter. The resulting lookup is fixed in the following sense: it contains only fixed set of objects passed in by the array parameter. Its contents never changes so registering listeners on such lookup does not have any observable effect (the listeners are never called).
      Parameters:
        `objectsToLookup` - list of objects to include
      Returns:
        Fully initialized lookup object ready to use
      Throws:
        `NullPointerException` - if the supplied argument is null
      Since:
        2.21

    - #### fixed

          public static <T,R> Lookup fixed(T[] keys,
                                           InstanceContent.Convertor<? super T,R> convertor)

      Creates a lookup that contains an array of objects specified via the parameter. The resulting lookup is fixed in the following sense: it contains only fixed set of objects passed in by the array parameter. The objects returned from this lookup are converted to real objects before they are returned by the lookup. Its contents never changes so registering listeners on such lookup does not have any observable effect (the listeners are never called).
      Returns:
        Fully initialized lookup object ready to use
      Throws:
        `NullPointerException` - if the any of the arguments is null
      Since:
        2.21

    - #### proxy

          public static Lookup proxy(Lookup.Provider provider)

      Creates a lookup that delegates to another one but that one can change from time to time. The returned lookup checks every time somebody calls `lookup` or `lookupItem` method whether the provider still returns the same lookup. If not, it updates state of all `Lookup.Result`s that it created (and that still exists).

      The user of this method has to implement its provider's `getLookup` method (must be thread safe and fast, will be called often and from any thread) pass it to this method and use the returned lookup. Whenever the user changes the return value from the `getLookup` method and wants to notify listeners on the lookup about that it should trigger the event firing, for example by calling `lookup.lookup (Object.class)` directly on the lookup returned by this method that forces a check of the return value of `Lookup.Provider.getLookup()`.

      Parameters:
        `provider` - the provider that returns a lookup to delegate to
      Returns:
        lookup delegating to the lookup returned by the provider
      Since:
        3.9

    - #### metaInfServices

          public static Lookup metaInfServices(ClassLoader classLoader)

      Returns a lookup that implements the JDK1.3 JAR services mechanism and delegates to META-INF/services/name.of.class files.

      Some extensions to the JAR services specification are implemented:

      1. An entry may be followed by a line of the form `#position=integer` to specify ordering. (Smaller numbers first, entries with unspecified position last.)
      2. A line of the form `#-classname` suppresses an entry registered in another file, so can be used to supersede one implementation with another.

      Note: It is not dynamic - so if you need to change the classloader or JARs, wrap it in a `ProxyLookup` and change the delegate when necessary. Existing instances will be kept if the implementation classes are unchanged, so there is "stability" in doing this provided some parent loaders are the same as the previous ones.

      Since:
        3.35
      See Also:
        `ServiceProvider`

    - #### metaInfServices

          public static Lookup metaInfServices(ClassLoader classLoader,
                                               String prefix)

      Returns a lookup that behaves exactly like `metaInfServices(ClassLoader)` except that it does not read data from `META-INF/services/`, but instead from the specified prefix.
      Parameters:
        `classLoader` - class loader to use for loading
        `prefix` - prefix to prepend to the class name when searching
      Since:
        7.9
      See Also:
        `ServiceProvider.path()`

    - #### forPath

          public static Lookup forPath(String path)

      Creates a named lookup. It is a lookup identified by a given path. Two lookups with the same path should have the same content.

      It is expected that each named lookup will contain a superset of what would be created by: `metaInfServices(theRightLoader, "META-INF/namedservices/" + path + "/")`

      Various environments can add their own extensions to its content. As such `forPath(java.lang.String)` can combine lookups from several sources. In current NetBeans Runtime Container, two lookups are used:

      - `Lookups.metaInfServices("META-INF/namedservices/" + path)`
      - `org.openide.loaders.FolderLookup(path)`

      Please note that these lookups differ in the way they inspect sub-folders. The first lookup just returns instances from the given path, ignoring sub-folders, the second one retrieves instances from the whole sub-tree.

      Read more about the usage of this method.

      Parameters:
        `path` - the path identifying the lookup, e.g. `Servers/J2EEWrapper`
      Returns:
        lookup associated with this path
      Since:
        7.9
      See Also:
        `NamedServiceDefinition`

    - #### exclude

          public static Lookup exclude(Lookup lookup,
                                       Class... classes)

      Creates a lookup that wraps another one and filters out instances of specified classes. If you have a lookup and you want to remove all instances of ActionMap you can use:

           l = Lookups.exclude(lookup, ActionMap.class);

      Then anybody who asks for `l.lookup(ActionMap.class)` or subclass will get `null`. Even if the original lookup contains the value. To create empty lookup (well, just an example, otherwise use `Lookup.EMPTY`) one could use:

           Lookup.exclude(anyLookup, Object.class);

      as any instance in any lookup is of type Object and thus would be excluded.

      The complete behavior can be described as `classes` being a barrier. For an object not to be excluded, there has to be an inheritance path between the queried class and the actual class of the instance, that is not blocked by any of the excluded classes and the queried class cannot be subclass of an excluded class:

           interface A {}
           interface B {}
           class C implements A, B {}
           Object c = new C();
           Lookup l1 = Lookups.singleton(c);
           Lookup l2 = Lookups.exclude(l1, A.class);
           assertNull("A is directly excluded", l2.lookup(A.class));
           assertEquals("Returns C as A.class is not between B and C", c, l2.lookup(B.class));

      For more info check the excluding lookup tests and the discussion in issue 53058.
      Parameters:
        `lookup` - the original lookup that should be filtered
        `classes` - array of classes those instances should be excluded
      Since:
        5.4

    - #### lookupItem

          public static <T> Lookup.Item<T> lookupItem(T instance,
                                                      String id)

      Creates `Lookup.Item` representing the instance passed in.
      Parameters:
        `instance` - the object for which Lookup.Item should be creted
        `id` - unique identification of the object, for details see `Lookup.Item.getId()`, can be `null`
      Returns:
        lookup item representing instance
      Since:
        4.8

    - #### executeWith

          public static void executeWith(Lookup defaultLookup,
                                         Runnable code)

      Temporarily (while the `code` is running) changes value of `Lookup.getDefault()` to here-in provided lookup. Useful in a multi user environment where different users and their requests should be associated with different content of default lookup.

      As a special case, `executeWith` will execute the Runnable with the system global lookup (the one effective during system bootstrap), when the passed `defaultLookup` parameter is `null`. This feature may be useful to switch from a specialized Lookup back to a default one for some limited processing, or when the caller needs to bypass potential execution-local content temporary effective in the default Lookup and work with system-wide services only.
      Parameters:
        `defaultLookup` - the lookup to be come default while code is running
        `code` - the code to execute (synchronously) before the method returns
      Since:
        8.30, 8.31 can delegate to the system Lookup

Copyright © 2025 API Design. All Rights Reserved.