|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
public interface Inhabitant<T>
Represents a component in the world of Habitat.
Inhabitant extends from Holder, as one of its
purposes is to encapsulate how we obtain an instance of a component.
On topf of that, Inhabitant enhances Holder by
adding more metadata that Habitat uses for finding
components and hooking them up together.
All the methods exept get() are immutable, meaning
they never change the value they return.
See Inhabitants for several factory methods for typical
Inhabitant constructions.
Inhabitants| Nested Class Summary |
|---|
| Nested classes/interfaces inherited from interface com.sun.hk2.component.Holder |
|---|
Holder.Impl<T> |
| Method Summary | ||
|---|---|---|
Collection<Inhabitant> |
companions()
Returns the companion inhabitants associated with this inhabitant. |
|
T |
get()
Returns the instance of this inhabitant. |
|
T |
get(Inhabitant onBehalfOf)
Returns the instance of this inhabitant. |
|
|
getSerializedMetadata(Class<T> type)
Obtains the metadata serialized into String. |
|
|
getSerializedMetadata(Class<T> type,
String key)
Obtains the serialized metadata. |
|
Inhabitant |
lead()
If this inhabitant is a companion to another inhabitant (called "lead"), This method returns that inhabitant. |
|
MultiMap<String,String> |
metadata()
Gets the metadata associated with this inhabitant. |
|
void |
release()
Called to orderly shutdown Habitat. |
|
void |
setCompanions(Collection<Inhabitant> companions)
This method is only meant to be invoked by Habitat. |
|
Class<? extends T> |
type()
Type of the inhabitant. |
|
String |
typeName()
The short-cut for type().getName()
but this allows us to defer loading the actual types. |
|
| Methods inherited from interface org.glassfish.hk2.Binding |
|---|
getDescriptor, getProvider, getProvider |
| Methods inherited from interface org.glassfish.hk2.ManagedComponentProvider |
|---|
isActive |
| Methods inherited from interface org.glassfish.hk2.Provider |
|---|
getAnnotations |
| Method Detail |
|---|
String typeName()
type().getName()
but this allows us to defer loading the actual types.
Class<? extends T> type()
The only binding contract that needs to be honored is that the get()
method returns an instance assignable to this type. That is,
get().getClass()==type() doesn't necessarily have to hold,
but type().isInstance(get()) must.
This is particularly true when Factory is involved, as in such
case HK2 has no way of knowing the actual type.
That said, this method is not designed for the semantics of
contract/implementation split --- implementations of a contract
should return the concrete type from this method, and use
habitat index
to support look-up by contract.
type in interface Provider<T>T get()
Some Inhabitants return the same instance for multiple
invocations (AKA singleton), but
the method may return different instances to invocations from different
context (AKA scope.) The extreme case is where the each invocation
returns a different object.
get in interface Factory<T>get in interface Provider<T>T get(Inhabitant onBehalfOf)
THIS METHOD SHOULD BE ONLY USED BY HK2 IMPLEMENTATION.
Inhabitants are often used with the decorator pattern
(see AbstractCreatorInhabitantImpl for example), yet during
the object initializtion inside the get() method, we often
need the reference to the outer-most Inhabitant registered to
the Habitat (for example so that we can request the injection
of {link Inhabita} that represents itself, or to inject companions.)
So this overloaded version of the get method takes the outer-most
Inhabitant. This method is only invoked from within HK2
where the decorator pattern is used.
MultiMap<String,String> metadata()
This data is usually used by a sub-system of HK2, and not really meant to
be used by applications. (At least for now.)
The main benefit of metadata is that it's available right away
as soon as the Habitat is properly initialized, even before
component classes are loaded. In contrast, accessing annotations would require
classes to be loaded and resolved.
Service.metadata()
<T> T getSerializedMetadata(Class<T> type,
String key)
This method is a wrapper around metadata() and useful for
defining a highly structured metadata that doesn't easily fit
a simple string representation.
The implementation of this method is to obtain the value associated with
this key as metadata().getOne(key), and if that exists, treat
the value as base64-encoded binary, and deserializes it and returns the object.
The classes used in the serialization need to be available during the build time (normally during the HK2 compile mojo runs) so that the metadata can be serialized. The evolution of these classes need to be careful done, otherwise the deserialization of the metadata may fail unexpectedly.
Error - If the deserialization fails. This can be for example because of
the incompatible class change, or failure to resolve the classes.
Sine these problems can only happen in a critical situation,
this method throws unchecked error.
TODO: switch this to IOError when we can depend on JDK6.<T> T getSerializedMetadata(Class<T> type)
This is a convenient short-cut that does getSerializedMetadata(type,type.getName())
void release()
Habitat.
The expected behavior is for objects to get its PreDestroy
callback invoked, and its reference released. For singleton
objects, this method is expected to dispose that object.
For scoped objects, those are released when ScopeInstance.release()
is invoked.
release in interface ManagedComponentProvider<T>Inhabitant lead()
Collection<Inhabitant> companions()
This method works with the lead() method in pairs, such
that the following condition always holds:
x.companions().contains(y) <-> y.lead()==x
void setCompanions(Collection<Inhabitant> companions)
Habitat.
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||