Lookups (Lookup API)

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

```
public class Lookups
extends Object
```
Static factory methods for creating common lookup implementations.

Since:

2.21

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 `Lookups.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.
    
    Parameters:
    
    objectToLookup - object to lookup
    
    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).
    
    Type Parameters:
    
    T - type for key
    
    R - type for result
    
    Parameters:
    
    keys - set of object
    
    convertor - convertor for object
    
    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.Results 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.
    Parameters:
    
    classLoader - class loader to use for loading
    
    Returns:
    
    lookup associatied with classloader
    
    Since:
    
    3.35
    
    See Also:
    
    ServiceProvider
  - metaInfServices
```
public static Lookup metaInfServices(ClassLoader classLoader,
                                     String prefix)
```
    Returns a lookup that behaves exactly like Lookups.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
    
    Returns:
    
    lookup associatied with classloader
    
    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 Lookups.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
    
    Returns:
    
    filtred lookup
    
    Since:
    
    5.4
  - lookupItem
```
public static <T> Lookup.Item<T> lookupItem(T instance,
                                            String id)
```
    Creates Lookup.Item representing the instance passed in.
    
    Type Parameters:
    
    T - type of the object
    
    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

Class Lookups

Method Summary

Methods inherited from class java.lang.Object

Method Detail

singleton

fixed

fixed

proxy

metaInfServices

metaInfServices

forPath

exclude

lookupItem

executeWith