org.glassfish.hk2.api

Interface ServiceLocator

@Contract
public interface ServiceLocator

ServiceLocator is the registry for HK2 services

This service is the most fundamental service in an HK2 system. Every service locator starts with a ServiceLocator as a service, and hence ServiceLocators can be injected into every object managed by HK2.

A service locator can have a single parent. Services are looked up in the current service locator and in all the parents of the service locator. If multiple services exist that match the filter they will all be returned. Two services with the same priority are sorted first by service locator id and second by service id. This implies that services directly installed in a ServiceLocator have higher natural priority than those in the parents of the ServiceLocator. Services can also be marked as having visibility LOCAL, in which case they will only be available to the ServiceLocator performing the lookup, and will not leak out to children of that ServiceLocator.

Method Summary

Modifier and Type	Method and Description
Object	assistedInject(Object injectMe, Method method, MethodParameter... params) This will invoke the given method on the given object.
Object	assistedInject(Object injectMe, Method method, ServiceHandle<?> root, MethodParameter... params) This will invoke the given method on the given object.
<T> T	create(Class<T> createMe) This method will analyze the given class, and create it if can.
<T> T	create(Class<T> createMe, String strategy) 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.
<U> U	createAndInitialize(Class<U> createMe, String strategy) 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
<T> List<ServiceHandle<T>>	getAllServiceHandles(Class<T> 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
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 all services from this locator that have the provided qualifiers
<T> List<T>	getAllServices(Class<T> contractOrImpl, Annotation... qualifiers) Gets all services from this locator that implement this contract or have this implementation and have the provided qualifiers
List<?>	getAllServices(Filter searchCriteria) Gets all services from this locator that match the provided Filter
<T> List<T>	getAllServices(Type contractOrImpl, Annotation... qualifiers) Gets all services from this locator that implement this contract or have this implementation and have the provided qualifiers
ActiveDescriptor<?>	getBestDescriptor(Filter filter) Gets the descriptor that best matches this filter, taking ranking and service id into account
String	getDefaultClassAnalyzerName() Gets the name of the default class analyzer service
Unqualified	getDefaultUnqualified() This returns the default Unqualified annotation that will be put on all injection points that do not have any qualifiers.
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
boolean	getNeutralContextClassLoader() This returns the value of neutralContextClassLoader.
ServiceLocator	getParent() Gets the parent service locator for this locator
<T> T	getService(ActiveDescriptor<T> activeDescriptor, ServiceHandle<?> root) Deprecated. use getService(ActiveDescriptor, ServiceHandle, Injectee)
<T> T	getService(ActiveDescriptor<T> activeDescriptor, ServiceHandle<?> root, Injectee injectee) 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(Class<T> contractOrImpl, Annotation... qualifiers) Gets the best service from this locator that implements this contract or has this implementation
<T> T	getService(Class<T> 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> 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(Class<T> 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(Class<T> contractOrImpl, String name, 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, 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
ServiceLocatorState	getState() Returns the current state of this service locator.
void	inject(Object injectMe) This will analyze the given object and inject into its fields and methods.
void	inject(Object injectMe, String strategy) 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	postConstruct(Object postConstructMe, String strategy) 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.
void	preDestroy(Object preDestroyMe, String strategy) 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	setDefaultClassAnalyzerName(String defaultClassAnalyzer) Sets the name of the default class analyzer that should be used for all Descriptors that return null as their class analyzer.
void	setDefaultUnqualified(Unqualified unqualified) This sets the default Unqualified annotation that will be put on all injection points that do not have any qualifiers.
void	setNeutralContextClassLoader(boolean neutralContextClassLoader) This sets the value of neutralContextClassLoader.
void	shutdown() This method will shutdown every service associated with this ServiceLocator.

Method Detail

getService

<T> T getService(Class<T> 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, otherwise use getServiceHandle(Class, Annotation...)

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,
                 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, otherwise use getServiceHandle(Type, Annotation...)

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(Class<T> 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, otherwise use getServiceHandle(Class, String, Annotation...)

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

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, otherwise use getServiceHandle(Type, String, Annotation...)

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(Class<T> contractOrImpl,
                           Annotation... qualifiers)
                    throws MultiException

Gets all services from this locator that implement this contract or have this implementation and have the provided qualifiers

Use this method only if destroying the service is not important, otherwise use getAllServiceHandles(Class, Annotation...)

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(Type contractOrImpl,
                           Annotation... qualifiers)
                    throws MultiException

Gets all services from this locator that implement this contract or have this implementation and have the provided qualifiers

Use this method only if destroying the service is not important, otherwise use getAllServiceHandles(Type, Annotation...)

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 all services from this locator that have the provided qualifiers

Use this method only if destroying the services is not important, otherwise use getAllServiceHandles(Annotation, Annotation...)

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 all services from this locator that match the provided Filter

Use this method only if destroying the service is not important, otherwise use getAllServiceHandles(Filter)

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(Class<T> 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 the service handle corresponding to the service or null if none were found

Throws:

MultiException - if there was an issue during lookup

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 the service handle corresponding to the service or null if none were found

Throws:

MultiException - if there was an issue during lookup

getServiceHandle

<T> ServiceHandle<T> getServiceHandle(Class<T> 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 lookup

IllegalArgumentException - if contractOrImpl is null

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 lookup

IllegalArgumentException - if contractOrImpl is null

getAllServiceHandles

<T> List<ServiceHandle<T>> getAllServiceHandles(Class<T> 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 lookup

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 lookup

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 lookup

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 non-null but possibly empty list of service handles 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 non-null but possibly empty 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.

This method is responsible for using the available JustInTimeInjectionResolver to add in new descriptors should the descriptor for the given injectee not be found initially

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

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

Deprecated. use getService(ActiveDescriptor, ServiceHandle, Injectee)

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

getService

<T> T getService(ActiveDescriptor<T> activeDescriptor,
                 ServiceHandle<?> root,
                 Injectee injectee)
          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

injectee - The injectee passed into the InjectionResolver.resolve(Injectee, ServiceHandle) if known, null otherwise

Returns:

The service matching this descriptor

Throws:

MultiException - if there was an error during service creation

getDefaultClassAnalyzerName

String getDefaultClassAnalyzerName()

Gets the name of the default class analyzer service

Returns:

The name of the default class analyzer. Will not return null

setDefaultClassAnalyzerName

void setDefaultClassAnalyzerName(String defaultClassAnalyzer)

Sets the name of the default class analyzer that should be used for all Descriptors that return null as their class analyzer. If null is given then the default class analyzer name of ClassAnalyzer.DEFAULT_IMPLEMENTATION_NAME will be used

Parameters:

defaultClassAnalyzer - The possibly null name of the default class analyzer (the class analyzer that will be used if a descriptor has not explicitly set the name of its class analyzer)

getDefaultUnqualified

Unqualified getDefaultUnqualified()

This returns the default Unqualified annotation that will be put on all injection points that do not have any qualifiers. This Unqualified will not be returned by the Injectee.getUnqualified() method as it is considered to be the systems default Unqualified annotation. If an injection point has its own Unqualified annotation returned from Injectee.getUnqualified() then that one takes precedence over this one. Further any injection point that is a IterableProvider will not have the default unqualified applied to it

Returns:

The Unqualified annotation that will be (virtually) put on injection points that have no qualifiers and no other Unqualified annotation. If null then this ServiceLocator has no default Unqualified annotation to be applied

setDefaultUnqualified

void setDefaultUnqualified(Unqualified unqualified)

This sets the default Unqualified annotation that will be put on all injection points that do not have any qualifiers. This Unqualified will not be returned by the Injectee.getUnqualified() method as it is considered to be the systems default Unqualified annotation. If an injection point has its own Unqualified annotation returned from Injectee.getUnqualified() then that one takes precedence over this one. Further any injection point that is a IterableProvider will not have the default unqualified applied to it

This method may be called at any time, but will only affect lookups and injections that have not yet occurred

Parameters:

unqualified - The Unqualified annotation that will be (virtually) put on injection points that have no qualifiers and no other Unqualified annotation. If null then this ServiceLocator has no default Unqualified annotation to be applied

See Also:

UnqualifiedImpl

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

getParent

ServiceLocator getParent()

Gets the parent service locator for this locator

Returns:

The parent service locator for this locator, or null if this service locator does not have a parent

shutdown

void shutdown()

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

getState

ServiceLocatorState getState()

Returns the current state of this service locator. This method will work in all service locator states

Returns:

The current state of the service locator

getNeutralContextClassLoader

boolean getNeutralContextClassLoader()

This returns the value of neutralContextClassLoader. If this value is true then HK2 will ensure that the context class loader on the thread is maintained whenever hk2 calls into user code. If this value is false then the value of the context class loader on the thread may be changed by the code hk2 is calling.

When set to false this value is used to increase performance since getting and setting the context class loader can be expensive. However, if the user code being called by hk2 may change the context class loader of the thread, this value should be true to ensure that tricky and hard to find bugs don't arise when this thread is used for other purposes later on

All new ServiceLocator implementation have this value initially set to true

Returns:

If true hk2 will ensure that the context class loader cannot be changed by user code. If false hk2 will not modify the context class loader of the thread when user code has finished

setNeutralContextClassLoader

void setNeutralContextClassLoader(boolean neutralContextClassLoader)

This sets the value of neutralContextClassLoader. If this value is true then HK2 will ensure that the context class loader on the thread is maintained whenever hk2 calls into user code. If this value is false then the value of the context class loader on the thread may be changed by the code hk2 is calling.

When set to false this value is used to increase performance since getting and setting the context class loader can be expensive. However, if the user code being called by hk2 may change the context class loader of the thread, this value should be true to ensure that tricky and hard to find bugs don't arise when this thread is used for other purposes later on

All new ServiceLocator implementation have this value initially set to true

Parameters:

neutralContextClassLoader - true if hk2 should ensure context class loader neutrality, false if hk2 should not change the context class loader on the thread around user code calls

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

create

<T> T create(Class<T> createMe,
             String strategy)

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

strategy - The name of the ClassAnalyzer that should be used. If null the default analyzer will be used

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

inject

void inject(Object injectMe,
            String strategy)

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

strategy - The name of the ClassAnalyzer that should be used. If null the default analyzer will be used

assistedInject

Object assistedInject(Object injectMe,
                      Method method,
                      MethodParameter... params)

This will invoke the given method on the given object. The values for the method will either be taken from the params list or will be gotten from this ServiceLocator taking into account all injection resolvers

Parameters:

injectMe - The non-null object to inject into

method - The non-null method to inject into

params - A list of parameter values known by the caller. The indexes in params may not repeat and must be in the valid range of parameters for the passed in method

Returns:

The return value of the method (null if the method is void type)

Throws:

IllegalArgumentException - if their is more than one of the same index in the params list or the index of one of the params is out of range of the parameters in the method

assistedInject

Object assistedInject(Object injectMe,
                      Method method,
                      ServiceHandle<?> root,
                      MethodParameter... params)

This will invoke the given method on the given object. The values for the method will either be taken from the params list or will be gotten from this ServiceLocator taking into account all injection resolvers

Parameters:

injectMe - The non-null object to inject into

method - The non-null method to inject into

root - A possibly null ServiceHandle that can be used after this call to destroy any hanging PerLookup instances created

params - A list of parameter values known by the caller. The indexes in params may not repeat and must be in the valid range of parameters for the passed in method

Returns:

The return value of the method (null if the method is void type)

Throws:

IllegalArgumentException - if their is more than one of the same index in the params list or the index of one of the params is out of range of the parameters in the method

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

postConstruct

void postConstruct(Object postConstructMe,
                   String strategy)

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

strategy - The name of the ClassAnalyzer that should be used. If null the default analyzer will be used

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

preDestroy

void preDestroy(Object preDestroyMe,
                String strategy)

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

strategy - The name of the ClassAnalyzer that should be used. If null the default analyzer will be used

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

createAndInitialize

<U> U createAndInitialize(Class<U> createMe,
                          String strategy)

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

strategy - The name of the ClassAnalyzer that should be used. If null the default analyzer will be used

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