hk2 4.0.1 · org.glassfish.hk2.api.DynamicConfiguration

Method Summary

Modifier and Type	Method and Description
public <T> ActiveDescriptor<T>	Returns: The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate addActiveDescriptor(ActiveDescriptor<T> The reified active descriptor to be added to the system. The system will not attempt to reify this descriptor itself activeDescriptor) This allows third party systems to add reified active descriptors to the system.
public <T> ActiveDescriptor<T>	Returns: The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate addActiveDescriptor(ActiveDescriptor<T> The reified active descriptor to be added to the system. The system will not attempt to reify this descriptor itself activeDescriptor, boolean If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking) requiresDeepCopy) This allows third party systems to add reified active descriptors to the system.
public <T> ActiveDescriptor<T>	Returns: The active (reified) descriptor that has been added to the system, with all fields filled in based on the rawClass addActiveDescriptor(Class<T> The class to analyze, must not be null rawClass) This adds an active descriptor to the system based completely on the analysis of the given class.
public <T> FactoryDescriptors	Returns: The factory descriptors that have been added to the system, with all fields filled in based on the rawFactoryClass addActiveFactoryDescriptor(Class<? extends Factory<T>> The class to analyze, must not be null rawFactoryClass) This adds two active descriptors to the system based completely on the analysis of the given `Factory` class.
public void	addIdempotentFilter(Filter... A non-null idempotent filter to use during commit. If any descriptors match the filter, the commit will fail idempotentFilter) At commit time all idempotent filters in this dynamic configuration will be run against all validation-visible descriptors.
public void	addUnbindFilter(Filter This filter will be added to the list of filters that this configuration object will use to determine which descriptors to unbind from the system. May not be null unbindFilter) This filter will added to the list of filters in this Configuration that will determine which Descriptors will be removed from the system.
public <T> ActiveDescriptor<T>	Returns: The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate bind(Descriptor May not be null. Will be used to derive the various key fields associated with the given provider key) This method will bind the given descriptor to this Module.
public <T> ActiveDescriptor<T>	Returns: The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate bind(Descriptor May not be null. Will be used to derive the various key fields associated with the given provider key, boolean If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking) requiresDeepCopy) This method will bind the given descriptor to this Module.
public FactoryDescriptors	Returns: The descriptors returned from this object may be cast to ActiveDescriptor and will contain all the fields of the descriptors filled in by the system bind(FactoryDescriptors A description of a factory service and the type the factory service provides. May not be null factoryDescriptors) This method will bind the descriptors found in the `FactoryDescriptors`.
public FactoryDescriptors	Returns: The descriptors returned from this object may be cast to ActiveDescriptor and will contain all the fields of the descriptors filled in by the system bind(FactoryDescriptors A description of a factory service and the type the factory service provides. May not be null factoryDescriptors, boolean If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking) requiresDeepCopy) This method will bind the descriptors found in the `FactoryDescriptors`.
public void	commit() This causes the configuration to get committed.
public void	registerTwoPhaseResources(TwoPhaseResource... A list of resources to add to this dynamic configuration resources) Registers two-phase resources in the order in which they are to run.

Method Detail

addActiveDescriptor	back to summary
public <T> ActiveDescriptor<T> addActiveDescriptor(ActiveDescriptor<T> activeDescriptor) throws IllegalArgumentException This allows third party systems to add reified active descriptors to the system. The active descriptor given must be fully reified (isReified must return true) and the create and destroy methods must be implemented. A deep copy will be made of the descriptor Parameters activeDescriptor:ActiveDescriptor<T> The reified active descriptor to be added to the system. The system will not attempt to reify this descriptor itself Returns:ActiveDescriptor<T> The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate Exceptions IllegalArgumentException: if the descriptor is not reified

addActiveDescriptor

back to summary

public <T> ActiveDescriptor<T> addActiveDescriptor(ActiveDescriptor<T> activeDescriptor) throws IllegalArgumentException

This allows third party systems to add reified active descriptors to the system. The active descriptor given must be fully reified (isReified must return true) and the create and destroy methods must be implemented. A deep copy will be made of the descriptor

Parameters

activeDescriptor:ActiveDescriptor<T>: The reified active descriptor to be added to the system. The system will not attempt to reify this descriptor itself

Returns:ActiveDescriptor<T>

The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate

Exceptions

IllegalArgumentException:: if the descriptor is not reified

