freemarker.template

Class SimpleHash

java.lang.Object

freemarker.template.WrappingTemplateModel

freemarker.template.SimpleHash

All Implemented Interfaces:

TemplateHashModel, TemplateHashModelEx, TemplateHashModelEx2, TemplateModel, java.io.Serializable

Direct Known Subclasses:

AllHttpScopesHashModel, Environment.Namespace

public class SimpleHash
extends WrappingTemplateModel
implements TemplateHashModelEx2, java.io.Serializable

A simple implementation of the TemplateHashModelEx interface, using its own underlying Map or SortedMap for storing the hash entries. If you are wrapping an already existing Map, you should certainly use DefaultMapAdapter instead (see comparison below).

This class is thread-safe if you don't call modifying methods (like put(String, Object), remove(String), etc.) after you have made the object available for multiple threads (assuming you have published it safely to the other threads; see JSR-133 Java Memory Model). These methods aren't called by FreeMarker, so it's usually not a concern.

SimpleHash VS DefaultMapAdapter - Which to use when?

For a Map that exists regardless of FreeMarker, only you need to access it from templates, DefaultMapAdapter should be the default choice, as it reflects the exact behavior of the underlying Map (no surprises), can be unwrapped to the originally wrapped object (important when passing it to Java methods from the template), and has more predictable performance (no spikes).

For a hash that's made specifically to be used from templates, creating an empty SimpleHash then filling it with put(String, Object) is usually the way to go, as the resulting hash is significantly faster to read from templates than a DefaultMapAdapter (though it's somewhat slower to read from a plain Java method to which it had to be passed adapted to a Map).

It also matters if for how many times will the same Map entry be read from the template(s) later, on average. If, on average, you read each entry for more than 4 times, SimpleHash will be most certainly faster, but if for 2 times or less (and especially if not at all) then DefaultMapAdapter will be faster. Before choosing based on performance though, pay attention to the behavioral differences; SimpleHash will shallow-copy the original Map at construction time, so key order will be lost in some cases, and it won't reflect Map content changes after the SimpleHash construction, also SimpleHash can't be unwrapped to the original Map instance.

See Also:

DefaultMapAdapter, TemplateHashModelEx, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface freemarker.template.TemplateHashModelEx2

TemplateHashModelEx2.KeyValuePair, TemplateHashModelEx2.KeyValuePairIterator

Field Summary

Fields inherited from interface freemarker.template.TemplateModel

NOTHING

Constructor Summary

Constructors

Constructor and Description
SimpleHash() Deprecated. Use SimpleHash(ObjectWrapper)
SimpleHash(java.util.Map map) Deprecated. Use SimpleHash(Map, ObjectWrapper)
SimpleHash(java.util.Map<java.lang.String,java.lang.Object> directMap, ObjectWrapper wrapper, int overloadDistinction) Creates an instance that will use the specified Map directly as its backing store; beware, the Map will be possibly modified by SimpleHash, even if you only read the SimpleHash.
SimpleHash(java.util.Map map, ObjectWrapper wrapper) Creates a new hash by shallow-coping (possibly cloning) the underlying map; in many applications you should use DefaultMapAdapter instead.
SimpleHash(ObjectWrapper wrapper) Creates an empty simple hash using the specified object wrapper.

Method Summary

Modifier and Type	Method and Description
boolean	containsKey(java.lang.String key) Tells if the map contains a key or not, regardless if the associated value is null or not.
protected java.util.Map	copyMap(java.util.Map map)
TemplateModel	get(java.lang.String key) Gets a TemplateModel from the hash.
boolean	isEmpty()
TemplateCollectionModel	keys()
TemplateHashModelEx2.KeyValuePairIterator	keyValuePairIterator()
void	put(java.lang.String key, boolean b) Puts a boolean in the map
void	put(java.lang.String key, java.lang.Object value) Adds a key-value entry to this hash.
void	putAll(java.util.Map m) Adds all the key/value entries in the map
void	remove(java.lang.String key) Removes the given key from the underlying map.
int	size()
SimpleHash	synchronizedWrapper()
java.util.Map	toMap() Note that this method creates and returns a deep-copy of the underlying hash used internally.
java.lang.String	toString() Returns the toString() of the underlying Map.
TemplateCollectionModel	values()

Methods inherited from class freemarker.template.WrappingTemplateModel

getDefaultObjectWrapper, getObjectWrapper, setDefaultObjectWrapper, setObjectWrapper, wrap

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleHash

@Deprecated
public SimpleHash()

Deprecated. Use SimpleHash(ObjectWrapper)

Constructs an empty hash that uses the default wrapper set in WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper).

SimpleHash

@Deprecated
public SimpleHash(java.util.Map map)

