org.openide.util

Class Lookup

java.lang.Object

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 Lookup.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

• The Solution to Communication Between Components page
• the introduction to the lookup API via use cases
• the examples of how to write your own lookup

See Also:

AbstractLookup, Lookups, LookupListener, LookupEvent

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
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

Fields

Modifier and Type	Field and Description
static Lookup	EMPTY A dummy lookup that never returns any results.

Constructor Summary

Constructors

Constructor and Description
Lookup() Empty constructor for use by subclasses.

Method Summary

Modifier and Type	Method and Description
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(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 Lookup.lookupResult(java.lang.Class<T>) 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