addActiveDescriptor	back to summary
public <T> ActiveDescriptor<T> addActiveDescriptor(ActiveDescriptor<T> activeDescriptor, boolean requiresDeepCopy) throws IllegalArgumentException This allows third party systems to add reified active descriptors to the system. The active descriptor given must be fully reified (isReified must return true) and the create and destroy methods must be implemented. A deep copy will be made of the descriptor Parameters activeDescriptor:ActiveDescriptor<T> The reified active descriptor to be added to the system. The system will not attempt to reify this descriptor itself requiresDeepCopy:boolean If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking) Returns:ActiveDescriptor<T> The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate Exceptions IllegalArgumentException: if the descriptor is not reified

addActiveDescriptor

back to summary

public <T> ActiveDescriptor<T> addActiveDescriptor(ActiveDescriptor<T> activeDescriptor, boolean requiresDeepCopy) throws IllegalArgumentException

Parameters

activeDescriptor:ActiveDescriptor<T>: The reified active descriptor to be added to the system. The system will not attempt to reify this descriptor itself
requiresDeepCopy:boolean: If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking)

Returns:ActiveDescriptor<T>

The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate

Exceptions

IllegalArgumentException:: if the descriptor is not reified

addActiveDescriptor	back to summary
public <T> ActiveDescriptor<T> addActiveDescriptor(Class<T> rawClass) throws MultiException, IllegalArgumentException This adds an active descriptor to the system based completely on the analysis of the given class. The class itself and all interfaces marked contract will be in the list of advertised services. The scope and qualifiers will be taken from the annotations on the class. Parameters rawClass:Class<T> The class to analyze, must not be null Returns:ActiveDescriptor<T> The active (reified) descriptor that has been added to the system, with all fields filled in based on the rawClass Exceptions MultiException: If this class cannot be a service IllegalArgumentException: if rawClass is null

addActiveDescriptor

back to summary

public <T> ActiveDescriptor<T> addActiveDescriptor(Class<T> rawClass) throws MultiException, IllegalArgumentException

This adds an active descriptor to the system based completely on the analysis of the given class. The class itself and all interfaces marked contract will be in the list of advertised services. The scope and qualifiers will be taken from the annotations on the class.

Parameters

rawClass:Class<T>: The class to analyze, must not be null

Returns:ActiveDescriptor<T>

The active (reified) descriptor that has been added to the system, with all fields filled in based on the rawClass

Exceptions

MultiException:: If this class cannot be a service
IllegalArgumentException:: if rawClass is null

addActiveFactoryDescriptor back to summary

addActiveFactoryDescriptor	back to summary
public <T> FactoryDescriptors addActiveFactoryDescriptor(Class<? extends Factory<T>> rawFactoryClass) throws MultiException, IllegalArgumentException This adds two active descriptors to the system based completely on the analysis of the given `Factory` class. The `Factory` class itself and all interfaces marked contract will be in the list of advertised services. The scope and qualifiers will be taken from the annotations on the class. The annotations on the `Factory#provide` method will provide the scope and qualifiers of the service produced by the `Factory` Parameters rawFactoryClass:Class<? extends Factory<T>> The class to analyze, must not be null Returns:FactoryDescriptors The factory descriptors that have been added to the system, with all fields filled in based on the rawFactoryClass Exceptions MultiException: If this class cannot be a service IllegalArgumentException: if rawClass is null

public <T> FactoryDescriptors addActiveFactoryDescriptor(Class<? extends Factory<T>> rawFactoryClass) throws MultiException, IllegalArgumentException

This adds two active descriptors to the system based completely on the analysis of the given Factory class. The Factory class itself and all interfaces marked contract will be in the list of advertised services. The scope and qualifiers will be taken from the annotations on the class. The annotations on the Factory#provide method will provide the scope and qualifiers of the service produced by the Factory

Parameters

rawFactoryClass:Class<? extends Factory<T>>: The class to analyze, must not be null

Returns:FactoryDescriptors

The factory descriptors that have been added to the system, with all fields filled in based on the rawFactoryClass

Exceptions

MultiException:: If this class cannot be a service
IllegalArgumentException:: if rawClass is null

addIdempotentFilter back to summary

addIdempotentFilter	back to summary
public void addIdempotentFilter(Filter... idempotentFilter) throws IllegalArgumentException At commit time all idempotent filters in this dynamic configuration will be run against all validation-visible descriptors. If any of the idempotent filters are a match then the commit will FAIL and none of the descriptors in this DynamicConfiguration will be added or removed. The idempotent filters will be run under the same lock as the commit, and hence can guarantee true idempotency of the transaction. The normal use case for the use of this filter is to ensure that a service is only added once to the `ServiceLocator`, even when multiple threads may be attempting to add the same service The filter passed in should not do any change to the set of descriptors itself, any attempt to do so will leave the system in an inconsistent state. `IndexedFilter` is supported and is the normal use of an idempotent filter, though it is not required Parameters idempotentFilter:Filter[] A non-null idempotent filter to use during commit. If any descriptors match the filter, the commit will fail Exceptions IllegalArgumentException: If any of the filters are null