Deprecated. Use SimpleHash(Map, ObjectWrapper)

Creates a new simple hash with the copy of the underlying map and the default wrapper set in WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper).

Parameters:

map - The Map to use for the key/value pairs. It makes a copy for internal use. If the map implements the SortedMap interface, the internal copy will be a TreeMap, otherwise it will be a HashMap.

SimpleHash

public SimpleHash(ObjectWrapper wrapper)

Creates an empty simple hash using the specified object wrapper.

Parameters:

wrapper - The object wrapper to use to wrap objects into TemplateModel instances. If null, the default wrapper set in WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper) is used.

SimpleHash

public SimpleHash(java.util.Map<java.lang.String,java.lang.Object> directMap,
                  ObjectWrapper wrapper,
                  int overloadDistinction)

Creates an instance that will use the specified Map directly as its backing store; beware, the Map will be possibly modified by SimpleHash, even if you only read the SimpleHash. That's because when a value is read, it's replaced with the corresponding TemplateModel.

The goal of this constructor is to allow you to control technical aspects, like the initial capacity, and ordering of the underlying Map implementation. The iteration order of the SimpleHash will be the same as of the underlying Map.

Parameters:

directMap - The map that the instance will use directly as backing storage; possibly will be modified, even when you only read the SimpleHash! Must allow any kind of object as value, including null! Supporting null keys is not needed.

overloadDistinction - To avoid ambiguity with other overloads; the value is unused.

Since:

2.3.30

SimpleHash

public SimpleHash(java.util.Map map,
                  ObjectWrapper wrapper)

Creates a new hash by shallow-coping (possibly cloning) the underlying map; in many applications you should use DefaultMapAdapter instead.

Parameters:

map - The Map to use for the key/value pairs. It makes a copy for internal use. If the map implements the SortedMap interface, the internal copy will be a TreeMap, otherwise it will be a

wrapper - The object wrapper to use to wrap contained objects into TemplateModel instances. Using null is deprecated but allowed, in which case the deprecated default wrapper set in WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper) is used.

Method Detail

copyMap

protected java.util.Map copyMap(java.util.Map map)

put

public void put(java.lang.String key,
                java.lang.Object value)

Adds a key-value entry to this hash.

Parameters:

key - The name by which the object is identified in the template.

value - The value to which the name will be associated. This will only be wrapped to TemplateModel lazily when it's first read.

put

public void put(java.lang.String key,
                boolean b)

Puts a boolean in the map

Parameters:

key - the name by which the resulting TemplateModel is identified in the template.

b - the boolean to store.

get

public TemplateModel get(java.lang.String key)
                  throws TemplateModelException

Description copied from interface: TemplateHashModel

Gets a TemplateModel from the hash.

Specified by:

get in interface TemplateHashModel

Parameters:

key - the name by which the TemplateModel is identified in the template.

Returns:

the TemplateModel referred to by the key, or null if not found.

Throws:

TemplateModelException

containsKey

public boolean containsKey(java.lang.String key)

Tells if the map contains a key or not, regardless if the associated value is null or not.

Since:

2.3.20

remove

public void remove(java.lang.String key)

Removes the given key from the underlying map.

Parameters:

key - the key to be removed

putAll

public void putAll(java.util.Map m)

Adds all the key/value entries in the map

Parameters:

m - the map with the entries to add, the keys are assumed to be strings.

toMap

public java.util.Map toMap()
                    throws TemplateModelException

Note that this method creates and returns a deep-copy of the underlying hash used internally. This could be a gotcha for some people at some point who want to alter something in the data model, but we should maintain our immutability semantics (at least using default SimpleXXX wrappers) for the data model. It will recursively unwrap the stuff in the underlying container.

Throws:

TemplateModelException

toString

public java.lang.String toString()

Returns the toString() of the underlying Map.

Overrides:

toString in class java.lang.Object

size

public int size()

Specified by:

size in interface TemplateHashModelEx

Returns:

the number of key/value mappings in the hash.

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface TemplateHashModel

keys

public TemplateCollectionModel keys()

Specified by:

keys in interface TemplateHashModelEx

Returns:

a collection containing the keys in the hash. Every element of the returned collection must implement the TemplateScalarModel (as the keys of hashes are always strings).

values

public TemplateCollectionModel values()

Specified by:

values in interface TemplateHashModelEx

Returns:

a collection containing the values in the hash. The elements of the returned collection can be any kind of TemplateModel-s.

keyValuePairIterator

public TemplateHashModelEx2.KeyValuePairIterator keyValuePairIterator()

Specified by:

keyValuePairIterator in interface TemplateHashModelEx2

Returns:

The iterator that walks through the key-value pairs in the hash. Not null.

synchronizedWrapper

public SimpleHash synchronizedWrapper()