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

Field Summary

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	addIndex(Inhabitant<?> i, java.lang.String index, java.lang.String name) Adds a new index to look up the given inhabitant.
<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>	getAllByType(java.lang.Class<T> implType) Gets the object of the given type.
java.util.Iterator<java.lang.String>	getAllContracts()
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<? extends 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 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.
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)
void	release() Releases all the components.
boolean	remove(Inhabitant<?> inhabitant) Removes a inhabitant
boolean	removeIndex(java.lang.String index, java.lang.Object service) Removes a Contracted service
boolean	removeIndex(java.lang.String index, java.lang.String name) Removes a NamedInhabitant for a specific contract

Methods inherited from class java.lang.Object

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

Field Detail

singletonScope

public final ScopeInstance singletonScope

Constructor Detail

Habitat

public Habitat()

Method Detail

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.

remove

public boolean remove(Inhabitant<?> inhabitant)

Removes a 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 service)

Removes a Contracted service

Parameters:

index - the contract name

service - the instance

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.

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<? extends 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.

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