public void addIdempotentFilter(Filter... idempotentFilter) throws IllegalArgumentException

At commit time all idempotent filters in this dynamic configuration will be run against all validation-visible descriptors. If any of the idempotent filters are a match then the commit will FAIL and none of the descriptors in this DynamicConfiguration will be added or removed. The idempotent filters will be run under the same lock as the commit, and hence can guarantee true idempotency of the transaction.

The normal use case for the use of this filter is to ensure that a service is only added once to the ServiceLocator, even when multiple threads may be attempting to add the same service

The filter passed in should not do any change to the set of descriptors itself, any attempt to do so will leave the system in an inconsistent state. IndexedFilter is supported and is the normal use of an idempotent filter, though it is not required

Parameters

idempotentFilter:Filter[]: A non-null idempotent filter to use during commit. If any descriptors match the filter, the commit will fail

Exceptions

IllegalArgumentException:: If any of the filters are null

addUnbindFilter back to summary

addUnbindFilter	back to summary
public void addUnbindFilter(Filter unbindFilter) throws IllegalArgumentException This filter will added to the list of filters in this Configuration that will determine which Descriptors will be removed from the system. Only services directly from this Configuration objects' associated ServiceLocator will be given to this Filter (it will not be given descriptors from the ServiceLocators parent). The descriptors passed into this filter may be cast to `ActiveDescriptor`. The descriptors passed into this filter may or may not have been reified. This filter should not reify passed in descriptors. And descriptor for which this filter returns true will be removed from the `ServiceLocator` prior to any additions that are performed with this Configuration object. Hence a Configuration can remove and add a descriptor of the same type in one commit. In order to unbind a filter the caller of commit must pass the LOOKUP validators and the UNBIND validators. Parameters unbindFilter:Filter This filter will be added to the list of filters that this configuration object will use to determine which descriptors to unbind from the system. May not be null Exceptions IllegalArgumentException: if unbindFilter is null

public void addUnbindFilter(Filter unbindFilter) throws IllegalArgumentException

This filter will added to the list of filters in this Configuration that will determine which Descriptors will be removed from the system. Only services directly from this Configuration objects' associated ServiceLocator will be given to this Filter (it will not be given descriptors from the ServiceLocators parent). The descriptors passed into this filter may be cast to ActiveDescriptor. The descriptors passed into this filter may or may not have been reified. This filter should not reify passed in descriptors.

And descriptor for which this filter returns true will be removed from the ServiceLocator prior to any additions that are performed with this Configuration object. Hence a Configuration can remove and add a descriptor of the same type in one commit.

In order to unbind a filter the caller of commit must pass the LOOKUP validators and the UNBIND validators.

Parameters

unbindFilter:Filter: This filter will be added to the list of filters that this configuration object will use to determine which descriptors to unbind from the system. May not be null

Exceptions

IllegalArgumentException:: if unbindFilter is null

bind	back to summary
public <T> ActiveDescriptor<T> bind(Descriptor key) This method will bind the given descriptor to this Module. If the descriptor given is not an ActiveDescriptor then a non-reified ActiveDescriptor will be returned with the system provided fields set. If the descriptor given is a reified ActiveDescriptor then the descriptor returned will be a reified ActiveDescriptor that takes all values except for the id from the given descriptor. A deep copy will be made of the incoming descriptor Parameters key:Descriptor May not be null. Will be used to derive the various key fields associated with the given provider Returns:ActiveDescriptor<T> The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate Exceptions IllegalArgumentException: if there is an error in the key

bind

back to summary

public <T> ActiveDescriptor<T> bind(Descriptor key)

This method will bind the given descriptor to this Module. If the descriptor given is not an ActiveDescriptor then a non-reified ActiveDescriptor will be returned with the system provided fields set. If the descriptor given is a reified ActiveDescriptor then the descriptor returned will be a reified ActiveDescriptor that takes all values except for the id from the given descriptor. A deep copy will be made of the incoming descriptor

Parameters

key:Descriptor: May not be null. Will be used to derive the various key fields associated with the given provider

Returns:ActiveDescriptor<T>

The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate

Exceptions

IllegalArgumentException:: if there is an error in the key

