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