Class SimpleHash
- java.lang.Object
-
- freemarker.template.WrappingTemplateModel
-
- freemarker.template.SimpleHash
-
- All Implemented Interfaces:
TemplateHashModel
,TemplateHashModelEx
,TemplateModel
,Serializable
- Direct Known Subclasses:
AllHttpScopesHashModel
,Environment.Namespace
public class SimpleHash extends WrappingTemplateModel implements TemplateHashModelEx, Serializable
A simple implementation of theTemplateHashModelEx
interface, using its own underlyingMap
orSortedMap
for storing the hash entries. If you are wrapping an already existingMap
, you should certainly useDefaultMapAdapter
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
VSDefaultMapAdapter
- 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 underlyingMap
(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 withput(String, Object)
is usually the way to go, as the resulting hash is significantly faster to read from templates than aDefaultMapAdapter
(though it's somewhat slower to read from a plain Java method to which it had to be passed adapted to aMap
).If regardless of which of the above two cases stand, you just need to (or more convenient to) create the hash from a
Map
(viaSimpleHash(Map, ObjectWrapper)
orSimpleHash(Map, ObjectWrapper)
), which will be the faster depends on how many times will the sameMap
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) thenDefaultMapAdapter
will be. Before choosing based on performance though, pay attention to the behavioral differences;SimpleHash
will shallow-copy the originalMap
at construction time, so key order will be lost in some cases, and it won't reflectMap
content changes after theSimpleHash
construction, alsoSimpleHash
can't be unwrapped to the originalMap
instance.- See Also:
DefaultMapAdapter
,TemplateHashModelEx
, Serialized Form
-
-
Field Summary
-
Fields inherited from interface freemarker.template.TemplateModel
NOTHING
-
-
Constructor Summary
Constructors Constructor Description SimpleHash()
Deprecated.SimpleHash(ObjectWrapper wrapper)
Creates an empty simple hash using the specified object wrapper.SimpleHash(Map map)
Deprecated.SimpleHash(Map map, ObjectWrapper wrapper)
Creates a new hash by shallow-coping (possibly cloning) the underlying map; in many applications you should useDefaultMapAdapter
instead.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
containsKey(String key)
Tells if the map contains a key or not, regardless if the associated value isnull
or not.protected Map
copyMap(Map map)
TemplateModel
get(String key)
Gets a TemplateModel from the hash.boolean
isEmpty()
TemplateCollectionModel
keys()
void
put(String key, boolean b)
Puts a boolean in the mapvoid
put(String key, Object value)
Adds a key-value entry to this hash.void
putAll(Map m)
Adds all the key/value entries in the mapvoid
remove(String key)
Removes the given key from the underlying map.int
size()
SimpleHash
synchronizedWrapper()
Map
toMap()
Note that this method creates and returns a deep-copy of the underlying hash used internally.String
toString()
Returns thetoString()
of the underlyingMap
.TemplateCollectionModel
values()
-
Methods inherited from class freemarker.template.WrappingTemplateModel
getDefaultObjectWrapper, getObjectWrapper, setDefaultObjectWrapper, setObjectWrapper, wrap
-
-
-
-
Constructor Detail
-
SimpleHash
public SimpleHash()
Deprecated.Constructs an empty hash that uses the default wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)
.
-
SimpleHash
public SimpleHash(Map map)
Deprecated.Creates a new simple hash with the copy of the underlying map and the default wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)
.
-
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 intoTemplateModel
instances. If null, the default wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)
is used.
-
SimpleHash
public SimpleHash(Map map, ObjectWrapper wrapper)
Creates a new hash by shallow-coping (possibly cloning) the underlying map; in many applications you should useDefaultMapAdapter
instead.- Parameters:
map
- The Map to use for the key/value pairs. It makes a copy for internal use. If the map implements theSortedMap
interface, the internal copy will be aTreeMap
, otherwise it will be awrapper
- The object wrapper to use to wrap contained objects intoTemplateModel
instances. Usingnull
is deprecated but allowed, in which case the deprecated default wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)
is used.
-
-
Method Detail
-
put
public void put(String key, 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 toTemplateModel
lazily when it's first read.
-
put
public void put(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(String key) throws TemplateModelException
Description copied from interface:TemplateHashModel
Gets a TemplateModel from the hash.- Specified by:
get
in interfaceTemplateHashModel
- 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(String key)
Tells if the map contains a key or not, regardless if the associated value isnull
or not.- Since:
- 2.3.20
-
remove
public void remove(String key)
Removes the given key from the underlying map.- Parameters:
key
- the key to be removed
-
putAll
public void putAll(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 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
-
size
public int size()
- Specified by:
size
in interfaceTemplateHashModelEx
- Returns:
- the number of key/value mappings in the hash.
-
isEmpty
public boolean isEmpty()
- Specified by:
isEmpty
in interfaceTemplateHashModel
-
keys
public TemplateCollectionModel keys()
- Specified by:
keys
in interfaceTemplateHashModelEx
- 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 interfaceTemplateHashModelEx
- Returns:
- a collection containing the values in the hash. The elements of the
returned collection can be any kind of
TemplateModel
-s.
-
synchronizedWrapper
public SimpleHash synchronizedWrapper()
-
-