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
`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
`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`.
`Object` `get(TemplateConfiguration templateConfiguration)` Same as `get(Template)`, but applies to a `TemplateConfiguration`.
`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`.
`void` `set(Object value, TemplateConfiguration templateConfiguration)` Same as `set(Object, Template)`, but applicable to a `TemplateConfiguration`.

### 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 Object get(TemplateConfiguration templateConfiguration)

Same as `get(Template)`, but applies to a `TemplateConfiguration`.

Since:
  2.3.24

#### 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,
                          TemplateConfiguration templateConfiguration)

Same as `set(Object, Template)`, but applicable to a `TemplateConfiguration`.

Since:
  2.3.24

#### 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