@Contract public interface ServiceLocator
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.
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 ActiveDescriptor s 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.
|
<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
Descriptor s 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.
|
<T> T getService(Class<T> contractOrImpl, Annotation... qualifiers) throws MultiException
Use this method only if destroying the service is not important,
otherwise use getServiceHandle(Class, Annotation...)
contractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service creation<T> T getService(Type contractOrImpl, Annotation... qualifiers) throws MultiException
Use this method only if destroying the service is not important,
otherwise use getServiceHandle(Type, Annotation...)
contractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service creation<T> T getService(Class<T> contractOrImpl, String name, Annotation... qualifiers) throws MultiException
Use this method only if destroying the service is not important,
otherwise use getServiceHandle(Class, String, Annotation...)
contractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofname
- May be null (to indicate any name is ok), and is the name of the
implementation to be returnedqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service creation<T> T getService(Type contractOrImpl, String name, Annotation... qualifiers) throws MultiException
Use this method only if destroying the service is not important,
otherwise use getServiceHandle(Type, String, Annotation...)
contractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofname
- May be null (to indicate any name is ok), and is the name of the
implementation to be returnedqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service creation<T> List<T> getAllServices(Class<T> contractOrImpl, Annotation... qualifiers) throws MultiException
Use this method only if destroying the service is not important,
otherwise use getAllServiceHandles(Class, Annotation...)
contractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service creation<T> List<T> getAllServices(Type contractOrImpl, Annotation... qualifiers) throws MultiException
Use this method only if destroying the service is not important,
otherwise use getAllServiceHandles(Type, Annotation...)
contractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service creation<T> List<T> getAllServices(Annotation qualifier, Annotation... qualifiers) throws MultiException
Use this method only if destroying the services is not important,
otherwise use getAllServiceHandles(Annotation, Annotation...)
qualifier
- May not be null, and is a qualifier that must
match the service definitionqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service creationList<?> getAllServices(Filter searchCriteria) throws MultiException
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
searchCriteria
- The returned service will match the Filter
(in other words, searchCriteria.matches returns true). May not
be nullMultiException
- if there was an error during service creation<T> ServiceHandle<T> getServiceHandle(Class<T> contractOrImpl, Annotation... qualifiers) throws MultiException
ServiceHandle
that can be used to get and destroy the
service that best matches the given criteriacontractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an issue during lookup<T> ServiceHandle<T> getServiceHandle(Type contractOrImpl, Annotation... qualifiers) throws MultiException
ServiceHandle
that can be used to get and destroy the
service that best matches the given criteriacontractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an issue during lookup<T> ServiceHandle<T> getServiceHandle(Class<T> contractOrImpl, String name, Annotation... qualifiers) throws MultiException
ServiceHandle
that can be used to get and destroy the
service that best matches the given criteriacontractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofname
- 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
definitionMultiException
- if there was an error during lookupIllegalArgumentException
- if contractOrImpl is null<T> ServiceHandle<T> getServiceHandle(Type contractOrImpl, String name, Annotation... qualifiers) throws MultiException
ServiceHandle
that can be used to get and destroy the
service that best matches the given criteriacontractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofname
- 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
definitionMultiException
- if there was an error during service lookupIllegalArgumentException
- if contractOrImpl is null<T> List<ServiceHandle<T>> getAllServiceHandles(Class<T> contractOrImpl, Annotation... qualifiers) throws MultiException
ServiceHandle
that can be used to get and destroy services
associated with descriptors that match the provided criteriacontractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service lookupIllegalArgumentException
- if contractOrImpl is nullList<ServiceHandle<?>> getAllServiceHandles(Type contractOrImpl, Annotation... qualifiers) throws MultiException
ServiceHandle
that can be used to get and destroy services
associated with descriptors that match the provided criteriacontractOrImpl
- May not be null, and is the contract
or concrete implementation to get the best instance ofqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service lookupIllegalArgumentException
- if contractOrImpl is nullList<ServiceHandle<?>> getAllServiceHandles(Annotation qualifier, Annotation... qualifiers) throws MultiException
ServiceHandle
that can be used to get and destroy services
associated with descriptors that match the provided criteriaqualifier
- May not be null, and is a qualifier that must
match the service definitionqualifiers
- The set of qualifiers that must match this service
definitionMultiException
- if there was an error during service lookupIllegalArgumentException
- if contractOrImpl is nullList<ServiceHandle<?>> getAllServiceHandles(Filter searchCriteria) throws MultiException
ServiceHandle
whose ActiveDescriptor
s match
the supplied filter. The returned ServiceHandle
s may be used to
get or destroy the services associated with the matching descriptorssearchCriteria
- A filter to use when determining which descriptors should applyMultiException
- if there was an error during service handle creationList<ActiveDescriptor<?>> getDescriptors(Filter filter)
filter
- A filter to use when determining which services should applyActiveDescriptor<?> getBestDescriptor(Filter filter)
filter
- The non-null filter to use to retrieve the best descriptorActiveDescriptor<?> reifyDescriptor(Descriptor descriptor, Injectee injectee) throws MultiException
descriptor
- The descriptor to convert, may not be nullinjectee
- The injectee on behalf of whom this descriptor is being injected. May
be null if the injectee is unknownHK2Loader
MultiException
- if there were errors when loading or analyzing the classActiveDescriptor<?> reifyDescriptor(Descriptor descriptor) throws MultiException
descriptor
- The descriptor to convert, may not be nullHK2Loader
MultiException
- if there were errors when loading or analyzing the classActiveDescriptor<?> getInjecteeDescriptor(Injectee injectee) throws MultiException
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
injectee
- the injection point for whom to find the ActiveDescriptorMultiException
- if there were errors when loading or analyzing the class<T> ServiceHandle<T> getServiceHandle(ActiveDescriptor<T> activeDescriptor, Injectee injectee) throws MultiException
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
activeDescriptor
- The descriptor for which to create a ServiceHandle
.
May not be nullinjectee
- The injectee on behalf of whom this service is being injected. May
be null if the injectee is unknownServiceHandle
that may be used to create or destroy the service
associated with this ActiveDescriptor
MultiException
- if there was an error during service handle creation<T> ServiceHandle<T> getServiceHandle(ActiveDescriptor<T> activeDescriptor) throws MultiException
ServiceHandle
that can be used to get and destroy the service
described by the ActiveDescriptor
.activeDescriptor
- The descriptor for which to create a ServiceHandle
.
May not be nullServiceHandle
that may be used to create or destroy the service
associated with this ActiveDescriptor
MultiException
- if there was an error during service handle creation@Deprecated <T> T getService(ActiveDescriptor<T> activeDescriptor, ServiceHandle<?> root) throws MultiException
getService(ActiveDescriptor, ServiceHandle, Injectee)
InjectionResolver.resolve(Injectee, ServiceHandle)
. In
this way the objects associated with the root object can be destroyed in the proper sequenceactiveDescriptor
- The descriptor whose service to createroot
- The ultimate parent of this service creation. May be nullMultiException
- if there was an error during service creation<T> T getService(ActiveDescriptor<T> activeDescriptor, ServiceHandle<?> root, Injectee injectee) throws MultiException
InjectionResolver.resolve(Injectee, ServiceHandle)
. In
this way the objects associated with the root object can be destroyed in the proper sequenceactiveDescriptor
- The descriptor whose service to createroot
- The ultimate parent of this service creation. May be nullinjectee
- The injectee passed into the InjectionResolver.resolve(Injectee, ServiceHandle)
if known,
null otherwiseMultiException
- if there was an error during service creationString getDefaultClassAnalyzerName()
void setDefaultClassAnalyzerName(String defaultClassAnalyzer)
Descriptor
s that return null as their class analyzer. If null is given
then the default class analyzer name of ClassAnalyzer.DEFAULT_IMPLEMENTATION_NAME
will be useddefaultClassAnalyzer
- 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)Unqualified getDefaultUnqualified()
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 javax.inject.IterableProvider
will not have the default
unqualified applied to itUnqualified
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 appliedvoid setDefaultUnqualified(Unqualified unqualified)
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 javax.inject.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
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 appliedorg.glassfish.hk2.utilities.UnqualifiedImpl}
String getName()
long getLocatorId()
ServiceLocator getParent()
void shutdown()
ServiceLocatorState getState()
boolean getNeutralContextClassLoader()
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
void setNeutralContextClassLoader(boolean neutralContextClassLoader)
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
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<T> T create(Class<T> createMe)
createMe
- The class to create, may not be null<T> T create(Class<T> createMe, String strategy)
createMe
- The class to create, may not be nullstrategy
- The name of the ClassAnalyzer
that should be used. If
null the default analyzer will be usedvoid inject(Object injectMe)
injectMe
- The object to be analyzed and injected intovoid inject(Object injectMe, String strategy)
injectMe
- The object to be analyzed and injected intostrategy
- The name of the ClassAnalyzer
that should be used. If
null the default analyzer will be usedObject assistedInject(Object injectMe, Method method, MethodParameter... params)
injectMe
- The non-null object to inject intomethod
- The non-null method to inject intoparams
- 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 methodIllegalArgumentException
- 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 methodObject assistedInject(Object injectMe, Method method, ServiceHandle<?> root, MethodParameter... params)
injectMe
- The non-null object to inject intomethod
- The non-null method to inject intoroot
- A possibly null ServiceHandle that can be used after this call
to destroy any hanging PerLookup instances createdparams
- 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 methodIllegalArgumentException
- 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 methodvoid postConstruct(Object postConstructMe)
postConstructMe
- The object to postConstructvoid postConstruct(Object postConstructMe, String strategy)
postConstructMe
- The object to postConstructstrategy
- The name of the ClassAnalyzer
that should be used. If
null the default analyzer will be usedvoid preDestroy(Object preDestroyMe)
preDestroyMe
- The object to preDestroyvoid preDestroy(Object preDestroyMe, String strategy)
preDestroyMe
- The object to preDestroystrategy
- The name of the ClassAnalyzer
that should be used. If
null the default analyzer will be used<U> U createAndInitialize(Class<U> createMe)
create(Class)
method followed by the inject(Object)
method followed
by the postConstruct(Object)
method.
The object created is not managed by the locator.
createMe
- The non-null class to create this object fromMultiException
- if there was an error when creating or initializing the object<U> U createAndInitialize(Class<U> createMe, String strategy)
create(Class)
method followed by the inject(Object)
method followed
by the postConstruct(Object)
method.
The object created is not managed by the locator.
createMe
- The non-null class to create this object fromstrategy
- The name of the ClassAnalyzer
that should be used. If
null the default analyzer will be usedMultiException
- if there was an error when creating or initializing the objectCopyright © 2009-2017, Oracle and/or its affiliates. All Rights Reserved.