org.glassfish.hk2.api
Interface ServiceLocator

@Contract
public interface ServiceLocator

ServiceLocator is the registry for HK2 services

Services can be looked up from this instance

Method Summary

<T> T	create(Class<T> createMe) This method will analyze the given class, and create it if can.
<U> U	createAndInitialize(Class<U> createMe) This method creates, injects and post-constructs an object with the given class.
List<ServiceHandle<?>>	getAllServiceHandles(Annotation qualifier, Annotation... qualifiers) Gets a list of ServiceHandle that can be used to get and destroy services associated with descriptors that match the provided criteria
List<ServiceHandle<?>>	getAllServiceHandles(Filter searchCriteria) Gets a list of ServiceHandle whose ActiveDescriptors match the supplied filter.
List<ServiceHandle<?>>	getAllServiceHandles(Type contractOrImpl, Annotation... qualifiers) Gets a list of ServiceHandle that can be used to get and destroy services associated with descriptors that match the provided criteria
<T> List<T>	getAllServices(Annotation qualifier, Annotation... qualifiers) Gets the all the services from this locator that has the given qualifier or qualifiers
List<?>	getAllServices(Filter searchCriteria) Gets the all the services from this locator that matches the Filter
<T> List<T>	getAllServices(Type contractOrImpl, Annotation... qualifiers) Gets the all the services from this locator that implements this contract or has this implementation
ActiveDescriptor<?>	getBestDescriptor(Filter filter) Gets the descriptor that best matches this filter, taking ranking and service id into account
List<ActiveDescriptor<?>>	getDescriptors(Filter filter) Gets the list of descriptors that match the given filter
ActiveDescriptor<?>	getInjecteeDescriptor(Injectee injectee) This method will first find a descriptor for this injectee, and then reify that descriptor.
long	getLocatorId() This returns the unique locator ID for this locator.
String	getName() Returns the name of this ServiceLocator
<T> T	getService(ActiveDescriptor<T> activeDescriptor, ServiceHandle<?> root) This method should be called by code resolving injectee's on behalf of some root service, usually by an implementation of InjectionResolver.resolve(Injectee, ServiceHandle).
<T> T	getService(Type contractOrImpl, Annotation... qualifiers) Gets the best service from this locator that implements this contract or has this implementation
<T> T	getService(Type contractOrImpl, String name, Annotation... qualifiers) Gets the best service from this locator that implements this contract or has this implementation and has the given name
<T> ServiceHandle<T>	getServiceHandle(ActiveDescriptor<T> activeDescriptor) Gets a ServiceHandle that can be used to get and destroy the service described by the ActiveDescriptor.
<T> ServiceHandle<T>	getServiceHandle(ActiveDescriptor<T> activeDescriptor, Injectee injectee) Gets a ServiceHandle that can be used to get and destroy the service described by the ActiveDescriptor.
<T> ServiceHandle<T>	getServiceHandle(Type contractOrImpl, Annotation... qualifiers) Gets a ServiceHandle that can be used to get and destroy the service that best matches the given criteria
<T> ServiceHandle<T>	getServiceHandle(Type contractOrImpl, String name, Annotation... qualifiers) Gets a ServiceHandle that can be used to get and destroy the service that best matches the given criteria
void	inject(Object injectMe) This will analyze the given object and inject into its fields and methods.
void	postConstruct(Object postConstructMe) This will analyze the given object and call the postConstruct method.
void	preDestroy(Object preDestroyMe) This will analyze the given object and call the preDestroy method.
ActiveDescriptor<?>	reifyDescriptor(Descriptor descriptor) Converts a descriptor to an ActiveDescriptor.
ActiveDescriptor<?>	reifyDescriptor(Descriptor descriptor, Injectee injectee) Converts a descriptor to an ActiveDescriptor.
void	shutdown() This method will shutdown every service associated with this ServiceLocator.

Method Detail

getService

<T> T getService(Type contractOrImpl,
                 Annotation... qualifiers)
             throws MultiException

Gets the best service from this locator that implements this contract or has this implementation

Use this method only if destroying the service is not important

Parameters:

contractOrImpl - May not be null, and is the contract or concrete implementation to get the best instance of

qualifiers - The set of qualifiers that must match this service definition

Returns:

An instance of the contract or impl. May return null if there is no provider that provides the given implementation or contract

Throws:

MultiException - if there was an error during service creation

getService

<T> T getService(Type contractOrImpl,
                 String name,
                 Annotation... qualifiers)
             throws MultiException

Gets the best service from this locator that implements this contract or has this implementation and has the given name

Use this method only if destroying the service is not important

Parameters:

contractOrImpl - May not be null, and is the contract or concrete implementation to get the best instance of

name - May be null (to indicate any name is ok), and is the name of the implementation to be returned

qualifiers - The set of qualifiers that must match this service definition

Returns:

An instance of the contract or impl. May return null if there is no provider that provides the given implementation or contract

Throws:

MultiException - if there was an error during service creation

