org.jvnet.hk2.component
Class Habitat

java.lang.Object
  org.jvnet.hk2.component.Habitat

public class Habitat
extends java.lang.Object

A set of templates that constitute a world of objects.

Author:

Kohsuke Kawaguchi, Jerome Dochez

Nested Class Summary

protected static interface

Habitat.NotifyCall

Field Summary

java.lang.String	DEFAULT_NAME Name to use to programmatically store default instances of a particular service.
ScopeInstance	singletonScope

Constructor Summary

Habitat()

Method Summary

void	add(Inhabitant<?> i) Adds a new inhabitant.
<T> void	addComponent(java.lang.String name, T component) Add an already instantiated component to this manager.
void	addHabitatListener(HabitatListener listener) Add a habitat listener with no contract-level filtering.
protected void	addHabitatListener(HabitatListener listener, java.util.Set<java.lang.String> typeNames)
void	addHabitatListener(HabitatListener listener, java.lang.String... typeNames) Add a habitat listener with contract-level filtering.
void	addIndex(Inhabitant<?> i, java.lang.String index, java.lang.String name) Adds a new index to look up the given inhabitant.
protected void	addIndex(Inhabitant<?> i, java.lang.String index, java.lang.String name, boolean notify)
<T> java.util.Collection<T>	getAllByContract(java.lang.Class<T> contractType) Gets all the inhabitants registered under the given Contract.
<T> java.util.Collection<T>	getAllByContract(java.lang.String contractType)
<T> java.util.Collection<T>	getAllByType(java.lang.Class<T> implType) Gets the object of the given type.
java.util.Iterator<java.lang.String>	getAllContracts()
java.util.Collection<Inhabitant<?>>	getAllInhabitantsByContract(java.lang.String contractType)
java.util.Iterator<java.lang.String>	getAllTypes()
<T> T	getByContract(java.lang.Class<T> contractType) Gets the object that has the given contract.
<T> T	getByType(java.lang.Class<T> implType) Gets the object of the given type.
<T> T	getComponent(java.lang.Class<T> clazz) Obtains a reference to the component inside the manager.
<T> T	getComponent(java.lang.Class<T> contract, java.lang.String name) Loads a component that implements the given contract and has the given name.
java.lang.Object	getComponent(java.lang.String fullQualifiedName, java.lang.String name)
<T> Inhabitant<T>	getInhabitant(java.lang.Class<T> contract, java.lang.String name) Gets a lazy reference to the component.
Inhabitant<?>	getInhabitantByAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> contract, java.lang.String name) Gets the inhabitant that has the given contract annotation and the given name.
Inhabitant<?>	getInhabitantByContract(java.lang.String typeName) Get the first inhabitant by contract
Inhabitant	getInhabitantByContract(java.lang.String fullyQualifiedName, java.lang.String name)
<T> Inhabitant<T>	getInhabitantByType(java.lang.Class<T> implType) Gets a lazy reference to the component.
Inhabitant<?>	getInhabitantByType(java.lang.String fullyQualifiedClassName)
<T> java.util.Collection<Inhabitant<? extends T>>	getInhabitants(java.lang.Class<T> contract) Gets all the inhabitants that has the given contract.
<T> java.lang.Iterable<Inhabitant<? extends T>>	getInhabitants(java.lang.Class<T> contract, java.lang.String name) Gets all the inhabitants that has the given contract and the given name
java.lang.Iterable<Inhabitant<?>>	getInhabitantsByAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> contract, java.lang.String name) Gets all the inhabitants that has the given contract annotation and the given name.
java.util.Collection<Inhabitant<?>>	getInhabitantsByContract(java.lang.String fullyQualifiedClassName)
<T> java.util.Collection<Inhabitant<T>>	getInhabitantsByType(java.lang.Class<T> implType) Gets all the inhabitants that has the given implementation type.
java.util.Collection<Inhabitant<?>>	getInhabitantsByType(java.lang.String fullyQualifiedClassName) Gets all the inhabitants that has the given implementation type name.
protected static java.lang.Long	getServiceRanking(Inhabitant<?> i, boolean wantNonNull)
void	initialized() FOR INTERNAL USE ONLY
boolean	isContract(java.lang.Class<?> type) Checks if the given type is a contract interface that has some implementations in this Habitat.
boolean	isContract(java.lang.String fullyQualifiedClassName)
boolean	isInitialized()
protected boolean	matches(Inhabitant<?> inhabitant, java.lang.Object serviceOrInhabitant)
protected void	notify(Habitat.NotifyCall innerCall, Inhabitant<?> inhabitant, HabitatListener.EventType event, java.lang.String index, Inhabitant<HabitatListener> extraListenerToBeNotified)
protected void	notify(Inhabitant<?> inhabitant, HabitatListener.EventType event, java.lang.String index, Inhabitant<HabitatListener> extraListenerToBeNotified)
protected void	notify(Inhabitant<?> inhabitant, HabitatListener.EventType event, java.lang.String index, java.lang.String name, java.lang.Object service, Inhabitant<HabitatListener> extraListenerToBeNotified)
void	notifyInhabitantChanged(Inhabitant<?> inhabitant, java.lang.String... contracts) Trigger a notification that an inhabitant has changed.
void	release() Releases all the components.
boolean	remove(Inhabitant<?> inhabitant) Removes an inhabitant
boolean	removeAllByType(java.lang.Class<?> type) Removes all inhabitants for a particular type
boolean	removeHabitatListener(HabitatListener listener) Remove a habitat listener.
boolean	removeIndex(java.lang.String index, java.lang.Object serviceOrInhabitant) Removes a Contracted service
boolean	removeIndex(java.lang.String index, java.lang.String name) Removes a NamedInhabitant for a specific contract
protected java.lang.Object	service(java.lang.Object serviceOrInhabitant)
InhabitantTracker	track(InhabitantTrackerContext itc, InhabitantTracker.Callback callback) Registers a dependency on the inhabitant with the given tracker context.
java.util.concurrent.Future<InhabitantTracker>	trackFuture(InhabitantTrackerContext itc) Returns a future that can be checked asynchronously, and multiple times.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_NAME

