org.jvnet.hk2.component
Class Habitat

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

All Implemented Interfaces:

org.glassfish.hk2.inject.Injector, org.glassfish.hk2.Locator, org.glassfish.hk2.Services, SimpleServiceLocator

public class Habitat
extends java.lang.Object
implements org.glassfish.hk2.Services, org.glassfish.hk2.inject.Injector, SimpleServiceLocator

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.
static java.lang.String	HK2_CONCURRENCY_CONTROLS System property tag for concurrency controls (i.e., true for multi threaded injection, inhabitant activation, etc.)
static boolean	MANAGED_INJECTION_POINTS_ENABLED
org.glassfish.hk2.ScopeInstance	singletonScope

Constructor Summary

Habitat()

Method Summary

void	add(Inhabitant<?> i) Adds a new inhabitant.
<T> void	addComponent(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)
org.glassfish.hk2.DynamicBinderFactory	bindDynamically()
<U> org.glassfish.hk2.ServiceLocator<U>	byType(java.lang.Class<U> type)
org.glassfish.hk2.ServiceLocator<?>	byType(java.lang.String typeName)
<U> org.glassfish.hk2.ContractLocator<U>	forContract(java.lang.Class<U> contract)
org.glassfish.hk2.ContractLocator<?>	forContract(java.lang.String contractName)
<U> org.glassfish.hk2.ContractLocator<U>	forContract(org.glassfish.hk2.TypeLiteral<U> typeLiteral)
<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)
<T> java.util.Collection<Inhabitant>	getAllInhabitantsByType(java.lang.Class<T> implType) Gets all matching inhabitants given the type.
java.util.Iterator<java.lang.String>	getAllTypes()
java.util.Collection<org.glassfish.hk2.Binding<?>>	getBindings()
java.util.Collection<org.glassfish.hk2.Binding<?>>	getBindings(org.glassfish.hk2.Descriptor descriptor)
<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	getByType(java.lang.String 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.
<T> T	getComponent(java.lang.String fullQualifiedName, java.lang.String name) Analogous to the following:
java.util.Collection<org.glassfish.hk2.Binding<?>>	getDeclaredBindings()
java.util.Collection<org.glassfish.hk2.Binding<?>>	getDeclaredBindings(org.glassfish.hk2.Descriptor descriptor)
org.glassfish.hk2.Services	getDefault()
<T> Inhabitant<T>	getInhabitant(java.lang.Class<T> contract, java.lang.String name) Gets a lazy reference to the component.
<T> Inhabitant<T>	getInhabitant(java.lang.reflect.Type type, java.lang.String name)
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> Inhabitant<T>	getInhabitantByType(java.lang.reflect.Type implType)
<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 This method defers the actual instantiation of the component until Inhabitant.get() is invoked.
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)
org.glassfish.hk2.Services	getServices(java.lang.String moduleName)
void	initialized() FOR INTERNAL USE ONLY
<T> T	inject(java.lang.Class<T> type) Instantiate the passed type and injects all the Inject annotated fields and methods
<T> T	inject(T object)
boolean	isContextualFactoriesPresent() FOR INTERNAL USE
static boolean	isContextualFactoriesPresentAnywhere() FOR INTERNAL USE
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	isContract(java.lang.reflect.Type type)
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

HK2_CONCURRENCY_CONTROLS

public static final java.lang.String HK2_CONCURRENCY_CONTROLS

System property tag for concurrency controls (i.e., true for multi threaded injection, inhabitant activation, etc.)

See Also:

Constant Field Values

singletonScope

public final org.glassfish.hk2.ScopeInstance singletonScope

MANAGED_INJECTION_POINTS_ENABLED

public static final boolean MANAGED_INJECTION_POINTS_ENABLED

See Also:

Constant Field Values

Constructor Detail

Habitat

public Habitat()

Method Detail

getDefault

public org.glassfish.hk2.Services getDefault()

Specified by:

getDefault in interface org.glassfish.hk2.Services

getServices

public org.glassfish.hk2.Services getServices(java.lang.String moduleName)

