org.openide.util.lookup
Class Lookups

java.lang.Object
  extended by org.openide.util.lookup.Lookups

public class Lookups
extends java.lang.Object

Static factory methods for creating common lookup implementations.

Since:
2.21
Author:
David Strupl

Method Summary
static Lookup exclude(Lookup lookup, java.lang.Class... classes)
          Creates a lookup that wraps another one and filters out instances of specified classes.
static Lookup fixed(java.lang.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(java.lang.String path)
          Creates a named lookup.
static
<T> Lookup.Item<T>
lookupItem(T instance, java.lang.String id)
          Creates Lookup.Item representing the instance passed in.
static Lookup metaInfServices(java.lang.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(java.lang.ClassLoader classLoader, java.lang.String prefix)
          Returns a lookup that behaves exactly as the one created 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(java.lang.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(java.lang.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:
java.lang.NullPointerException - if the supplied argument is null
Since:
2.21

fixed

public static Lookup fixed(java.lang.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:
java.lang.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:
java.lang.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(java.lang.ClassLoader classLoader)
Returns a lookup that implements the JDK1.3 JAR services mechanism and delegates to META-INF/services/name.of.class files.

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

metaInfServices

public static Lookup metaInfServices(java.lang.ClassLoader classLoader,
                                     java.lang.String prefix)
Returns a lookup that behaves exactly as the one created 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

forPath

public static Lookup forPath(java.lang.String path)
Creates a named lookup. It is a lookup identified by a given path. Two lookups with the same path are going to have the same content. It is expected that each named lookup will contain a superset of what would lookup created by metaInfServices(theRightLoader, "META-INF/namedservices/" + path) contain. However various environments can add their own extensions to its content. For example when running inside NetBeans Runtime Container, the content of system file system under the given path is also present in the returned lookup.

Read more about the usage of this method...

Parameters:
path - the path identifying the lookup, for example Databases/, etc.
Returns:
lookup associated with this path
Since:
7.9

exclude

public static Lookup exclude(Lookup lookup,
                             java.lang.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:

 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,
                                            java.lang.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