public final java.lang.String DEFAULT_NAME

Name to use to programmatically store default instances of a particular service.

See Also:

Constant Field Values

singletonScope

public final ScopeInstance singletonScope

Constructor Detail

Habitat

public Habitat()

Method Detail

addHabitatListener

public void addHabitatListener(HabitatListener listener)

Add a habitat listener with no contract-level filtering. This API is primarily intended for internal cases within Hk2. The listener with no contract-level filtering will be called for all change events within the habitat pertaining to inhabitants.

Parameters:

listener - The habitat Listener to be added

Since:

3.1

See Also:

#addHabitatListener(HabitatListener, String...)} is recommended for most cases

addHabitatListener

public void addHabitatListener(HabitatListener listener,
                               java.lang.String... typeNames)

Add a habitat listener with contract-level filtering. The listener will be called based on the set of contract filters provided.

Parameters:

listener - The habitat Listener to be added

typeNames - The contracts to filter on; this should be non-null

Since:

3.1

addHabitatListener

protected void addHabitatListener(HabitatListener listener,
                                  java.util.Set<java.lang.String> typeNames)

removeHabitatListener

public boolean removeHabitatListener(HabitatListener listener)

Remove a habitat listener.

Parameters:

listener - The habitat Listener to be removed

typeNames - The contracts to filter on

Returns:

true; if the listener was indeed removed

Since:

3.1

track

public InhabitantTracker track(InhabitantTrackerContext itc,
                               InhabitantTracker.Callback callback)
                        throws ComponentException

Registers a dependency on the inhabitant with the given tracker context.

Once the criteria is met, any callback provided is called. This callback may occur asynchronously from the thread initiating the event.

Parameters:

itc - The tracking criteria.

callback - Optionally the callback.

Returns:

The tracker

Throws:

ComponentException

Since:

3.1

trackFuture

public java.util.concurrent.Future<InhabitantTracker> trackFuture(InhabitantTrackerContext itc)
                                                           throws ComponentException

Returns a future that can be checked asynchronously, and multiple times.

Implementation Note: The Future that is returned does not behave in the traditional sense in that it is NOT directly submitted to an ExecutorService. Each call to get() or get(timeout) may result in a [re]submission to an internally held executor. This means that a call to get(...) may return a tracker, and a subsequent call to get(...) may return null, or vice versa. This is true until the underlying tracker is released at which point a tracker is no longer usable.

Parameters:

itc - The tracking criteria.

Returns:

The tracker

Throws:

ComponentException

Since:

3.1

removeAllByType

public boolean removeAllByType(java.lang.Class<?> type)

Removes all inhabitants for a particular type

Parameters:

type - of the component

