ValuedEnum
Date: 2016-02-08

org.apache.avalon.framework

## Class ValuedEnum

- java.lang.Object
- - org.apache.avalon.framework.Enum
  - - org.apache.avalon.framework.ValuedEnum

-     public abstract class ValuedEnum
      extends Enum

  Basic enum class for type-safe enums with values. Valued enum items can be compared and ordered with the provided methods. Should be used as an abstract base. For example:

       import org.apache.avalon.framework.ValuedEnum;

       public final class JavaVersion
         extends ValuedEnum
       {
         //standard enums for version of JVM
         public static final JavaVersion  JAVA1_0  = new JavaVersion( "Java 1.0", 100 );
         public static final JavaVersion  JAVA1_1  = new JavaVersion( "Java 1.1", 110 );
         public static final JavaVersion  JAVA1_2  = new JavaVersion( "Java 1.2", 120 );
         public static final JavaVersion  JAVA1_3  = new JavaVersion( "Java 1.3", 130 );

         private JavaVersion( final String name, final int value )
         {
           super( name, value );
         }
       }

  The above class could then be used as follows:

       import org.apache.avalon.framework.context.Context;
       import org.apache.avalon.framework.context.Contextualizable;
       import org.apache.avalon.framework.context.ContextException;

       public class MyComponent implements Contextualizable
       {
         JavaVersion requiredVer = JavaVersion.JAVA1_2;

         public void contextualize(Context context)
             throws ContextException
         {
           JavaVersion ver = (JavaVersion)context.get("java.version");
           if ( ver.isLessThan( requiredVer ) )
           {
             throw new RuntimeException( requiredVer.getName()+" or higher required" );
           }
         }
       }

  As with `Enum`, the `ValuedEnum(String, int, Map)` constructor can be used to populate a `Map`, from which further functionality can be derived.

  NOTE: between 4.0 and 4.1, the constructors' access has been changed from `public` to `protected`. This is to prevent users of the Enum breaking type-safety by defining new Enum items. All Enum items should be defined in the Enum class, as shown above.

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ValuedEnum(java.lang.String name, int value)` Constructor for enum item.
    `protected` | `ValuedEnum(java.lang.String name, int value, java.util.Map map)` Constructor for enum item so that it gets added to Map at creation.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getValue()` Get value of enum item.
    `boolean` | `isEqualTo(ValuedEnum other)` Test if enum item is equal in value to other enum.
    `boolean` | `isGreaterThan(ValuedEnum other)` Test if enum item is greater than in value to other enum.
    `boolean` | `isGreaterThanOrEqual(ValuedEnum other)` Test if enum item is greater than or equal in value to other enum.
    `boolean` | `isLessThan(ValuedEnum other)` Test if enum item is less than in value to other enum.
    `boolean` | `isLessThanOrEqual(ValuedEnum other)` Test if enum item is less than or equal in value to other enum.
    `java.lang.String` | `toString()` Override toString method to produce human readable description.

    - ### Methods inherited from class org.apache.avalon.framework.Enum

      `equals, getName, hashCode`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ValuedEnum

          protected ValuedEnum(java.lang.String name,
                    int value)

      Constructor for enum item.

      Note: access changed from `public` to `protected` after 4.0. See class description.

      Parameters:
        `name` - the name of enum item.
        `value` - the value of enum item.

    - #### ValuedEnum

          protected ValuedEnum(java.lang.String name,
                    int value,
                    java.util.Map map)

      Constructor for enum item so that it gets added to Map at creation. Adding to a map is useful for implementing find...() style methods. Note: access changed from `public` to `protected` after 4.0. See class description.
      Parameters:
        `name` - the name of enum item.
        `value` - the value of enum item.
        `map` - the `Map` to add enum item to.

  - ### Method Detail

    - #### getValue

          public final int getValue()

      Get value of enum item.
      Returns:
        the enum item's value.

    - #### isEqualTo

          public final boolean isEqualTo(ValuedEnum other)

      Test if enum item is equal in value to other enum.
      Parameters:
        `other` - the other enum
      Returns:
        true if equal

    - #### isGreaterThan

          public final boolean isGreaterThan(ValuedEnum other)

      Test if enum item is greater than in value to other enum.
      Parameters:
        `other` - the other enum
      Returns:
        true if greater than

    - #### isGreaterThanOrEqual

          public final boolean isGreaterThanOrEqual(ValuedEnum other)

      Test if enum item is greater than or equal in value to other enum.
      Parameters:
        `other` - the other enum
      Returns:
        true if greater than or equal

    - #### isLessThan

          public final boolean isLessThan(ValuedEnum other)

      Test if enum item is less than in value to other enum.
      Parameters:
        `other` - the other enum
      Returns:
        true if less than

    - #### isLessThanOrEqual

          public final boolean isLessThanOrEqual(ValuedEnum other)

      Test if enum item is less than or equal in value to other enum.
      Parameters:
        `other` - the other enum
      Returns:
        true if less than or equal

    - #### toString

          public java.lang.String toString()

      Override toString method to produce human readable description.
      Overrides:
        `toString` in class `Enum`
      Returns:
        String in the form `type[name=value]`, eg.: `JavaVersion[Java 1.0=100]`.