CustomAttribute (FreeMarker 2.3.35 API)
Description: declaration: package: freemarker.core, class: CustomAttribute

Package 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
  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
  Description
  `CustomAttribute​(int scope)`
  Creates a new custom attribute with the specified scope

- ## Method Summary

  Modifier and Type
  Method
  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​(Environment env)`
  Gets the attribute from the appropriate scope that's accessible through the specified `Environment`.
  `Object`
  `get​(TemplateConfiguration templateConfiguration)`
  Same as `get(Template)`, but applies to a `TemplateConfiguration`.
  `Object`
  `get​(Configuration cfg)`
  Gets the value of a `Configuration`-scope attribute from the given `Configuration`.
  `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, Environment env)`
  Sets the attribute inside the appropriate scope that's accessible through the specified `Environment`.
  `void`
  `set​(Object value, TemplateConfiguration templateConfiguration)`
  Same as `set(Object, Template)`, but applicable to a `TemplateConfiguration`.
  `void`
  `set​(Object value, Configuration cfg)`
  Sets the value of a `Configuration`-scope attribute in the given `Configuration`.
  `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 Details

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

  - ### CustomAttribute

    public CustomAttribute​(int scope)
    Creates a new custom attribute with the specified scope
    Parameters:
      `scope` - one of `SCOPE_` constants.

- ## Method Details

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