Top Description Fields Constructors Methods
org.glassfish.hk2.utilities

public Class BuilderHelper

extends Object
Class Inheritance
Imports
java.lang.annotation.Annotation, java.lang.reflect.Array, .Method, .Type, java.security.AccessController, .PrivilegedAction, java.util.Collections, .HashMap, .HashSet, .LinkedHashSet, .List, .Map, .Set, .StringTokenizer, java.util.concurrent.locks.ReentrantLock, org.glassfish.hk2.api.ActiveDescriptor, .Descriptor, .DescriptorType, .DescriptorVisibility, .Factory, .Filter, .IndexedFilter, .Metadata, .MultiException, .PerLookup, .ProxyForSameScope, .Rank, .ServiceHandle, .UseProxy, .Visibility, org.glassfish.hk2.internal.ActiveDescriptorBuilderImpl, .ConstantActiveDescriptor, .DescriptorBuilderImpl, .IndexedFilterImpl, .SpecificFilterImpl, .StarFilter, org.glassfish.hk2.utilities.reflection.ReflectionHelper, org.jvnet.hk2.annotations.Contract, .ContractsProvided, .Service

This class is used to generate DescriptorBuilders to be used as a simple mechanism to create a Filter or Descriptor.

Field Summary

Modifier and TypeField and Description
public static final String
NAME_KEY

The key for the name field of the tokenized string

public static final String
QUALIFIER_KEY

The key for the qualifier field of the tokenized string

public static final String
TOKEN_SEPARATOR

The token separator

Constructor Summary

AccessConstructor and Description
public

Method Summary

Modifier and TypeMethod and Description
public static Filter

Returns:

A filter that matches all descriptors
allFilter
()

Returns a filter of type Descriptor that matches all descriptors

public static <T> AbstractActiveDescriptor<T>

Returns:

The descriptor returned can be used in calls to DynamicConfiguration.addActiveDescriptor
createConstantDescriptor
(T
The non-null constant that should always be returned from the create method of this ActiveDescriptor.
constant
)

This creates a descriptor that will always return the given object.

public static <T> AbstractActiveDescriptor<T>

Returns:

The descriptor returned can be used in calls to DynamicConfiguration.addActiveDescriptor
createConstantDescriptor
(T
The non-null constant that should always be returned from the create method of this ActiveDescriptor.
constant
,
String
The possibly null name that should be associated with this constant descriptor
name
,
Type...
The possibly empty set of contracts that should be associated with this descriptor
contracts
)

This creates a descriptor that will always return the given object.

public static <T> ServiceHandle<T>

Returns:

A ServiceHandle that will always return the given value
createConstantServiceHandle
(final T
The object to be associated with this ServiceHandle. May be null
obj
)

Creates a ServiceHandle that will always return the given object from the ServiceHandle#getService() method.

public static IndexedFilter

Returns:

The indexed filter that can be used to calls to ServiceLocator methods
createContractFilter
(String
The advertised contract to look for
contract
)

Returns an indexed filter that will return all descriptors that have contract as an advertised contract

public static IndexedFilter

Returns:

An IndexedFilter that can be used to determine equality with the given filter based on the fields of the Descriptor
createDescriptorFilter
(Descriptor
A non-null Descriptor to compare against other Descriptors
descriptorImpl
,
boolean
If true then a copy will be made of the descriptorImpl to protect the filter from the case where the incoming descriptorImpl may change. If false then the user must ensure that the fields of the descriptorImpl cannot change after the filter is returned.
deepCopy
)

Returns a filter that will return true an IndexedFilter that will match the DescriptorImpl#equals(Object) return

public static IndexedFilter

Returns:

An IndexedFilter that can be used to determine equality with the given filter based on the fields of the Descriptor
createDescriptorFilter
(Descriptor
A non-null Descriptor to compare against other Descriptors
descriptorImpl
)

Returns a filter that will return true an IndexedFilter that will match the DescriptorImpl#equals(Object) return

public static DescriptorImpl

Returns:

The DescriptorImpl corresponding to this class
createDescriptorFromClass
(Class<?>
The class to analyze
clazz
)

This returns a DescriptorImpl based on the given class.

public static IndexedFilter

Returns:

The indexed filter that can be used to calls to ServiceLocator methods
createNameAndContractFilter
(String
The advertised contract to look for
contract
,
String
The name to look for
name
)

Returns an indexed filter that will return all descriptors that have the given name and given contract

public static IndexedFilter

Returns:

The indexed filter that can be used to calls to ServiceLocator methods
createNameFilter
(String
The name to look for
name
)

