Class SimpleHash
- All Implemented Interfaces:
TemplateHashModel,TemplateHashModelEx,TemplateHashModelEx2,TemplateModel,Serializable
- Direct Known Subclasses:
AllHttpScopesHashModel,AllHttpScopesHashModel,Environment.Namespace
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
ConstructorsConstructorDescriptionDeprecated.SimpleHash(ObjectWrapper wrapper)Creates an empty simple hash using the specified object wrapper.SimpleHash(Map map)Deprecated.SimpleHash(Map<String,Object> directMap, ObjectWrapper wrapper, int overloadDistinction)Creates an instance that will use the specifiedMapdirectly as its backing store; beware, theMapwill be possibly modified bySimpleHash, even if you only read theSimpleHash.SimpleHash(Map map, ObjectWrapper wrapper)Creates a new hash by shallow-coping (possibly cloning) the underlying map; in many applications you should useDefaultMapAdapterinstead. -
Method Summary
Modifier and TypeMethodDescriptionbooleancontainsKey(String key)Tells if the map contains a key or not, regardless if the associated value isnullor not.protected MapGets aTemplateModelfrom the hash.booleanisEmpty()keys()voidPuts a boolean in the mapvoidAdds a key-value entry to this hash.voidAdds all the key/value entries in the mapvoidRemoves the given key from the underlying map.intsize()toMap()Note that this method creates and returns a deep-copy of the underlying hash used internally.toString()Returns thetoString()of the underlyingMap.values()Methods inherited from class freemarker.template.WrappingTemplateModel
getDefaultObjectWrapper, getObjectWrapper, setDefaultObjectWrapper, setObjectWrapper, wrap
-
Constructor Details
-
SimpleHash
Deprecated.Constructs an empty hash that uses the default wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper). -
SimpleHash
Deprecated.Creates a new simple hash with the copy of the underlying map and the default wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper). -
SimpleHash
Creates an empty simple hash using the specified object wrapper.- Parameters:
wrapper- The object wrapper to use to wrap objects intoTemplateModelinstances. If null, the default wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)is used.
-
SimpleHash
Creates an instance that will use the specifiedMapdirectly as its backing store; beware, theMapwill be possibly modified bySimpleHash, even if you only read theSimpleHash. That's because when a value is read, it's replaced with the correspondingTemplateModel.The goal of this constructor is to allow you to control technical aspects, like the initial capacity, and ordering of the underlying
Mapimplementation. The iteration order of theSimpleHashwill be the same as of the underlyingMap.- Parameters:
directMap- The map that the instance will use directly as backing storage; possibly will be modified, even when you only read theSimpleHash! Must allow any kind of object as value, includingnull! Supportingnullkeys is not needed.overloadDistinction- To avoid ambiguity with other overloads; the value is unused.- Since:
- 2.3.30
-
SimpleHash
Creates a new hash by shallow-coping (possibly cloning) the underlying map; in many applications you should useDefaultMapAdapterinstead.- Parameters:
map- The Map to use for the key/value pairs. It makes a copy for internal use. If the map implements theSortedMapinterface, the internal copy will be aTreeMap, otherwise it will be awrapper- The object wrapper to use to wrap contained objects intoTemplateModelinstances. Usingnullis deprecated but allowed, in which case the deprecated default wrapper set inWrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper)is used.
-
-
Method Details
-
copyMap
-
put
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 toTemplateModellazily when it's first read.
-
put
Puts a boolean in the map- Parameters:
key- the name by which the resultingTemplateModelis identified in the template.b- the boolean to store.
-
get
Description copied from interface:TemplateHashModelGets aTemplateModelfrom the hash.- Specified by:
getin interfaceTemplateHashModel- Parameters:
key- The name by which theTemplateModelis identified in the template.- Returns:
- The
TemplateModelreferred to by the key, ornullif not found. - Throws:
TemplateModelException
-
containsKey
Tells if the map contains a key or not, regardless if the associated value isnullor not.- Since:
- 2.3.20
-
remove
Removes the given key from the underlying map.- Parameters:
key- the key to be removed
-
putAll
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
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
Returns thetoString()of the underlyingMap. -
size
public int size()- Specified by:
sizein interfaceTemplateHashModelEx- Returns:
- the number of key/value mappings in the hash.
-
isEmpty
public boolean isEmpty()- Specified by:
isEmptyin interfaceTemplateHashModel
-
keys
- Specified by:
keysin 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
- Specified by:
valuesin interfaceTemplateHashModelEx- Returns:
- a collection containing the values in the hash. The elements of the
returned collection can be any kind of
TemplateModel-s.
-
keyValuePairIterator
- Specified by:
keyValuePairIteratorin interfaceTemplateHashModelEx2- Returns:
- The iterator that walks through the key-value pairs in the hash. Not
null.
-
synchronizedWrapper
-
SimpleHash(ObjectWrapper)