org.jvnet.hk2.component
Interface Inhabitant<T>

All Superinterfaces:
Binding<T>, Descriptor, Factory<T>, Holder<T>, ManagedComponentProvider<T>, Provider<T>, Releasable
All Known Subinterfaces:
Creator<T>
All Known Implementing Classes:
AbstractCreatorImpl, AbstractCreatorInhabitantImpl, AbstractInhabitantImpl, ConfigBean, ConstructorCreator, CreatorImpl, Dom, EventPublishingInhabitant, ExistingSingletonInhabitant, InhabitantImpl, LazyInhabitant, ScopedInhabitant

Deprecated.

@Deprecated
public interface Inhabitant<T>
extends Binding<T>, ManagedComponentProvider<T>, Holder<T>, Descriptor

Represents a component in the world of ServiceLocator.

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

Author:
Kohsuke Kawaguchi
See Also:
Inhabitants

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.sun.hk2.component.Holder
Holder.Impl<T>
 
Method Summary
 Collection<Inhabitant> companions()
          Deprecated. Returns the companion inhabitants associated with this inhabitant.
 T get()
          Deprecated. Returns the instance of this inhabitant.
 T get(Inhabitant onBehalfOf)
          Deprecated. Returns the instance of this inhabitant.
<T> T
getSerializedMetadata(Class<T> type)
          Deprecated. Obtains the metadata serialized into String.
<T> T
getSerializedMetadata(Class<T> type, String key)
          Deprecated. Obtains the serialized metadata.
 Inhabitant lead()
          Deprecated. If this inhabitant is a companion to another inhabitant (called "lead"), This method returns that inhabitant.
 Map<String,List<String>> metadata()
          Deprecated. Gets the metadata associated with this inhabitant.
 void release()
          Deprecated. Called to orderly shutdown ServiceLocator.
 void setCompanions(Collection<Inhabitant> companions)
          Deprecated. This method is only meant to be invoked by ServiceLocator.
 Class<? extends T> type()
          Deprecated. Type of the inhabitant.
 String typeName()
          Deprecated. 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.Provider
getAnnotations, getByType, isActive
 
Methods inherited from interface org.glassfish.hk2.api.Descriptor
getAdvertisedContracts, getBaseDescriptor, getDescriptorType, getImplementation, getLoader, getLocatorId, getMetadata, getName, getQualifiers, getRanking, getScope, getServiceId, setRanking
 

Method Detail

typeName

String typeName()
Deprecated. 
The short-cut for type().getName() but this allows us to defer loading the actual types.


type

Class<? extends T> type()
Deprecated. 
Type of the inhabitant.

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.

Specified by:
type in interface Provider<T>
Returns:
Always non-null, same value.

get

T get()
Deprecated. 
Returns the instance of this inhabitant.

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.

Specified by:
get in interface Factory<T>
Specified by:
get in interface Provider<T>
Returns:
null is a valid return value. This is useful when a factory primarily does a look-up and it fails to find the specified component, yet you don't want that by itself to be an error. If the injection wants a non-null value (i.e., @Inject(optional=false)).

get

T get(Inhabitant onBehalfOf)
Deprecated. 
Returns the instance of this inhabitant.

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 ServiceLocator (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.


metadata

Map<String,List<String>> metadata()
Deprecated. 
Gets the metadata associated with this inhabitant.

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 ServiceLocator is properly initialized, even before component classes are loaded. In contrast, accessing annotations would require classes to be loaded and resolved.

Returns:
can be empty but never null. The values are read-only.
See Also:
Service.metadata()

getSerializedMetadata

<T> T getSerializedMetadata(Class<T> type,
                            String key)
Deprecated. 
Obtains the serialized metadata.

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.

Returns:
the deserialized object.
Throws:
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.

getSerializedMetadata

<T> T getSerializedMetadata(Class<T> type)
Deprecated. 
Obtains the metadata serialized into String.

This is a convenient short-cut that does getSerializedMetadata(type,type.getName())


release

void release()
Deprecated. 
Called to orderly shutdown ServiceLocator.

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.

Specified by:
release in interface Releasable

lead

Inhabitant lead()
Deprecated. 
If this inhabitant is a companion to another inhabitant (called "lead"), This method returns that inhabitant. Otherwise null.


companions

Collection<Inhabitant> companions()
Deprecated. 
Returns the companion inhabitants associated with this inhabitant.

This method works with the lead() method in pairs, such that the following condition always holds:

x.companions().contains(y) <-> y.lead()==x

Returns:
Can be empty but never null.

setCompanions

void setCompanions(Collection<Inhabitant> companions)
Deprecated. 
This method is only meant to be invoked by ServiceLocator.



Copyright © 2013 Oracle Corporation. All Rights Reserved.