Returns:

true if any inhabitants were removed

add

public void add(Inhabitant<?> i)

Adds a new inhabitant.

See Inhabitants for typical ways to create Inhabitants.

addIndex

public void addIndex(Inhabitant<?> i,
                     java.lang.String index,
                     java.lang.String name)

Adds a new index to look up the given inhabitant.

Parameters:

index - Primary index name, such as contract FQCN.

name - Name that identifies the inhabitant among other inhabitants in the same index. Can be null for unnamed inhabitants.

addIndex

protected void addIndex(Inhabitant<?> i,
                        java.lang.String index,
                        java.lang.String name,
                        boolean notify)

getServiceRanking

protected static java.lang.Long getServiceRanking(Inhabitant<?> i,
                                                  boolean wantNonNull)

remove

public boolean remove(Inhabitant<?> inhabitant)

Removes an inhabitant

Parameters:

inhabitant - inhabitant to be removed

removeIndex

public boolean removeIndex(java.lang.String index,
                           java.lang.String name)

Removes a NamedInhabitant for a specific contract

Parameters:

index - contract name

name - instance name

Returns:

true if the removal was successful

removeIndex

public boolean removeIndex(java.lang.String index,
                           java.lang.Object serviceOrInhabitant)

Removes a Contracted service

Parameters:

index - the contract name

serviceOrInhabitant - the service instance, or an Inhabitant instance

matches

protected boolean matches(Inhabitant<?> inhabitant,
                          java.lang.Object serviceOrInhabitant)

service

protected java.lang.Object service(java.lang.Object serviceOrInhabitant)

notifyInhabitantChanged

public void notifyInhabitantChanged(Inhabitant<?> inhabitant,
                                    java.lang.String... contracts)

Trigger a notification that an inhabitant has changed.

Parameters:

inhabitant - the inhabitant that has changed

contracts - the contracts associated with the inhabitant

initialized

public void initialized()

FOR INTERNAL USE ONLY

isInitialized

public boolean isInitialized()

notify

protected void notify(Inhabitant<?> inhabitant,
                      HabitatListener.EventType event,
                      java.lang.String index,
                      Inhabitant<HabitatListener> extraListenerToBeNotified)

notify

protected void notify(Inhabitant<?> inhabitant,
                      HabitatListener.EventType event,
                      java.lang.String index,
                      java.lang.String name,
                      java.lang.Object service,
                      Inhabitant<HabitatListener> extraListenerToBeNotified)

notify

protected void notify(Habitat.NotifyCall innerCall,
                      Inhabitant<?> inhabitant,
                      HabitatListener.EventType event,
                      java.lang.String index,
                      Inhabitant<HabitatListener> extraListenerToBeNotified)

isContract

public boolean isContract(java.lang.Class<?> type)

Checks if the given type is a contract interface that has some implementations in this Habitat.

There are two ways for a type to be marked as a contract. Either it has Contract, or it's marked by ContractProvided from the implementation.

Note that just having Contract is not enough to make this method return true. It can still return false if the contract has no implementation in this habitat.

This method is useful during the injection to determine what lookup to perform, and it handles the case correctly when the type is marked as a contract by ContractProvided.

isContract

public boolean isContract(java.lang.String fullyQualifiedClassName)

getAllByContract

public <T> java.util.Collection<T> getAllByContract(java.lang.Class<T> contractType)

Gets all the inhabitants registered under the given Contract. This is an example of heterogeneous type-safe container.

Returns:

can be empty but never null.

getAllByContract

public <T> java.util.Collection<T> getAllByContract(java.lang.String contractType)

getAllInhabitantsByContract

public java.util.Collection<Inhabitant<?>> getAllInhabitantsByContract(java.lang.String contractType)

getAllByType

public <T> java.util.Collection<T> getAllByType(java.lang.Class<T> implType)

Gets the object of the given type.

Returns:

can be empty but never null.

addComponent

public <T> void addComponent(java.lang.String name,
                             T component)
                  throws ComponentException

Add an already instantiated component to this manager. The component has been instantiated by external code, however dependency injection, PostConstruct invocation and dependency extraction will be performed on this instance before it is store in the relevant scope's resource manager.

Parameters:

name - name of the component, could be default name

component - component instance

Throws:

ComponentException - if the passed object is not an HK2 component or injection/extraction failed.

getComponent

public <T> T getComponent(java.lang.Class<T> clazz)
               throws ComponentException

