Class BuilderHelper


  • public class BuilderHelper
    extends java.lang.Object
    This class is used to generate DescriptorBuilders to be used as a simple mechanism to create a Filter or Descriptor.
    • Field Detail

      • NAME_KEY

        public static final java.lang.String NAME_KEY
        The key for the name field of the tokenized string
        See Also:
        Constant Field Values
      • QUALIFIER_KEY

        public static final java.lang.String QUALIFIER_KEY
        The key for the qualifier field of the tokenized string
        See Also:
        Constant Field Values
      • TOKEN_SEPARATOR

        public static final java.lang.String TOKEN_SEPARATOR
        The token separator
        See Also:
        Constant Field Values
    • Constructor Detail

      • BuilderHelper

        public BuilderHelper()
    • Method Detail

      • createContractFilter

        public static IndexedFilter createContractFilter​(java.lang.String contract)
        Returns an indexed filter that will return all descriptors that have contract as an advertised contract
        Parameters:
        contract - The advertised contract to look for
        Returns:
        The indexed filter that can be used to calls to ServiceLocator methods
      • createNameFilter

        public static IndexedFilter createNameFilter​(java.lang.String name)
        Returns an indexed filter that will return all descriptors that have the given name
        Parameters:
        name - The name to look for
        Returns:
        The indexed filter that can be used to calls to ServiceLocator methods
      • createNameAndContractFilter

        public static IndexedFilter createNameAndContractFilter​(java.lang.String contract,
                                                                java.lang.String name)
        Returns an indexed filter that will return all descriptors that have the given name and given contract
        Parameters:
        contract - The advertised contract to look for
        name - The name to look for
        Returns:
        The indexed filter that can be used to calls to ServiceLocator methods
      • createTokenizedFilter

        public static IndexedFilter createTokenizedFilter​(java.lang.String tokenString)
                                                   throws java.lang.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 - A non-null string following the rules stated above
        Returns:
        A filter that will match the given string
        Throws:
        java.lang.IllegalArgumentException - If the token string is invalid in some way
      • createSpecificDescriptorFilter

        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 - The descriptor from which to create a filter
        Returns:
        A filter to use that will match this descriptor exactly
      • createDescriptorFilter

        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 - A non-null Descriptor to compare against other Descriptors
        deepCopy - 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:
        An IndexedFilter that can be used to determine equality with the given filter based on the fields of the Descriptor
      • createDescriptorFilter

        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 - A non-null Descriptor to compare against other Descriptors
        Returns:
        An IndexedFilter that can be used to determine equality with the given filter based on the fields of the Descriptor
      • allFilter

        public static Filter allFilter()
        Returns a filter of type Descriptor that matches all descriptors
        Returns:
        A filter that matches all descriptors
      • link

        public static DescriptorBuilder link​(java.lang.String implementationClass,
                                             boolean addToContracts)
                                      throws java.lang.IllegalArgumentException
        This method links an implementation class with a DescriptorBuilder, to be used to further build the Descriptor.
        Parameters:
        implementationClass - The fully qualified name of the implementation class to be associated with the DescriptorBuilder.
        addToContracts - if true, this implementation class will be added to the list of contracts
        Returns:
        A DescriptorBuilder that can be used to further build up the Descriptor
        Throws:
        java.lang.IllegalArgumentException - if implementationClass is null
      • link

        public static DescriptorBuilder link​(java.lang.String implementationClass)
                                      throws java.lang.IllegalArgumentException
        This method links an implementation class with a DescriptorBuilder, to be used to further build the Descriptor. This method will automatically put the implementationClass into the list of advertised contracts.
        Parameters:
        implementationClass - The fully qualified name of the implementation class to be associated with the PredicateBuilder.
        Returns:
        A DescriptorBuilder that can be used to further build up the Descriptor
        Throws:
        java.lang.IllegalArgumentException - if implementationClass is null
      • link

        public static DescriptorBuilder link​(java.lang.Class<?> implementationClass,
                                             boolean addToContracts)
                                      throws java.lang.IllegalArgumentException
        This method links an implementation class with a DescriptorBuilder, to be used to further build the Descriptor
        Parameters:
        implementationClass - The implementation class to be associated with the DescriptorBuilder.
        addToContracts - true if this impl class should be automatically added to the list of contracts
        Returns:
        A DescriptorBuilder that can be used to further build up the Descriptor
        Throws:
        java.lang.IllegalArgumentException - if implementationClass is null
      • link

        public static DescriptorBuilder link​(java.lang.Class<?> implementationClass)
                                      throws java.lang.IllegalArgumentException
        This method links an implementation class with a DescriptorBuilder, to be used to further build the Descriptor.
        Parameters:
        implementationClass - The implementation class to be associated with the DescriptorBuilder.
        Returns:
        A DescriptorBuilder that can be used to further build up the Descriptor
        Throws:
        java.lang.IllegalArgumentException - if implementationClass is null
      • createConstantDescriptor

        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 - The non-null constant that should always be returned from the create method of this ActiveDescriptor.
        Returns:
        The descriptor returned can be used in calls to DynamicConfiguration.addActiveDescriptor
        Throws:
        java.lang.IllegalArgumentException - if constant is null
      • getRank

        public static int getRank​(java.lang.Class<?> fromClass)
        Gets the rank from the given class
        Parameters:
        fromClass - The class to get the rank from. Will also check all superclasses
        Returns:
        The rank this class should initially have, or 0 if there is no Rank annotation on this class or all its superclasses
      • createConstantDescriptor

        public static <T> AbstractActiveDescriptor<T> createConstantDescriptor​(T constant,
                                                                               java.lang.String name,
                                                                               java.lang.reflect.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 - The non-null constant that should always be returned from the create method of this ActiveDescriptor.
        name - The possibly null name that should be associated with this constant descriptor
        contracts - The possibly empty set of contracts that should be associated with this descriptor
        Returns:
        The descriptor returned can be used in calls to DynamicConfiguration.addActiveDescriptor
        Throws:
        java.lang.IllegalArgumentException - if constant is null
      • createDescriptorFromClass

        public static DescriptorImpl createDescriptorFromClass​(java.lang.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 - The class to analyze
        Returns:
        The DescriptorImpl corresponding to this class
      • deepCopyDescriptor

        public static DescriptorImpl deepCopyDescriptor​(Descriptor copyMe)
        Makes a deep copy of the incoming descriptor
        Parameters:
        copyMe - The descriptor to copy
        Returns:
        A new descriptor with all fields copied
      • getMetadataValues

        public static void getMetadataValues​(java.lang.annotation.Annotation annotation,
                                             java.util.Map<java.lang.String,​java.util.List<java.lang.String>> metadata)
        This is a helper method that gets the metadata values from the Metadata annotations found in an annotation.
        Parameters:
        annotation - The annotation to find Metadata values from. May not be null.
        metadata - A non-null metadata map. The values found in the annotation will be added to this metadata map
        Throws:
        java.lang.IllegalArgumentException - if annotation or metadata is null
        MultiException - if there was an error invoking the methods of the annotation
      • filterMatches

        public static boolean filterMatches​(Descriptor baseDescriptor,
                                            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 - The non-null descriptor to match the filter against
        filter - The filter to match. If null will return true
        Returns:
        true if baseDescriptor matches, false otherwise