Returns an indexed filter that will return all descriptors that have the given name

public static IndexedFilter

Returns:

A filter to use that will match this descriptor exactly
createSpecificDescriptorFilter
(Descriptor
The descriptor from which to create a filter
descriptor
)

This method creates a filter that will match one and only one descriptor.

public static IndexedFilter

Returns:

A filter that will match the given string
createTokenizedFilter
(String
A non-null string following the rules stated above
tokenString
)

Creates a filter from a token string as per the following rules.

public static DescriptorImpl

Returns:

A new descriptor with all fields copied
deepCopyDescriptor
(Descriptor
The descriptor to copy
copyMe
)

Makes a deep copy of the incoming descriptor

public static boolean

Returns:

true if baseDescriptor matches, false otherwise
filterMatches
(final Descriptor
The non-null descriptor to match the filter against
baseDescriptor
,
final Filter
The filter to match. If null will return true
filter
)

Determines if the given descriptor matches the given filter.

public static void
getMetadataValues(Annotation
The annotation to find Metadata values from. May not be null.
annotation
,
Map<String, List<String>>
A non-null metadata map. The values found in the annotation will be added to this metadata map
metadata
)

This is a helper method that gets the metadata values from the Metadata annotations found in an annotation.

public static int

Returns:

The rank this class should initially have, or 0 if there is no Rank annotation on this class or all its superclasses
getRank
(Class<?>
The class to get the rank from. Will also check all superclasses
fromClass
)

Gets the rank from the given class

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

NAME_KEYback to summary
public static final String NAME_KEY

The key for the name field of the tokenized string

QUALIFIER_KEYback to summary
public static final String QUALIFIER_KEY

The key for the qualifier field of the tokenized string

TOKEN_SEPARATORback to summary
public static final String TOKEN_SEPARATOR

The token separator

Constructor Detail

BuilderHelperback to summary
public BuilderHelper()

Method Detail

allFilterback to summary
public static Filter allFilter()

Returns a filter of type Descriptor that matches all descriptors

Returns:Filter

A filter that matches all descriptors

createConstantDescriptorback to summary
public static <T> AbstractActiveDescriptor<T> createConstantDescriptor(T constant)

This creates a descriptor that will always return the given object. The set of types in the advertised contracts will contain the class of the constant along with:

  • Any superclass of the constant marked with Contract
  • Any interface of the constant marked with Contract
Parameters
constant:T

The non-null constant that should always be returned from the create method of this ActiveDescriptor.

Returns:AbstractActiveDescriptor<T>

The descriptor returned can be used in calls to DynamicConfiguration.addActiveDescriptor

Exceptions
IllegalArgumentException:
if constant is null
createConstantDescriptorback to summary
public static <T> AbstractActiveDescriptor<T> createConstantDescriptor(T constant, String name, Type... contracts)

This creates a descriptor that will always return the given object. The advertised contracts is given in the incoming parameter and the name on the descriptor also comes from the incoming parameter.

Parameters
constant:T

The non-null constant that should always be returned from the create method of this ActiveDescriptor.

name:String

The possibly null name that should be associated with this constant descriptor

contracts:Type[]

The possibly empty set of contracts that should be associated with this descriptor

Returns:AbstractActiveDescriptor<T>

The descriptor returned can be used in calls to DynamicConfiguration.addActiveDescriptor

Exceptions
IllegalArgumentException:
if constant is null
createConstantServiceHandleback to summary
public static <T> ServiceHandle<T> createConstantServiceHandle(final T obj)

Creates a ServiceHandle that will always return the given object from the ServiceHandle#getService() method. The ServiceHandle#getActiveDescriptor() will return null and the ServiceHandle#destroy() method will do nothing

Parameters
obj:T

The object to be associated with this ServiceHandle. May be null

Returns:ServiceHandle<T>

A ServiceHandle that will always return the given value

createContractFilterback to summary
public static IndexedFilter createContractFilter(String contract)

Returns an indexed filter that will return all descriptors that have contract as an advertised contract

Parameters
contract:String

The advertised contract to look for

Returns:IndexedFilter

The indexed filter that can be used to calls to ServiceLocator methods

createDescriptorFilterback to summary
public static IndexedFilter createDescriptorFilter(Descriptor descriptorImpl, boolean deepCopy)

Returns a filter that will return true an IndexedFilter that will match the DescriptorImpl#equals(Object) return

Parameters
descriptorImpl:Descriptor

A non-null Descriptor to compare against other Descriptors

deepCopy:boolean