Obtains a reference to the component inside the manager.

This is the "new Foo()" equivalent in the IoC world.

Depending on the Scope of the component, a new instance might be created, or an existing instance might be returned.

Returns:

non-null.

Throws:

ComponentException - If failed to obtain a requested instance. In practice, failure only happens when we try to create a new instance of the component.

getComponent

public <T> T getComponent(java.lang.Class<T> contract,
                          java.lang.String name)
               throws ComponentException

Loads a component that implements the given contract and has the given name.

Parameters:

name - can be null, in which case it'll only match to the unnamed component.

Returns:

null if no such servce exists.

Throws:

ComponentException

getComponent

public java.lang.Object getComponent(java.lang.String fullQualifiedName,
                                     java.lang.String name)

getInhabitant

public <T> Inhabitant<T> getInhabitant(java.lang.Class<T> contract,
                                       java.lang.String name)
                            throws ComponentException

Gets a lazy reference to the component.

This method defers the actual instantiation of the component until Inhabitant.get() is invoked.

Returns:

null if no such component is found.

Throws:

ComponentException

getInhabitantByType

public <T> Inhabitant<T> getInhabitantByType(java.lang.Class<T> implType)

Gets a lazy reference to the component.

This method defers the actual instantiation of the component until Inhabitant.get() is invoked.

Returns:

null if no such component is found.

getInhabitantByType

public Inhabitant<?> getInhabitantByType(java.lang.String fullyQualifiedClassName)

getInhabitantByAnnotation

public Inhabitant<?> getInhabitantByAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> contract,
                                               java.lang.String name)
                                        throws ComponentException

Gets the inhabitant that has the given contract annotation and the given name.

This method defers the actual instantiation of the component until Inhabitant.get() is invoked.

Returns:

null if no such component is found.

Throws:

ComponentException

getInhabitants

public <T> java.util.Collection<Inhabitant<? extends T>> getInhabitants(java.lang.Class<T> contract)
                                                             throws ComponentException

Gets all the inhabitants that has the given contract.

Throws:

ComponentException

getInhabitantsByType

public <T> java.util.Collection<Inhabitant<T>> getInhabitantsByType(java.lang.Class<T> implType)
                                                         throws ComponentException

Gets all the inhabitants that has the given implementation type.

Throws:

ComponentException

getInhabitantsByType

public java.util.Collection<Inhabitant<?>> getInhabitantsByType(java.lang.String fullyQualifiedClassName)

Gets all the inhabitants that has the given implementation type name.

getInhabitantByContract

public Inhabitant<?> getInhabitantByContract(java.lang.String typeName)

Get the first inhabitant by contract

Parameters:

fullyQualifiedClassName -

Returns:

getInhabitantsByContract

public java.util.Collection<Inhabitant<?>> getInhabitantsByContract(java.lang.String fullyQualifiedClassName)

getAllContracts

public java.util.Iterator<java.lang.String> getAllContracts()

getAllTypes

public java.util.Iterator<java.lang.String> getAllTypes()

getInhabitantByContract

public Inhabitant getInhabitantByContract(java.lang.String fullyQualifiedName,
                                          java.lang.String name)

getInhabitants

public <T> java.lang.Iterable<Inhabitant<? extends T>> getInhabitants(java.lang.Class<T> contract,
                                                                      java.lang.String name)
                                                           throws ComponentException

Gets all the inhabitants that has the given contract and the given name

This method defers the actual instantiation of the component until Inhabitant.get() is invoked.

Returns:

Can be empty but never null.

Throws:

ComponentException

getInhabitantsByAnnotation

public java.lang.Iterable<Inhabitant<?>> getInhabitantsByAnnotation(java.lang.Class<? extends java.lang.annotation.Annotation> contract,
                                                                    java.lang.String name)
                                                             throws ComponentException

Gets all the inhabitants that has the given contract annotation and the given name.

This method defers the actual instantiation of the component until Inhabitant.get() is invoked.

Returns:

Can be empty but never null.

Throws:

ComponentException

getByType

public <T> T getByType(java.lang.Class<T> implType)

Gets the object of the given type.

Returns:

null if not found.

getByContract

public <T> T getByContract(java.lang.Class<T> contractType)

Gets the object that has the given contract.

If there are more than one of them, this method arbitrarily return one of them.

release

public void release()

Releases all the components. Should be called for orderly shut-down of the system. TODO: more javadoc needed