CustomAttribute (FreeMarker 2.3.23 API)
Date: 2015-07-05

freemarker.core

## Class CustomAttribute

- java.lang.Object
- - freemarker.core.CustomAttribute

-     public class CustomAttribute
      extends Object

  A class that allows one to associate custom data with a `Configuration`, a `Template`, or `Environment`.

  This API has similar approach to that of `ThreadLocal` (which allows one to associate custom data with a thread). With an example:

       // The object identity itself will serve as the attribute identifier; there's no attribute name String:
       public static final CustomAttribute MY_ATTR = new CustomAttribute(CustomAttribute.SCOPE_CONFIGURATION);
       ...
           // Set the attribute in this particular Configuration object:
           MY_ATTR.set(myAttrValue, cfg);
           ...
           // Read the attribute from this particular Configuration object:
           myAttrValue = MY_ATTR.get(cfg);

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `SCOPE_CONFIGURATION` Constant used in the constructor specifying that this attribute is `Configuration`-scoped.
    `static int` | `SCOPE_ENVIRONMENT` Constant used in the constructor specifying that this attribute is `Environment`-scoped.
    `static int` | `SCOPE_TEMPLATE` Constant used in the constructor specifying that this attribute is `Template`-scoped.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CustomAttribute(int scope)` Creates a new custom attribute with the specified scope

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Object` | `create()` This method is invoked when `get()` is invoked without `set(Object)` being invoked before it to define the value in the current scope.
    `Object` | `get()` Same as `get(Environment)`, but uses `Environment.getCurrentEnvironment()` to fill the 2nd argument.
    `Object` | `get(Configuration cfg)` Gets the value of a `Configuration`-scope attribute from the given `Configuration`.
    `Object` | `get(Environment env)` Gets the attribute from the appropriate scope that's accessible through the specified `Environment`.
    `Object` | `get(Template template)` Gets the value of a `Template`-scope attribute from the given `Template`.
    `void` | `set(Object value)` Same as `set(Object, Environment)`, but uses `Environment.getCurrentEnvironment()` to fill the 2nd argument.
    `void` | `set(Object value, Configuration cfg)` Sets the value of a `Configuration`-scope attribute in the given `Configuration`.
    `void` | `set(Object value, Environment env)` Sets the attribute inside the appropriate scope that's accessible through the specified `Environment`.
    `void` | `set(Object value, Template template)` Sets the value of a `Template`-scope attribute in the given `Template`.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SCOPE_ENVIRONMENT

          public static final int SCOPE_ENVIRONMENT

      Constant used in the constructor specifying that this attribute is `Environment`-scoped.
      See Also:
        Constant Field Values

    - #### SCOPE_TEMPLATE

          public static final int SCOPE_TEMPLATE

      Constant used in the constructor specifying that this attribute is `Template`-scoped.
      See Also:
        Constant Field Values

    - #### SCOPE_CONFIGURATION

          public static final int SCOPE_CONFIGURATION

      Constant used in the constructor specifying that this attribute is `Configuration`-scoped.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### CustomAttribute

          public CustomAttribute(int scope)

      Creates a new custom attribute with the specified scope
      Parameters:
        `scope` - one of `SCOPE_` constants.

  - ### Method Detail

    - #### create

          protected Object create()

      This method is invoked when `get()` is invoked without `set(Object)` being invoked before it to define the value in the current scope. Override it to create the attribute value on-demand.
      Returns:
        the initial value for the custom attribute. By default returns null.

    - #### get

          public final Object get(Environment env)

      Gets the attribute from the appropriate scope that's accessible through the specified `Environment`. If the attribute has `SCOPE_ENVIRONMENT` scope, it will be get from the given `Environment` directly. If the attribute has `SCOPE_TEMPLATE` scope, it will be get from the parent of the given `Environment` (that is, in `Configurable.getParent()`) directly). If the attribute has `SCOPE_CONFIGURATION` scope, it will be get from `Environment.getConfiguration()`.
      Returns:
        The new value of the attribute (possibly `null`), or `null` if the attribute doesn't exist.
      Throws:
        `NullPointerException` - If `env` is null
      Since:
        2.3.22

    - #### get

          public final Object get()

      Same as `get(Environment)`, but uses `Environment.getCurrentEnvironment()` to fill the 2nd argument.
      Throws:
        `IllegalStateException` - If there is no current `Environment`, which is usually the case when the current thread isn't processing a template.

    - #### get

          public final Object get(Template template)

      Gets the value of a `Template`-scope attribute from the given `Template`.
      Throws:
        `UnsupportedOperationException` - If this custom attribute has different scope than `SCOPE_TEMPLATE`.
        `NullPointerException` - If `template` is null

    - #### get

          public final Object get(Configuration cfg)

      Gets the value of a `Configuration`-scope attribute from the given `Configuration`.
      Throws:
        `UnsupportedOperationException` - If this custom attribute has different scope than `SCOPE_CONFIGURATION`.
        `NullPointerException` - If `cfg` is null
      Since:
        2.3.22

    - #### set

          public final void set(Object value,
                                Environment env)

      Sets the attribute inside the appropriate scope that's accessible through the specified `Environment`. If the attribute has `SCOPE_ENVIRONMENT` scope, it will be set in the given `Environment` directly. If the attribute has `SCOPE_TEMPLATE` scope, it will be set in the parent of the given `Environment` (that is, in `Configurable.getParent()`) directly). If the attribute has `SCOPE_CONFIGURATION` scope, it will be set in `Environment.getConfiguration()`.
      Parameters:
        `value` - The new value of the attribute. Can be `null`.
      Throws:
        `NullPointerException` - If `env` is null
      Since:
        2.3.22

    - #### set

          public final void set(Object value)

      Same as `set(Object, Environment)`, but uses `Environment.getCurrentEnvironment()` to fill the 2nd argument.
      Throws:
        `IllegalStateException` - If there is no current `Environment`, which is usually the case when the current thread isn't processing a template.

    - #### set

          public final void set(Object value,
                                Template template)

      Sets the value of a `Template`-scope attribute in the given `Template`.
      Parameters:
        `value` - The new value of the attribute. Can be `null`.
      Throws:
        `UnsupportedOperationException` - If this custom attribute has different scope than `SCOPE_TEMPLATE`.
        `NullPointerException` - If `template` is null

    - #### set

          public final void set(Object value,
                                Configuration cfg)

      Sets the value of a `Configuration`-scope attribute in the given `Configuration`.
      Parameters:
        `value` - The new value of the attribute. Can be `null`.
      Throws:
        `UnsupportedOperationException` - If this custom attribute has different scope than `SCOPE_CONFIGURATION`.
        `NullPointerException` - If `cfg` is null
      Since:
        2.3.22