Package org.apache.any23.configuration

## Class Setting<V>

- java.lang.Object
- - org.apache.any23.configuration.Setting<V>

- All Implemented Interfaces:
    `Cloneable`

      public abstract class Setting<V>
      extends Object
      implements Cloneable

  Represents a setting key paired with a compatible value.
  Author:
    Hans Brende (hansbrende@apache.org)

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Setting​(String identifier, Class<V> valueType, V defaultValue)` | Constructs a new setting with the specified identifier, value type, and default value.
    `protected` | `Setting​(String identifier, V defaultValue)` | Constructs a new setting with the specified identifier and default value.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `<S extends Setting<?>> Optional<S>` | `as​(S setting)` |
    `protected void` | `checkValue​(V newValue)` | Subclasses may override this method to check that new values for this setting are valid.
    `protected Object` | `clone()` |
    `static Setting<Boolean>` | `create​(String identifier, Boolean defaultValue)` | Convenience method to create a new setting with the specified identifier and default value.
    `static <V> Setting<V>` | `create​(String identifier, Class<V> valueType, V defaultValue)` | Convenience method to create a new setting with the specified identifier, value type, and default value.
    `static Setting<Double>` | `create​(String identifier, Double defaultValue)` | Convenience method to create a new setting with the specified identifier and default value.
    `static Setting<Float>` | `create​(String identifier, Float defaultValue)` | Convenience method to create a new setting with the specified identifier and default value.
    `static Setting<Integer>` | `create​(String identifier, Integer defaultValue)` | Convenience method to create a new setting with the specified identifier and default value.
    `static Setting<Long>` | `create​(String identifier, Long defaultValue)` | Convenience method to create a new setting with the specified identifier and default value.
    `static Setting<String>` | `create​(String identifier, String defaultValue)` | Convenience method to create a new setting with the specified identifier and default value.
    `boolean` | `equals​(Object o)` |
    `String` | `getIdentifier()` |
    `V` | `getValue()` |
    `Type` | `getValueType()` |
    `int` | `hashCode()` |
    `String` | `toString()` |
    `Setting<V>` | `withValue​(V newValue)` |

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

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

- - ### Constructor Detail

    - #### Setting

          protected Setting​(String identifier,
                            V defaultValue)

      Constructs a new setting with the specified identifier and default value. This constructor must be called with concrete type arguments.
      Parameters:
        `identifier` - the identifier for this setting
        `defaultValue` - the default value for this setting
      Throws:
        `IllegalArgumentException` - if the identifier or any of the type arguments were invalid

    - #### Setting

          protected Setting​(String identifier,
                            Class<V> valueType,
                            V defaultValue)

      Constructs a new setting with the specified identifier, value type, and default value.
      Parameters:
        `identifier` - the identifier for this setting
        `valueType` - the value type for this setting
        `defaultValue` - the default value for this setting
      Throws:
        `IllegalArgumentException` - if the identifier is invalid, or the value type is primitive, mutable, or has type parameters

  - ### Method Detail

    - #### getIdentifier

          public final String getIdentifier()

      Returns:
        the identifier for this setting

    - #### checkValue

          protected void checkValue​(V newValue)
                             throws Exception

      Subclasses may override this method to check that new values for this setting are valid. The default implementation of this method throws a `NullPointerException` if the new value is null and the original default value for this setting was non-null.
      Parameters:
        `newValue` - the new value for this setting
      Throws:
        `Exception` - if the new value for this setting is invalid

    - #### getValue

          public final V getValue()

      Returns:
        the value for this setting

    - #### getValueType

          public final Type getValueType()

      Returns:
        the type of value supported for this setting

    - #### as

          public final <S extends Setting<?>> Optional<S> as​(S setting)

      Type Parameters:
        `S` - the type of the supplied setting
      Parameters:
        `setting` - a setting that may or may not have the same key as this setting
      Returns:
        this setting, if this setting has the same key as the supplied setting

    - #### withValue

          public final Setting<V> withValue​(V newValue)

      Parameters:
        `newValue` - a value for a new setting
      Returns:
        a new `Setting` object with this setting's key and the supplied value.
      Throws:
        `IllegalArgumentException` - if the new value was invalid, as determined by:

                 this.checkValue(newValue)

      See Also:
        `checkValue(Object)`

    - #### clone

          protected final Object clone()

      Overrides:
        `clone` in class `Object`

    - #### equals

          public final boolean equals​(Object o)

      Overrides:
        `equals` in class `Object`
      Returns:
        true if the supplied object is an instance of `Setting` and has the same key and value as this setting.

    - #### hashCode

          public final int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### create

          public static Setting<Boolean> create​(String identifier,
                                                Boolean defaultValue)

      Convenience method to create a new setting with the specified identifier and default value.
      Parameters:
        `identifier` - the identifier for this setting
        `defaultValue` - the default value for this setting
      Returns:
        the new setting
      Throws:
        `IllegalArgumentException` - if the identifier is invalid

    - #### create

          public static Setting<String> create​(String identifier,
                                               String defaultValue)

      Convenience method to create a new setting with the specified identifier and default value.
      Parameters:
        `identifier` - the identifier for this setting
        `defaultValue` - the default value for this setting
      Returns:
        the new setting
      Throws:
        `IllegalArgumentException` - if the identifier is invalid

    - #### create

          public static Setting<Integer> create​(String identifier,
                                                Integer defaultValue)

      Convenience method to create a new setting with the specified identifier and default value.
      Parameters:
        `identifier` - the identifier for this setting
        `defaultValue` - the default value for this setting
      Returns:
        the new setting
      Throws:
        `IllegalArgumentException` - if the identifier is invalid

    - #### create

          public static Setting<Long> create​(String identifier,
                                             Long defaultValue)

      Convenience method to create a new setting with the specified identifier and default value.
      Parameters:
        `identifier` - the identifier for this setting
        `defaultValue` - the default value for this setting
      Returns:
        the new setting
      Throws:
        `IllegalArgumentException` - if the identifier is invalid

    - #### create

          public static Setting<Float> create​(String identifier,
                                              Float defaultValue)

      Convenience method to create a new setting with the specified identifier and default value.
      Parameters:
        `identifier` - the identifier for this setting
        `defaultValue` - the default value for this setting
      Returns:
        the new setting
      Throws:
        `IllegalArgumentException` - if the identifier is invalid

    - #### create

          public static Setting<Double> create​(String identifier,
                                               Double defaultValue)

      Convenience method to create a new setting with the specified identifier and default value.
      Parameters:
        `identifier` - the identifier for this setting
        `defaultValue` - the default value for this setting
      Returns:
        the new setting
      Throws:
        `IllegalArgumentException` - if the identifier is invalid

    - #### create

          public static <V> Setting<V> create​(String identifier,
                                              Class<V> valueType,
                                              V defaultValue)

      Convenience method to create a new setting with the specified identifier, value type, and default value.
      Type Parameters:
        `V` - generic setting value type
      Parameters:
        `identifier` - the identifier for this setting
        `valueType` - the value type for this setting
        `defaultValue` - the default value for this setting
      Returns:
        the new setting
      Throws:
        `IllegalArgumentException` - if the identifier is invalid, or the value type is primitive, mutable, or has type parameters