getAllServices

<T> List<T> getAllServices(Type contractOrImpl,
                           Annotation... qualifiers)
                       throws MultiException

Gets the all the services from this locator that implements this contract or has this implementation

Use this method only if destroying the service is not important

Parameters:

contractOrImpl - May not be null, and is the contract or concrete implementation to get the best instance of

qualifiers - The set of qualifiers that must match this service definition

Returns:

A list of services implementing this contract or concrete implementation. May not return null, but may return an empty list

Throws:

MultiException - if there was an error during service creation

getAllServices

<T> List<T> getAllServices(Annotation qualifier,
                           Annotation... qualifiers)
                       throws MultiException

Gets the all the services from this locator that has the given qualifier or qualifiers

Use this method only if destroying the services is not important

Parameters:

qualifier - May not be null, and is a qualifier that must match the service definition

qualifiers - The set of qualifiers that must match this service definition

Returns:

A list of services implementing this contract or concrete implementation. May not return null, but may return an empty list

Throws:

MultiException - if there was an error during service creation

getAllServices

List<?> getAllServices(Filter searchCriteria)
                       throws MultiException

Gets the all the services from this locator that matches the Filter

Use this method only if destroying the service is not important

This method should also be used with care to avoid classloading a large number of services

Parameters:

searchCriteria - The returned service will match the Filter (in other words, searchCriteria.matches returns true). May not be null

Returns:

A list of services matching this filter. May not return null, but may return an empty list

Throws:

MultiException - if there was an error during service creation

getServiceHandle

<T> ServiceHandle<T> getServiceHandle(Type contractOrImpl,
                                      Annotation... qualifiers)
                                  throws MultiException

Gets a ServiceHandle that can be used to get and destroy the service that best matches the given criteria

Parameters:

contractOrImpl - May not be null, and is the contract or concrete implementation to get the best instance of

qualifiers - The set of qualifiers that must match this service definition

Returns:

Will return root as a convenience

Throws:

MultiException - if there was an error during service creation

getServiceHandle

<T> ServiceHandle<T> getServiceHandle(Type contractOrImpl,
                                      String name,
                                      Annotation... qualifiers)
                                  throws MultiException

Gets a ServiceHandle that can be used to get and destroy the service that best matches the given criteria

Parameters:

contractOrImpl - May not be null, and is the contract or concrete implementation to get the best instance of

name - The name to use to further qualify the search (may be null, indicating that any name will match)

qualifiers - The set of qualifiers that must match this service definition

Returns:

Will the service handle for the best service matching the given criteria, or null if no matching service could be found

Throws:

MultiException - if there was an error during service creation

IllegalArgumentException - if contractOrImpl is null

getAllServiceHandles

List<ServiceHandle<?>> getAllServiceHandles(Type contractOrImpl,
                                            Annotation... qualifiers)
                                            throws MultiException

Gets a list of ServiceHandle that can be used to get and destroy services associated with descriptors that match the provided criteria

Parameters:

contractOrImpl - May not be null, and is the contract or concrete implementation to get the best instance of

qualifiers - The set of qualifiers that must match this service definition

Returns:

A non-null but possibly empty list of service handles matching the given criteria

Throws:

MultiException - if there was an error during service creation

IllegalArgumentException - if contractOrImpl is null

getAllServiceHandles

List<ServiceHandle<?>> getAllServiceHandles(Annotation qualifier,
                                            Annotation... qualifiers)
                                            throws MultiException

Gets a list of ServiceHandle that can be used to get and destroy services associated with descriptors that match the provided criteria

Parameters:

qualifier - May not be null, and is a qualifier that must match the service definition

qualifiers - The set of qualifiers that must match this service definition

Returns:

A non-null but possibly empty list of service handles matching the given criteria

Throws:

MultiException - if there was an error during service creation

IllegalArgumentException - if contractOrImpl is null

getAllServiceHandles

List<ServiceHandle<?>> getAllServiceHandles(Filter searchCriteria)
                                            throws MultiException

Gets a list of ServiceHandle whose ActiveDescriptors match the supplied filter. The returned ServiceHandles may be used to get or destroy the services associated with the matching descriptors

Parameters:

searchCriteria - A filter to use when determining which descriptors should apply

Returns:

A list of service handles in ranked order that match the given filter

Throws:

MultiException - if there was an error during service handle creation

getDescriptors

List<ActiveDescriptor<?>> getDescriptors(Filter filter)

Gets the list of descriptors that match the given filter

Parameters:

filter - A filter to use when determining which services should apply

Returns:

A list of descriptors in ranked order that match the given filter

getBestDescriptor

ActiveDescriptor<?> getBestDescriptor(Filter filter)

Gets the descriptor that best matches this filter, taking ranking and service id into account

Parameters:

filter - The non-null filter to use to retrieve the best descriptor

Returns:

The best descriptor matching the filter, or null if there is no descriptor that matches the filter

reifyDescriptor