Specified by:

getServices in interface org.glassfish.hk2.Services

getDeclaredBindings

public java.util.Collection<org.glassfish.hk2.Binding<?>> getDeclaredBindings()

Specified by:

getDeclaredBindings in interface org.glassfish.hk2.Services

getDeclaredBindings

public java.util.Collection<org.glassfish.hk2.Binding<?>> getDeclaredBindings(org.glassfish.hk2.Descriptor descriptor)

Specified by:

getDeclaredBindings in interface org.glassfish.hk2.Services

getBindings

public java.util.Collection<org.glassfish.hk2.Binding<?>> getBindings()

Specified by:

getBindings in interface org.glassfish.hk2.Services

getBindings

public java.util.Collection<org.glassfish.hk2.Binding<?>> getBindings(org.glassfish.hk2.Descriptor descriptor)

Specified by:

getBindings in interface org.glassfish.hk2.Services

bindDynamically

public org.glassfish.hk2.DynamicBinderFactory bindDynamically()

Specified by:

bindDynamically in interface org.glassfish.hk2.Services

forContract

public <U> org.glassfish.hk2.ContractLocator<U> forContract(java.lang.Class<U> contract)

Specified by:

forContract in interface org.glassfish.hk2.Locator

forContract

public org.glassfish.hk2.ContractLocator<?> forContract(java.lang.String contractName)

Specified by:

forContract in interface org.glassfish.hk2.Locator

forContract

public <U> org.glassfish.hk2.ContractLocator<U> forContract(org.glassfish.hk2.TypeLiteral<U> typeLiteral)

Specified by:

forContract in interface org.glassfish.hk2.Locator

byType

public <U> org.glassfish.hk2.ServiceLocator<U> byType(java.lang.Class<U> type)

Specified by:

byType in interface org.glassfish.hk2.Locator

byType

public org.glassfish.hk2.ServiceLocator<?> byType(java.lang.String typeName)

Specified by:

byType in interface org.glassfish.hk2.Locator

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

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()

isContextualFactoriesPresentAnywhere

public static boolean isContextualFactoriesPresentAnywhere()

FOR INTERNAL USE

isContextualFactoriesPresent

public boolean isContextualFactoriesPresent()

FOR INTERNAL USE

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.reflect.Type type)

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.

getAllInhabitantsByType

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

Gets all matching inhabitants given the type.

Returns:

can be empty but never null.

addComponent

public <T> void addComponent(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:

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

Description copied from interface: SimpleServiceLocator

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

Specified by:

getComponent in interface SimpleServiceLocator

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

Returns:

null if no such service exists.

Throws:

ComponentException

getComponent

public <T> T getComponent(java.lang.String fullQualifiedName,
                          java.lang.String name)

Description copied from interface: SimpleServiceLocator

Analogous to the following:

 getComponent(contractClass.getName(), name);
 

Specified by:

getComponent in interface SimpleServiceLocator

Parameters:

fullQualifiedName - the contract class name

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

Returns:

null if no such service exists.

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

getInhabitant

public <T> Inhabitant<T> getInhabitant(java.lang.reflect.Type type,
                                       java.lang.String name)

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 <T> Inhabitant<T> getInhabitantByType(java.lang.reflect.Type implType)

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

inject

public <T> T inject(T object)

Specified by:

inject in interface org.glassfish.hk2.inject.Injector

inject

public <T> T inject(java.lang.Class<T> type)

Instantiate the passed type and injects all the Inject annotated fields and methods

Specified by:

inject in interface org.glassfish.hk2.inject.Injector

Type Parameters:

T - type of the requested instance

Parameters:

type - class of the requested instance

Returns:

the instantiated and injected instance

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:

typeName - 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)

Description copied from interface: SimpleServiceLocator

Gets the object of the given type.

Specified by:

getByType in interface SimpleServiceLocator

Returns:

null if not found.

getByType

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

Description copied from interface: SimpleServiceLocator

Gets the object of the given type.

Specified by:

getByType in interface SimpleServiceLocator

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