org.glassfish.hk2.api
Interface ServiceLocator

All Known Implementing Classes:
Habitat, ServiceLocatorImpl

@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 service handles that can be used to get and destroy the returned services
 List<ServiceHandle<?>> getAllServiceHandles(Filter searchCriteria)
          Gets a service handle that can be used to get and destroy the returned service.
 List<ServiceHandle<?>> getAllServiceHandles(Type contractOrImpl, Annotation... qualifiers)
          Gets service handles that can be used to get and destroy the returned services
<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 implements this contract or has this implementation
<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 getting injectee's on behalf of some root object.
<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 service handle that can be used to get and destroy the returned service.
<T> ServiceHandle<T>
getServiceHandle(ActiveDescriptor<T> activeDescriptor, Injectee injectee)
          Gets a service handle that can be used to get and destroy the returned service.
<T> ServiceHandle<T>
getServiceHandle(Type contractOrImpl, Annotation... qualifiers)
          Gets a service handle that can be used to get and destroy the returned service.
<T> ServiceHandle<T>
getServiceHandle(Type contractOrImpl, String name, Annotation... qualifiers)
          Gets a service handle that can be used to get and destroy the returned service
 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 not be null, 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 implements this contract or has this implementation

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 service handle that can be used to get and destroy the returned service. If a service, and all per lookup services must be destroyed then this method should be used to destroy the object

It is assumed that this method is called by the top level code. All injection points created because of this invocation must use the getServiceHandle(ActiveDescriptor, ServiceHandle) method to retrieve objects, so that they can be destroyed in the proper sequence

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 service handle that can be used to get and destroy the returned service

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)
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 service handles that can be used to get and destroy the returned services

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 service handles that can be used to get and destroy the returned services

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 service handle that can be used to get and destroy the returned service. If a service, and all per lookup services must be destroyed then this method should be used to destroy the object

It is assumed that this method is called by the top level code. All injection points created because of this invocation must use the getServiceHandle(ActiveDescriptor, ServiceHandle) method to retrieve objects, so that they can be destroyed in the proper sequence

Parameters:
searchCriteria - A filter to use when determining which services should apply
Returns:
A list of handles in ranked order that match the given filter
Throws:
MultiException - if there was an error during service 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 filter to use to retrieve the set of descriptors
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

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 service handle that can be used to get and destroy the returned service. If a service, and all per lookup services must be destroyed then this method should be used to destroy the object

It is assumed that this method is called by the top level code. All injection points created because of this invocation must use the getServiceHandle(ActiveDescriptor, ServiceHandle) method to retrieve objects, so that they can be destroyed in the proper sequence

Parameters:
activeDescriptor - The service handle that can be used to get and destroy this service
injectee - The injectee on behalf of whom this descriptor is being injected. May be null if the injectee is unknown
Returns:
Will return root as a convenience
Throws:
MultiException - if there was an error during service creation

getServiceHandle

<T> ServiceHandle<T> getServiceHandle(ActiveDescriptor<T> activeDescriptor)
                                  throws MultiException
Gets a service handle that can be used to get and destroy the returned service. If a service, and all per lookup services must be destroyed then this method should be used to destroy the object

It is assumed that this method is called by the top level code. All injection points created because of this invocation must use the getServiceHandle(ActiveDescriptor, ServiceHandle) method to retrieve objects, so that they can be destroyed in the proper sequence

Parameters:
activeDescriptor - The service handle that can be used to get and destroy this service
Returns:
Will return root as a convenience
Throws:
MultiException - if there was an error during service creation

getService

<T> T getService(ActiveDescriptor<T> activeDescriptor,
                 ServiceHandle<?> root)
             throws MultiException
This method should be called by code getting injectee's on behalf of some root object. 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


Copyright © 2013 Oracle Corporation. All Rights Reserved.