ActiveDescriptor<?> reifyDescriptor(Descriptor descriptor,
                                    Injectee injectee)
                                    throws MultiException

Converts a descriptor to an ActiveDescriptor. Will use the registered HK2Loaders to perform this action. If no HK2Loader is available for the descriptor, will use the injectee to discover a classloader

Parameters:

descriptor - The descriptor to convert, may not be null

injectee - The injectee on behalf of whom this descriptor is being injected. May be null if the injectee is unknown

Returns:

The active descriptor as loaded with the first valid HK2Loader

Throws:

MultiException - if there were errors when loading or analyzing the class

reifyDescriptor

ActiveDescriptor<?> reifyDescriptor(Descriptor descriptor)
                                    throws MultiException

Converts a descriptor to an ActiveDescriptor. Will use the registered HK2Loaders to perform this action

Parameters:

descriptor - The descriptor to convert, may not be null

Returns:

The active descriptor as loaded with the first valid HK2Loader

Throws:

MultiException - if there were errors when loading or analyzing the class

getInjecteeDescriptor

ActiveDescriptor<?> getInjecteeDescriptor(Injectee injectee)
                                          throws MultiException

This method will first find a descriptor for this injectee, and then reify that descriptor. If multiple descriptors are found, they will be reified in ranking order until an ActiveDescriptor matching the Injectee is found.

Parameters:

injectee - the injection point for whom to find the ActiveDescriptor

Returns:

The active descriptor for this injection point

Throws:

MultiException - if there were errors when loading or analyzing the class

getServiceHandle

<T> ServiceHandle<T> getServiceHandle(ActiveDescriptor<T> activeDescriptor,
                                      Injectee injectee)
                                  throws MultiException

Gets a ServiceHandle that can be used to get and destroy the service described by the ActiveDescriptor. The injectee may be used to discover the proper classloader to use when attempting to reify the ActiveDescriptor

Parameters:

activeDescriptor - The descriptor for which to create a ServiceHandle. May not be null

injectee - The injectee on behalf of whom this service is being injected. May be null if the injectee is unknown

Returns:

A ServiceHandle that may be used to create or destroy the service associated with this ActiveDescriptor

Throws:

MultiException - if there was an error during service handle creation

getServiceHandle

<T> ServiceHandle<T> getServiceHandle(ActiveDescriptor<T> activeDescriptor)
                                  throws MultiException

Gets a ServiceHandle that can be used to get and destroy the service described by the ActiveDescriptor.

Parameters:

activeDescriptor - The descriptor for which to create a ServiceHandle. May not be null

Returns:

A ServiceHandle that may be used to create or destroy the service associated with this ActiveDescriptor

Throws:

MultiException - if there was an error during service handle creation

getService

<T> T getService(ActiveDescriptor<T> activeDescriptor,
                 ServiceHandle<?> root)
             throws MultiException

This method should be called by code resolving injectee's on behalf of some root service, usually by an implementation of InjectionResolver.resolve(Injectee, ServiceHandle). In this way the objects associated with the root object can be destroyed in the proper sequence

Parameters:

activeDescriptor - The descriptor whose service to create

root - The ultimate parent of this service creation. May be null

Returns:

The service matching this descriptor

Throws:

MultiException - if there was an error during service creation

getName

String getName()

Returns the name of this ServiceLocator

Returns:

The name of this ServiceLocator, will not return null

getLocatorId

long getLocatorId()

This returns the unique locator ID for this locator. The locator ID will be assigned at the time of creation and must be a monotonacally increasing number (starting at zero)

Returns:

The identifier for this service locator

shutdown

void shutdown()

This method will shutdown every service associated with this ServiceLocator. Those services that have a preDestroy shall have their preDestroy called

create

<T> T create(Class<T> createMe)

This method will analyze the given class, and create it if can. The object created in this way will not be managed by HK2. It is the responsibility of the caller to ensure that any lifecycle this object has is honored

Parameters:

createMe - The class to create, may not be null

Returns:

An instance of the object

inject

void inject(Object injectMe)

This will analyze the given object and inject into its fields and methods. The object injected in this way will not be managed by HK2

Parameters:

injectMe - The object to be analyzed and injected into

postConstruct

void postConstruct(Object postConstructMe)

This will analyze the given object and call the postConstruct method. The object given will not be managed by HK2

Parameters:

postConstructMe - The object to postConstruct

preDestroy

void preDestroy(Object preDestroyMe)

This will analyze the given object and call the preDestroy method. The object given will not be managed by HK2

Parameters:

preDestroyMe - The object to preDestroy

createAndInitialize

<U> U createAndInitialize(Class<U> createMe)

This method creates, injects and post-constructs an object with the given class. This is equivalent to calling the create(Class) method followed by the inject(Object) method followed by the postConstruct(Object) method.

The object created is not managed by the locator.

Parameters:

createMe - The non-null class to create this object from

Returns:

An instance of the object that has been created, injected and post constructed

Throws:

MultiException - if there was an error when creating or initializing the object