If true then a copy will be made of the descriptorImpl to protect the filter from the case where the incoming descriptorImpl may change. If false then the user must ensure that the fields of the descriptorImpl cannot change after the filter is returned.

Returns:IndexedFilter

An IndexedFilter that can be used to determine equality with the given filter based on the fields of the Descriptor

createDescriptorFilterback to summary
public static IndexedFilter createDescriptorFilter(Descriptor descriptorImpl)

Returns a filter that will return true an IndexedFilter that will match the DescriptorImpl#equals(Object) return

Parameters
descriptorImpl:Descriptor

A non-null Descriptor to compare against other Descriptors

Returns:IndexedFilter

An IndexedFilter that can be used to determine equality with the given filter based on the fields of the Descriptor

createDescriptorFromClassback to summary
public static DescriptorImpl createDescriptorFromClass(Class<?> clazz)

This returns a DescriptorImpl based on the given class. The returned descriptor will include the class itself as an advertised contract and all implemented interfaces that are marked @Contract

Parameters
clazz:Class<?>

The class to analyze

Returns:DescriptorImpl

The DescriptorImpl corresponding to this class

createNameAndContractFilterback to summary
public static IndexedFilter createNameAndContractFilter(String contract, String name)

Returns an indexed filter that will return all descriptors that have the given name and given contract

Parameters
contract:String

The advertised contract to look for

name:String

The name to look for

Returns:IndexedFilter

The indexed filter that can be used to calls to ServiceLocator methods

createNameFilterback to summary
public static IndexedFilter createNameFilter(String name)

Returns an indexed filter that will return all descriptors that have the given name

Parameters
name:String

The name to look for

Returns:IndexedFilter

The indexed filter that can be used to calls to ServiceLocator methods

createSpecificDescriptorFilterback to summary
public static IndexedFilter createSpecificDescriptorFilter(Descriptor descriptor)

This method creates a filter that will match one and only one descriptor. The passed in descriptor must have both its serviceID and locatorId filled in, or else this method will throw an IllegalArgumentException

Parameters
descriptor:Descriptor

The descriptor from which to create a filter

Returns:IndexedFilter

A filter to use that will match this descriptor exactly

createTokenizedFilterback to summary
public static IndexedFilter createTokenizedFilter(String tokenString) throws IllegalArgumentException

Creates a filter from a token string as per the following rules.

  1. The token delimiter is ;
  2. The first token is the contract. If the tokenString starts with ; there is no contract
  3. All other tokens are in key = value form (with = being the separator)
  4. A valid key that can appear only once is "name"
  5. A valid key that can appear any number of times is "qualifier"

The following are examples of valid token strings:

  • com.acme.product.RocketShoes
  • com.acme.product.Sneakers;name=Nike
  • com.acme.product.Sneakers;name=Nike;qualifier=com.acme.color.Red;qualifier=com.acme.style.HighTop
  • ;name=Narcissus
Parameters
tokenString:String

A non-null string following the rules stated above

Returns:IndexedFilter

A filter that will match the given string

Exceptions
IllegalArgumentException:
If the token string is invalid in some way
deepCopyDescriptorback to summary
public static DescriptorImpl deepCopyDescriptor(Descriptor copyMe)

Makes a deep copy of the incoming descriptor

Parameters
copyMe:Descriptor

The descriptor to copy

Returns:DescriptorImpl

A new descriptor with all fields copied

filterMatchesback to summary
public static boolean filterMatches(final Descriptor baseDescriptor, final Filter filter)

Determines if the given descriptor matches the given filter. A null filter matches every descriptor. Takes into account if the Filter implements IndexedFilter.

Parameters
baseDescriptor:Descriptor

The non-null descriptor to match the filter against

filter:Filter

The filter to match. If null will return true

Returns:boolean

true if baseDescriptor matches, false otherwise

getMetadataValuesback to summary
public static void getMetadataValues(Annotation annotation, Map<String, List<String>> metadata)

This is a helper method that gets the metadata values from the Metadata annotations found in an annotation.

Parameters
annotation:Annotation

The annotation to find Metadata values from. May not be null.

metadata:Map<String, List<String>>

A non-null metadata map. The values found in the annotation will be added to this metadata map

Exceptions
IllegalArgumentException:
if annotation or metadata is null
MultiException:
if there was an error invoking the methods of the annotation
getRankback to summary
public static int getRank(Class<?> fromClass)

Gets the rank from the given class

Parameters
fromClass:Class<?>

The class to get the rank from. Will also check all superclasses

Returns:int

The rank this class should initially have, or 0 if there is no Rank annotation on this class or all its superclasses