Class ExtendedEnum<T extends Named>

  • Type Parameters:
    T - the type of the enum

    public final class ExtendedEnum<T extends Named>
    extends java.lang.Object
    Manager for extended enums controlled by code or configuration.

    The standard Java Enum is a fixed set of constants defined at compile time. In many scenarios this can be too limiting and this class provides an alternative.

    An INI configuration file is used to define the set of named instances. For more information on the process of loading the configuration file, see ResourceConfig.

    The named instances are loaded via provider classes. A provider class is either an implementation of NamedLookup or a class providing public static final enum constants.

    The configuration file also supports the notion of alternate names (aliases). This allows many different names to be used to lookup the same instance.

    Three sections control the loading of additional information.

    The 'providers' section contains a number of properties, one for each provider. The key is the full class name of the provider. The value is 'constants', 'lookup' or 'instance', and is used to obtain a NamedLookup instance. A 'constants' provider must contain public static constants of the correct type, which will be reflectively located and wrapped in a NamedLookup. A 'lookup' provider must implement NamedLookup and have a no-args constructor. An 'instance' provider must have a static variable named "INSTANCE" of type NamedLookup.

    The 'alternates' section contains a number of properties, one for each alternate name. The key is the alternate name, the value is the standard name. Alternate names are used when looking up an extended enum.

    The 'externals' sections contains a number of properties intended to allow external enum names to be mapped. Unlike 'alternates', which are always included, 'externals' are only included when requested. There may be multiple external groups to handle different external providers of data. For example, the mapping used by FpML may differ from that used by Bloomberg.

    Each 'externals' section has a name of the form 'externals.Foo', where 'Foo' is the name of the group. Each property line in the section is of the same format as the 'alternates' section. It maps the external name to the standard name.

    It is intended that this class is used as a helper class to load the configuration and manage the map of names to instances. It should be created and used by the author of the main abstract extended enum class, and not be application developers.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  ExtendedEnum.ExternalEnumNames<T extends Named>
      Maps names used by external systems to the standard name used here.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      com.google.common.collect.ImmutableMap<java.lang.String,​java.lang.String> alternateNames()
      Returns the complete map of alternate name to standard name.
      com.google.common.collect.ImmutableSet<java.lang.String> externalNameGroups()
      Returns the set of groups that have external names defined.
      ExtendedEnum.ExternalEnumNames<T> externalNames​(java.lang.String group)
      Returns the mapping of external names to standard names for a group.
      java.util.Optional<T> find​(java.lang.String name)
      Finds an instance by name.
      java.util.Optional<T> findLenient​(java.lang.String name)
      Looks up an instance by name leniently.
      java.lang.Class<T> getType()
      Gets the enum type.
      T lookup​(java.lang.String name)
      Looks up an instance by name.
      <S extends T>
      S
      lookup​(java.lang.String name, java.lang.Class<S> subtype)
      Looks up an instance by name and type.
      com.google.common.collect.ImmutableMap<java.lang.String,​T> lookupAll()
      Returns the map of known instances by name.
      com.google.common.collect.ImmutableMap<java.lang.String,​T> lookupAllNormalized()
      Returns the map of known instances by normalized name.
      static <R extends Named>
      ExtendedEnum<R>
      of​(java.lang.Class<R> type)
      Obtains an extended enum instance.
      java.lang.String toString()  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Method Detail

      • of

        public static <R extends NamedExtendedEnum<R> of​(java.lang.Class<R> type)
        Obtains an extended enum instance.

        Calling this method loads configuration files to determine the extended enum values. The configuration file has the same simple name as the specified type and is a INI file with the suffix '.ini'. See class-level documentation for more information.

        Type Parameters:
        R - the type of the enum
        Parameters:
        type - the type to load
        Returns:
        the extended enum
      • getType

        public java.lang.Class<T> getType()
        Gets the enum type.
        Returns:
        the enum type
      • find

        public java.util.Optional<T> find​(java.lang.String name)
        Finds an instance by name.

        This finds the instance matching the specified name. Instances may have alternate names (aliases), thus the returned instance may have a name other than that requested.

        Parameters:
        name - the enum name to return
        Returns:
        the named enum
      • lookup

        public T lookup​(java.lang.String name)
        Looks up an instance by name.

        This finds the instance matching the specified name. Instances may have alternate names (aliases), thus the returned instance may have a name other than that requested.

        Parameters:
        name - the enum name to return
        Returns:
        the named enum
        Throws:
        java.lang.IllegalArgumentException - if the name is not found
      • lookup

        public <S extends T> S lookup​(java.lang.String name,
                                      java.lang.Class<S> subtype)
        Looks up an instance by name and type.

        This finds the instance matching the specified name, ensuring it is of the specified type. Instances may have alternate names (aliases), thus the returned instance may have a name other than that requested.

        Type Parameters:
        S - the enum subtype
        Parameters:
        subtype - the enum subtype to match
        name - the enum name to return
        Returns:
        the named enum
        Throws:
        java.lang.IllegalArgumentException - if the name is not found or has the wrong type
      • lookupAll

        public com.google.common.collect.ImmutableMap<java.lang.String,​T> lookupAll()
        Returns the map of known instances by name.

        This method returns all known instances. It is permitted for an enum provider implementation to return an empty map, thus the map may not be complete. The map may include instances keyed under an alternate name, such as names in upper case, however it will not include the base set of alternate names.

        Returns:
        the map of enum instance by name
      • lookupAllNormalized

        public com.google.common.collect.ImmutableMap<java.lang.String,​T> lookupAllNormalized()
        Returns the map of known instances by normalized name.

        This method returns all known instances, keyed by the normalized name. This is equivalent to the result of lookupAll() adjusted such that each entry is keyed by the result of Named.getName().

        Returns:
        the map of enum instance by name
      • alternateNames

        public com.google.common.collect.ImmutableMap<java.lang.String,​java.lang.String> alternateNames()
        Returns the complete map of alternate name to standard name.

        The map is keyed by the alternate name.

        Returns:
        the map of alternate names
      • externalNameGroups

        public com.google.common.collect.ImmutableSet<java.lang.String> externalNameGroups()
        Returns the set of groups that have external names defined.

        External names are used to map names used by external systems to the standard name used here. There can be multiple groups of mappings to external systems, For example, the mapping used by FpML may differ from that used by Bloomberg.

        Returns:
        the set of groups that have external names
      • externalNames

        public ExtendedEnum.ExternalEnumNames<T> externalNames​(java.lang.String group)
        Returns the mapping of external names to standard names for a group.

        External names are used to map names used by external systems to the standard name used here. There can be multiple groups of mappings to external systems, For example, the mapping used by FpML may differ from that used by Bloomberg.

        The result provides mapping between the external name and the standard name.

        Parameters:
        group - the group name to find external names for
        Returns:
        the map of external names for the group
        Throws:
        java.lang.IllegalArgumentException - if the group is not found
      • findLenient

        public java.util.Optional<T> findLenient​(java.lang.String name)
        Looks up an instance by name leniently.

        This finds the instance matching the specified name using a lenient lookup strategy. An extended enum may include additional configuration defining how lenient search occurs.

        Parameters:
        name - the enum name to return
        Returns:
        the named enum
        Throws:
        java.lang.IllegalArgumentException - if the name is not found
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object