freemarker.core

Class CustomAttribute

java.lang.Object

freemarker.core.CustomAttribute

public class CustomAttribute
extends java.lang.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

Modifier and Type	Method and Description
protected java.lang.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.
java.lang.Object	get() Same as get(Environment), but uses Environment.getCurrentEnvironment() to fill the 2nd argument.
java.lang.Object	get(Configuration cfg) Gets the value of a Configuration-scope attribute from the given Configuration.
java.lang.Object	get(Environment env) Gets the attribute from the appropriate scope that's accessible through the specified Environment.
java.lang.Object	get(Template template) Gets the value of a Template-scope attribute from the given Template.
java.lang.Object	get(TemplateConfiguration templateConfiguration) Same as get(Template), but applies to a TemplateConfiguration.
void	set(java.lang.Object value) Same as set(Object, Environment), but uses Environment.getCurrentEnvironment() to fill the 2nd argument.
void	set(java.lang.Object value, Configuration cfg) Sets the value of a Configuration-scope attribute in the given Configuration.
void	set(java.lang.Object value, Environment env) Sets the attribute inside the appropriate scope that's accessible through the specified Environment.
void	set(java.lang.Object value, Template template) Sets the value of a Template-scope attribute in the given Template.
void	set(java.lang.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 java.lang.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 java.lang.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:

java.lang.NullPointerException - If env is null

Since:

2.3.22

get

public final java.lang.Object get()

Same as get(Environment), but uses Environment.getCurrentEnvironment() to fill the 2nd argument.

Throws:

java.lang.IllegalStateException - If there is no current Environment, which is usually the case when the current thread isn't processing a template.

get

public final java.lang.Object get(Template template)

Gets the value of a Template-scope attribute from the given Template.

Throws:

java.lang.UnsupportedOperationException - If this custom attribute has different scope than SCOPE_TEMPLATE.

java.lang.NullPointerException - If template is null

get

public java.lang.Object get(TemplateConfiguration templateConfiguration)

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

Since:

2.3.24

get

public final java.lang.Object get(Configuration cfg)

Gets the value of a Configuration-scope attribute from the given Configuration.

Throws:

java.lang.UnsupportedOperationException - If this custom attribute has different scope than SCOPE_CONFIGURATION.

java.lang.NullPointerException - If cfg is null

Since:

2.3.22

set

public final void set(java.lang.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:

java.lang.NullPointerException - If env is null

Since:

2.3.22

set

public final void set(java.lang.Object value)

Same as set(Object, Environment), but uses Environment.getCurrentEnvironment() to fill the 2nd argument.

Throws:

java.lang.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(java.lang.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:

java.lang.UnsupportedOperationException - If this custom attribute has different scope than SCOPE_TEMPLATE.

java.lang.NullPointerException - If template is null

set

public final void set(java.lang.Object value,
                      TemplateConfiguration templateConfiguration)

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

Since:

2.3.24

set

public final void set(java.lang.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:

java.lang.UnsupportedOperationException - If this custom attribute has different scope than SCOPE_CONFIGURATION.

java.lang.NullPointerException - If cfg is null

Since:

2.3.22