bind	back to summary
public <T> ActiveDescriptor<T> bind(Descriptor key, boolean requiresDeepCopy) This method will bind the given descriptor to this Module. If the descriptor given is not an ActiveDescriptor then a non-reified ActiveDescriptor will be returned with the system provided fields set. If the descriptor given is a reified ActiveDescriptor then the descriptor returned will be a reified ActiveDescriptor that takes all values except for the id from the given descriptor. Parameters key:Descriptor May not be null. Will be used to derive the various key fields associated with the given provider requiresDeepCopy:boolean If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking) Returns:ActiveDescriptor<T> The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate Exceptions IllegalArgumentException: if there is an error in the key

bind

back to summary

public <T> ActiveDescriptor<T> bind(Descriptor key, boolean requiresDeepCopy)

Parameters

key:Descriptor: May not be null. Will be used to derive the various key fields associated with the given provider
requiresDeepCopy:boolean: If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking)

Returns:ActiveDescriptor<T>

The entry as added to the service registry, with fields of the Descriptor filled in by the system as appropriate

Exceptions

IllegalArgumentException:: if there is an error in the key

bind back to summary

bind	back to summary
public FactoryDescriptors bind(FactoryDescriptors factoryDescriptors) This method will bind the descriptors found in the `FactoryDescriptors`. This method will first validate the descriptors from the `FactoryDescriptors` and then simply bind them into this configuration as two independent descriptors. A deep copy will be made of both descriptors Parameters factoryDescriptors:FactoryDescriptors A description of a factory service and the type the factory service provides. May not be null Returns:FactoryDescriptors The descriptors returned from this object may be cast to ActiveDescriptor and will contain all the fields of the descriptors filled in by the system Exceptions IllegalArgumentException: if there is an error in the input parameter

public FactoryDescriptors bind(FactoryDescriptors factoryDescriptors)

This method will bind the descriptors found in the FactoryDescriptors. This method will first validate the descriptors from the FactoryDescriptors and then simply bind them into this configuration as two independent descriptors. A deep copy will be made of both descriptors

Parameters

factoryDescriptors:FactoryDescriptors: A description of a factory service and the type the factory service provides. May not be null

Returns:FactoryDescriptors

The descriptors returned from this object may be cast to ActiveDescriptor and will contain all the fields of the descriptors filled in by the system

Exceptions

IllegalArgumentException:: if there is an error in the input parameter

bind back to summary

bind	back to summary
public FactoryDescriptors bind(FactoryDescriptors factoryDescriptors, boolean requiresDeepCopy) This method will bind the descriptors found in the `FactoryDescriptors`. This method will first validate the descriptors from the `FactoryDescriptors` and then simply bind them into this configuration as two independent descriptors. A deep copy will be made of both descriptors Parameters factoryDescriptors:FactoryDescriptors A description of a factory service and the type the factory service provides. May not be null requiresDeepCopy:boolean If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking) Returns:FactoryDescriptors The descriptors returned from this object may be cast to ActiveDescriptor and will contain all the fields of the descriptors filled in by the system Exceptions IllegalArgumentException: if there is an error in the input parameter

public FactoryDescriptors bind(FactoryDescriptors factoryDescriptors, boolean requiresDeepCopy)

Parameters

factoryDescriptors:FactoryDescriptors: A description of a factory service and the type the factory service provides. May not be null
requiresDeepCopy:boolean: If true a deep copy will be made of the key. If false then the Descriptor will be used as is, and it is the responsibility of the caller to ensure that the fields of the Descriptor never change (with the exception of any writeable fields, such as ranking)

Returns:FactoryDescriptors

The descriptors returned from this object may be cast to ActiveDescriptor and will contain all the fields of the descriptors filled in by the system

Exceptions

IllegalArgumentException:: if there is an error in the input parameter

commit	back to summary
public void commit() throws MultiException This causes the configuration to get committed. This method may only be called once Exceptions MultiException: If errors were found in the commit process IllegalStateException: if this method was called more than once

commit

back to summary

public void commit() throws MultiException

This causes the configuration to get committed. This method may only be called once

Exceptions

MultiException:: If errors were found in the commit process
IllegalStateException:: if this method was called more than once

registerTwoPhaseResources	back to summary
public void registerTwoPhaseResources(TwoPhaseResource... resources) Registers two-phase resources in the order in which they are to run. Subsequent calls to this method will add resources at the end of the existing list Parameters resources:TwoPhaseResource[] A list of resources to add to this dynamic configuration

registerTwoPhaseResources

back to summary

public void registerTwoPhaseResources(TwoPhaseResource... resources)

Registers two-phase resources in the order in which they are to run. Subsequent calls to this method will add resources at the end of the existing list

Parameters

resources:TwoPhaseResource[]: A list of resources to add to this dynamic configuration

public Interface DynamicConfiguration

Method Summary

Method Detail