org.openide.util.lookup 8.11.1

org.openide.util
Class Lookup

java.lang.Object
  extended by org.openide.util.Lookup
Direct Known Subclasses:
AbstractLookup, ProxyLookup

public abstract class Lookup
extends Object

A general registry permitting clients to find instances of services (implementation of a given interface). This class is inspired by the Jini registration and lookup mechanism. The difference is that the methods do not throw checked exceptions (as they usually work only locally and not over the network) and that the Lookup API concentrates on the lookup, not on the registration (although getDefault() is strongly encouraged to support Lookups.metaInfServices(java.lang.ClassLoader) for registration in addition to whatever else it decides to support).

For a general talk about the idea behind the lookup pattern please see

See Also:
AbstractLookup, Lookups, LookupListener, LookupEvent

Nested Class Summary
static class Lookup.Item<T>
          A single item in a lookup result.
static interface Lookup.Provider
          Objects implementing interface Lookup.Provider are capable of and willing to provide a lookup (usually bound to the object).
static class Lookup.Result<T>
          Result of a lookup request.
static class Lookup.Template<T>
          Template defining a pattern to filter instances by.
 
Field Summary
static Lookup EMPTY
          A dummy lookup that never returns any results.
 
Constructor Summary
Lookup()
          Empty constructor for use by subclasses.
 
Method Summary
static Lookup getDefault()
          Static method to obtain the global lookup in the whole system.
abstract
<T> T
lookup(Class<T> clazz)
          Look up an object matching a given interface.
abstract
<T> Lookup.Result<T>
lookup(Lookup.Template<T> template)
          The general lookup method.
<T> Collection<? extends T>
lookupAll(Class<T> clazz)
          Find all instances corresponding to a given class.
<T> Lookup.Item<T>
lookupItem(Lookup.Template<T> template)
          Look up the first item matching a given template.
<T> Lookup.Result<T>
lookupResult(Class<T> clazz)
          Find a result corresponding to a given class.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY

public static final Lookup EMPTY
A dummy lookup that never returns any results.

Constructor Detail

Lookup

public Lookup()
Empty constructor for use by subclasses.

Method Detail

getDefault

public static Lookup getDefault()
Static method to obtain the global lookup in the whole system. The actual returned implementation can be different in different systems, but the default one is based on Lookups.metaInfServices(java.lang.ClassLoader) with the context classloader of the first caller. Each system is adviced to honor this and include some form of metaInfServices implementation in the returned lookup as usage of META-INF/services is a JDK standard.

Returns:
the global lookup in the system
See Also:
ServiceProvider

lookup

public abstract <T> T lookup(Class<T> clazz)
Look up an object matching a given interface. This is the simplest method to use. If more than one object matches, the first will be returned. The template class may be a class or interface; the instance is guaranteed to be assignable to it.

Parameters:
clazz - class of the object we are searching for
Returns:
an object implementing the given class or null if no such implementation is found

lookup

public abstract <T> Lookup.Result<T> lookup(Lookup.Template<T> template)
The general lookup method. Callers can get list of all instances and classes that match the given template, request more info about them in form of Lookup.Item and attach a listener to this be notified about changes. The general interface does not specify whether subsequent calls with the same template produce new instance of the Lookup.Result or return shared instance. The prefered behaviour however is to return shared one.

Parameters:
template - a template describing the services to look for
Returns:
an object containing the results

lookupItem

public <T> Lookup.Item<T> lookupItem(Lookup.Template<T> template)
Look up the first item matching a given template. Includes not only the instance but other associated information.

Parameters:
template - the template to check
Returns:
a matching item or null
Since:
1.8

lookupResult

public <T> Lookup.Result<T> lookupResult(Class<T> clazz)
Find a result corresponding to a given class. Equivalent to calling lookup(Lookup.Template) but slightly more convenient. Subclasses may override this method to produce the same semantics more efficiently.

Parameters:
clazz - the supertype of the result
Returns:
a live object representing instances of that type
Since:
org.openide.util 6.10

lookupAll

public <T> Collection<? extends T> lookupAll(Class<T> clazz)
Find all instances corresponding to a given class. Equivalent to calling lookupResult(java.lang.Class) and asking for Lookup.Result.allInstances() but slightly more convenient. Subclasses may override this method to produce the same semantics more efficiently.

Example usage:

 for (MyService svc : Lookup.getDefault().lookupAll(MyService.class)) {
     svc.useMe();
 }
 

Parameters:
clazz - the supertype of the result
Returns:
all currently available instances of that type
Since:
org.openide.util 6.10

org.openide.util.lookup 8.11.1

Built on December 7 2011.  |  Portions Copyright 1997-2011 Oracle. All rights reserved.