2021SC@SDUSC
目录
SimpleCollection.java
源码展示
package freemarker.template;
import java.io.Serializable;
import java.util.Collection;
import java.util.Iterator;
/**
* A simple implementation of {@link TemplateCollectionModel}.
* It's able to wrap <tt>java.util.Iterator</tt>-s and <tt>java.util.Collection</tt>-s.
* If you wrap an <tt>Iterator</tt>, the variable can be <#list>-ed only once!
*
* <p>Consider using {@link SimpleSequence} instead of this class if you want to wrap <tt>Iterator</tt>s.
* <tt>SimpleSequence</tt> will read all elements of the <tt>Iterator</tt>, and store them in a <tt>List</tt>
* (this may cause too high resource consumption in some applications), so you can list the variable
* for unlimited times. Also, if you want to wrap <tt>Collection</tt>s, and then list the resulting
* variable for many times, <tt>SimpleSequence</tt> may gives better performance, as the
* wrapping of non-<tt>TemplateModel</tt> objects happens only once.
*
* <p>This class is thread-safe. The returned {@link TemplateModelIterator}-s
* are <em>not</em> thread-safe.
*/
public class SimpleCollection extends WrappingTemplateModel
implements TemplateCollectionModel, Serializable {
private boolean iteratorOwned;
private final Iterator iterator;
private final Iterable iterable;
/**
* @deprecated Use {@link #SimpleCollection(Iterator, ObjectWrapper)}
*/
@Deprecated
public SimpleCollection(Iterator iterator) {
this.iterator = iterator;
iterable = null;
}
/**
* @deprecated Use {@link #SimpleCollection(Iterable, ObjectWrapper)} instead.
*/
@Deprecated
public SimpleCollection(Iterable iterable) {
this.iterable = iterable;
iterator = null;
}
/**
* Same as {@link SimpleCollection#SimpleCollection(Iterable)}; kept for binary compatibility.
*
* @deprecated Use {@link #SimpleCollection(Iterable, ObjectWrapper)} instead.
*/
@Deprecated
public SimpleCollection(Collection collection) {
this((Iterable) collection);
}
/**
* Same as {@link SimpleCollection#SimpleCollection(Iterable, ObjectWrapper)}; kept for binary compatibility.
*/
public SimpleCollection(Collection collection, ObjectWrapper wrapper) {
this((Iterable) collection, wrapper);
}
public SimpleCollection(Iterator iterator, ObjectWrapper wrapper) {
super(wrapper);
this.iterator = iterator;
iterable = null;
}
/**
* @param iterable Note that this was a {@link Collection} before 2.3.27, not an {@link Iterable}
*/
public SimpleCollection(Iterable iterable, ObjectWrapper wrapper) {
super(wrapper);
this.iterable = iterable;
iterator = null;
}
/**
* Retrieves a template model iterator that is used to iterate over the elements in this collection.
*
* <p>When you wrap an <tt>Iterator</tt> and you get <tt>TemplateModelIterator</tt> for multiple times,
* only on of the returned <tt>TemplateModelIterator</tt> instances can be really used. When you have called a
* method of a <tt>TemplateModelIterator</tt> instance, all other instance will throw a
* <tt>TemplateModelException</tt> when you try to call their methods, since the wrapped <tt>Iterator</tt>
* can't return the first element anymore.
*/
@Override
public TemplateModelIterator iterator() {
return iterator != null
? new SimpleTemplateModelIterator(iterator, false)
: new SimpleTemplateModelIterator(iterable.iterator(), true);
}
/**
* Wraps an {@link Iterator}; not thread-safe. The encapsulated {@link Iterator} may be accessible from multiple
* threads (as multiple {@link SimpleTemplateModelIterator} instance can wrap the same {@link Iterator} instance),
* but if the {@link Iterator} was marked in the constructor as shared, the first thread which uses the
* {@link Iterator} will monopolize that.
*/
private class SimpleTemplateModelIterator implements TemplateModelIterator {
private final Iterator iterator;
private boolean iteratorOwnedByMe;
SimpleTemplateModelIterator(Iterator iterator, boolean iteratorOwnedByMe) {
this.iterator = iterator;
this.iteratorOwnedByMe = iteratorOwnedByMe;
}
@Override
public TemplateModel next() throws TemplateModelException {
if (!iteratorOwnedByMe) {
synchronized (SimpleCollection.this) {
checkIteratorOwned();
iteratorOwned = true;
iteratorOwnedByMe = true;
}
}
if (!iterator.hasNext()) {
throw new TemplateModelException("The collection has no more items.");
}
Object value = iterator.next();
return value instanceof TemplateModel ? (TemplateModel) value : wrap(value);
}
@Override
public boolean hasNext() throws TemplateModelException {
// Calling hasNext may looks safe, but I have met sync. problems.
if (!iteratorOwnedByMe) {
synchronized (SimpleCollection.this) {
checkIteratorOwned();
}
}
return iterator.hasNext();
}
private void checkIteratorOwned() throws TemplateModelException {
if (iteratorOwned) {
throw new TemplateModelException(
"This collection value wraps a java.util.Iterator, thus it can be listed only once.");
}
}
}
}
关键代码分析
iterator()
//检索用于遍历此集合中的元素的模板模型迭代器//
public TemplateModelIterator iterator() {
/*当包装一个迭代器并多次获得TemplateModelIterator时，只有返回的TemplateModelIterator实例才能真正使用。*/
return iterator != null
? new SimpleTemplateModelIterator(iterator, false)
: new SimpleTemplateModelIterator(iterable.iterator(), true);
}next()
public TemplateModel next() throws TemplateModelException {
// 遍历收集到的信息，把遍历的结果存储到一个对象中返回//
if (!iteratorOwnedByMe) {
synchronized (SimpleCollection.this) {
checkIteratorOwned();
iteratorOwned = true;
iteratorOwnedByMe = true;
}
}
if (!iterator.hasNext()) {
throw new TemplateModelException("The collection has no more items.");
}
Object value = iterator.next();
return value instanceof TemplateModel ? (TemplateModel) value : wrap(value);
}SimpleHash.java
源码展示
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package freemarker.template;
import java.io.Serializable;
import java.util.ConcurrentModificationException;
import java.util.HashMap;
import java.util.Iterator;
import java.util.Map;
import java.util.SortedMap;
import java.util.TreeMap;
import freemarker.core._DelayedJQuote;
import freemarker.core._TemplateModelException;
import freemarker.ext.beans.BeansWrapper;
/**
* A simple implementation of the {@link TemplateHashModelEx} interface, using its own underlying {@link Map} or
* {@link SortedMap} for storing the hash entries. If you are wrapping an already existing {@link Map}, you should
* certainly use {@link DefaultMapAdapter} instead (see comparison below).
*
* <p>
* This class is thread-safe if you don't call modifying methods (like {@link #put(String, Object)},
* {@link #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.
*
* <p>
* <b>{@link SimpleHash} VS {@link DefaultMapAdapter} - Which to use when?</b>
*
* <p>
* For a {@link Map} that exists regardless of FreeMarker, only you need to access it from templates,
* {@link DefaultMapAdapter} should be the default choice, as it reflects the exact behavior of the underlying
* {@link 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).
*
* <p>
* For a hash that's made specifically to be used from templates, creating an empty {@link SimpleHash} then filling it
* with {@link SimpleHash#put(String, Object)} is usually the way to go, as the resulting hash is significantly faster
* to read from templates than a {@link DefaultMapAdapter} (though it's somewhat slower to read from a plain Java method
* to which it had to be passed adapted to a {@link Map}).
*
* <p>
* It also matters if for how many times will the <em>same</em> {@link Map} entry be read from the template(s) later, on
* average. If, on average, you read each entry for more than 4 times, {@link SimpleHash} will be most certainly faster,
* but if for 2 times or less (and especially if not at all) then {@link DefaultMapAdapter} will be faster. Before
* choosing based on performance though, pay attention to the behavioral differences; {@link SimpleHash} will
* shallow-copy the original {@link Map} at construction time, so key order will be lost in some cases, and it won't
* reflect {@link Map} content changes after the {@link SimpleHash} construction, also {@link SimpleHash} can't be
* unwrapped to the original {@link Map} instance.
*
* @see DefaultMapAdapter
* @see TemplateHashModelEx
*/
public class SimpleHash extends WrappingTemplateModel implements TemplateHashModelEx2, Serializable {
private final Map map;
private boolean putFailed;
private Map unwrappedMap;
/**
* Constructs an empty hash that uses the default wrapper set in
* {@link WrappingTemplateModel#setDefaultObjectWrapper(ObjectWrapper)}.
*
* @deprecated Use {@link #SimpleHash(ObjectWrapper)}
*/
@Deprecated
public SimpleHash() {
this((ObjectWrapper) null);
}
/**
* Creates a new simple hash with the copy of the underlying map and the
* default wrapper set in
* {@link WrappingTemplateModel#setDefaultObjectWrapper(ObjectWrapper)}.
* @param map The Map to use for the key/value pairs. It makes a copy for
* internal use. If the map implements the {@link SortedMap} interface, the
* internal copy will be a {@link TreeMap}, otherwise it will be a
* {@link HashMap}.
*
* @deprecated Use {@link #SimpleHash(Map, ObjectWrapper)}
*/
@Deprecated
public SimpleHash(Map map) {
this(map, null);
}
/**
* Creates an empty simple hash using the specified object wrapper.
* @param wrapper The object wrapper to use to wrap objects into
* {@link TemplateModel} instances. If null, the default wrapper set in
* {@link WrappingTemplateModel#setDefaultObjectWrapper(ObjectWrapper)} is
* used.
*/
public SimpleHash(ObjectWrapper wrapper) {
super(wrapper);
map = new HashMap();
}
/**
* Creates an instance that will use the specified {@link Map} directly as its backing store; beware, the
* {@link Map} will be possibly modified by {@link SimpleHash}, even if you only read the {@link SimpleHash}.
* That's because when a value is read, it's replaced with the corresponding {@link TemplateModel}.
*
* <p>The goal of this constructor is to allow you to control technical aspects, like the initial capacity, and
* ordering of the underlying {@link Map} implementation. The iteration order of the {@link SimpleHash} will be
* the same as of the underlying {@link Map}.
*
* @param directMap The map that the instance will use directly as backing storage; possibly will be modified,
* even when you only read the {@link SimpleHash}! Must allow any kind of object as value,
* including {@code null}! Supporting {@code null} keys is not needed.
*
* @param overloadDistinction To avoid ambiguity with other overloads; the value is unused.
*
* @since 2.3.30
*/
public SimpleHash(Map<String, Object> directMap, ObjectWrapper wrapper, int overloadDistinction) {
super(wrapper);
this.map = directMap;
}
/**
* Creates a new hash by shallow-coping (possibly cloning) the underlying map; in many applications you should use
* {@link DefaultMapAdapter} instead.
*
* @param map
* The Map to use for the key/value pairs. It makes a copy for internal use. If the map implements the
* {@link SortedMap} interface, the internal copy will be a {@link TreeMap}, otherwise it will be a
* @param wrapper
* The object wrapper to use to wrap contained objects into {@link TemplateModel} instances. Using
* {@code null} is deprecated but allowed, in which case the deprecated default wrapper set in
* {@link WrappingTemplateModel#setDefaultObjectWrapper(ObjectWrapper)} is used.
*/
public SimpleHash(Map map, ObjectWrapper wrapper) {
super(wrapper);
Map mapCopy;
try {
mapCopy = copyMap(map);
} catch (ConcurrentModificationException cme) {
//This will occur extremely rarely.
//If it does, we just wait 5 ms and try again. If
// the ConcurrentModificationException
// is thrown again, we just let it bubble up this time.
// TODO: Maybe we should log here.
try {
Thread.sleep(5);
} catch (InterruptedException ie) {
}
synchronized (map) {
mapCopy = copyMap(map);
}
}
this.map = mapCopy;
}
protected Map copyMap(Map map) {
if (map instanceof HashMap) {
return (Map) ((HashMap) map).clone();
}
if (map instanceof SortedMap) {
if (map instanceof TreeMap) {
return (Map) ((TreeMap) map).clone();
} else {
return new TreeMap((SortedMap) map);
}
}
return new HashMap(map);
}
/**
* Adds a key-value entry to this hash.
*
* @param key
* The name by which the object is identified in the template.
* @param value
* The value to which the name will be associated. This will only be wrapped to {@link TemplateModel}
* lazily when it's first read.
*/
public void put(String key, Object value) {
map.put(key, value);
unwrappedMap = null;
}
/**
* Puts a boolean in the map
*
* @param key the name by which the resulting <tt>TemplateModel</tt>
* is identified in the template.
* @param b the boolean to store.
*/
public void put(String key, boolean b) {
put(key, b ? TemplateBooleanModel.TRUE : TemplateBooleanModel.FALSE);
}
@Override
public TemplateModel get(String key) throws TemplateModelException {
Object result;
try {
result = map.get(key);
} catch (ClassCastException e) {
throw new _TemplateModelException(e,
"ClassCastException while getting Map entry with String key ",
new _DelayedJQuote(key));
} catch (NullPointerException e) {
throw new _TemplateModelException(e,
"NullPointerException while getting Map entry with String key ",
new _DelayedJQuote(key));
}
// The key to use for putting -- it's the key that already exists in
// the map (either key or charKey below). This way, we'll never put a
// new key in the map, avoiding spurious ConcurrentModificationException
// from another thread iterating over the map, see bug #1939742 in
// SourceForge tracker.
Object putKey = null;
if (result == null) {
// Check for Character key if this is a single-character string.
// In SortedMap-s, however, we can't do that safely, as it can cause ClassCastException.
if (key.length() == 1 && !(map instanceof SortedMap)) {
Character charKey = Character.valueOf(key.charAt(0));
try {
result = map.get(charKey);
if (result != null || map.containsKey(charKey)) {
putKey = charKey;
}
} catch (ClassCastException e) {
throw new _TemplateModelException(e,
"ClassCastException while getting Map entry with Character key ",
new _DelayedJQuote(key));
} catch (NullPointerException e) {
throw new _TemplateModelException(e,
"NullPointerException while getting Map entry with Character key ",
new _DelayedJQuote(key));
}
}
if (putKey == null) {
if (!map.containsKey(key)) {
return null;
} else {
putKey = key;
}
}
} else {
putKey = key;
}
if (result instanceof TemplateModel) {
return (TemplateModel) result;
}
TemplateModel tm = wrap(result);
if (!putFailed) {
try {
map.put(putKey, tm);
} catch (Exception e) {
// If it's immutable or something, we just keep going.
putFailed = true;
}
}
return tm;
}
/**
* Tells if the map contains a key or not, regardless if the associated value is {@code null} or not.
* @since 2.3.20
*/
public boolean containsKey(String key) {
return map.containsKey(key);
}
/**
* Removes the given key from the underlying map.
*
* @param key the key to be removed
*/
public void remove(String key) {
map.remove(key);
}
/**
* Adds all the key/value entries in the map
* @param m the map with the entries to add, the keys are assumed to be strings.
*/
public void putAll(Map m) {
for (Iterator it = m.entrySet().iterator(); it.hasNext(); ) {
Map.Entry entry = (Map.Entry) it.next();
this.put((String) entry.getKey(), entry.getValue());
}
}
/**
* 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.
*/
public Map toMap() throws TemplateModelException {
if (unwrappedMap == null) {
Class mapClass = this.map.getClass();
Map m = null;
try {
m = (Map) mapClass.newInstance();
} catch (Exception e) {
throw new TemplateModelException("Error instantiating map of type " + mapClass.getName() + "\n" + e.getMessage());
}
// Create a copy to maintain immutability semantics and
// Do nested unwrapping of elements if necessary.
BeansWrapper bw = BeansWrapper.getDefaultInstance();
for (Iterator it = map.entrySet().iterator(); it.hasNext(); ) {
Map.Entry entry = (Map.Entry) it.next();
Object key = entry.getKey();
Object value = entry.getValue();
if (value instanceof TemplateModel) {
value = bw.unwrap((TemplateModel) value);
}
m.put(key, value);
}
unwrappedMap = m;
}
return unwrappedMap;
}
/**
* Returns the {@code toString()} of the underlying {@link Map}.
*/
@Override
public String toString() {
return map.toString();
}
@Override
public int size() {
return map.size();
}
@Override
public boolean isEmpty() {
return map == null || map.isEmpty();
}
@Override
public TemplateCollectionModel keys() {
return new SimpleCollection(map.keySet(), getObjectWrapper());
}
@Override
public TemplateCollectionModel values() {
return new SimpleCollection(map.values(), getObjectWrapper());
}
@Override
public KeyValuePairIterator keyValuePairIterator() {
return new MapKeyValuePairIterator(map, getObjectWrapper());
}
public SimpleHash synchronizedWrapper() {
return new SynchronizedHash();
}
private class SynchronizedHash extends SimpleHash {
@Override
public boolean isEmpty() {
synchronized (SimpleHash.this) {
return SimpleHash.this.isEmpty();
}
}
@Override
public void put(String key, Object obj) {
synchronized (SimpleHash.this) {
SimpleHash.this.put(key, obj);
}
}
@Override
public TemplateModel get(String key) throws TemplateModelException {
synchronized (SimpleHash.this) {
return SimpleHash.this.get(key);
}
}
@Override
public void remove(String key) {
synchronized (SimpleHash.this) {
SimpleHash.this.remove(key);
}
}
@Override
public int size() {
synchronized (SimpleHash.this) {
return SimpleHash.this.size();
}
}
@Override
public TemplateCollectionModel keys() {
synchronized (SimpleHash.this) {
return SimpleHash.this.keys();
}
}
@Override
public TemplateCollectionModel values() {
synchronized (SimpleHash.this) {
return SimpleHash.this.values();
}
}
@Override
public KeyValuePairIterator keyValuePairIterator() {
synchronized (SimpleHash.this) {
return SimpleHash.this.keyValuePairIterator();
}
}
@Override
public Map toMap() throws TemplateModelException {
synchronized (SimpleHash.this) {
return SimpleHash.this.toMap();
}
}
}
}
关键代码分析
SimpleHash()
//map—用于键/值对的map。它做了一个内部使用的拷贝。如果映射实现了SortedMap接口，则内部副本将是TreeMap
//wrapper—用于将包含的对象包装到TemplateModel实例中的对象包装器
public SimpleHash(Map map, ObjectWrapper wrapper) {
super(wrapper);
Map mapCopy;
try {
mapCopy = copyMap(map);
} catch (ConcurrentModificationException cme) {
//再次抛出，只是让它这次冒泡。//
try {
Thread.sleep(5);
} catch (InterruptedException ie) {
}
synchronized (map) {
mapCopy = copyMap(map);
}
}
this.map = mapCopy;
}
get()
//描述从接口复制:TemplateHashModel,从散列获取TemplateModel。
public TemplateModel get(String key) throws TemplateModelException {
//参数:key—模板中用来标识TemplateModel的名称。
Object result;
try {
result = map.get(key);
} catch (ClassCastException e) {
throw new _TemplateModelException(e,
"ClassCastException while getting Map entry with String key ",
new _DelayedJQuote(key));
} catch (NullPointerException e) {
throw new _TemplateModelException(e,
"NullPointerException while getting Map entry with String key ",
new _DelayedJQuote(key));
}
// The key to use for putting -- it's the key that already exists in
// the map (either key or charKey below). This way, we'll never put a
// new key in the map, avoiding spurious ConcurrentModificationException
// from another thread iterating over the map, see bug #1939742 in
// SourceForge tracker.
Object putKey = null;
//规定:获取接口TemplateHashModel
if (result == null) {
// Check for Character key if this is a single-character string.
// In SortedMap-s, however, we can't do that safely, as it can cause ClassCastException.
if (key.length() == 1 && !(map instanceof SortedMap)) {
Character charKey = Character.valueOf(key.charAt(0));
try {
result = map.get(charKey);
if (result != null || map.containsKey(charKey)) {
putKey = charKey;
}
} catch (ClassCastException e) {
throw new _TemplateModelException(e,
"ClassCastException while getting Map entry with Character key ",
new _DelayedJQuote(key));
} catch (NullPointerException e) {
throw new _TemplateModelException(e,
"NullPointerException while getting Map entry with Character key ",
new _DelayedJQuote(key));
}
}
if (putKey == null) {
if (!map.containsKey(key)) {
return null;
} else {
putKey = key;
}
}
} else {
putKey = key;
}
if (result instanceof TemplateModel) {
return (TemplateModel) result;
}
TemplateModel tm = wrap(result);
if (!putFailed) {
try {
map.put(putKey, tm);
//抛出:TemplateModelException
} catch (Exception e) {
// If it's immutable or something, we just keep going.
putFailed = true;
}
}
return tm;
//返回:由键引用的TemplateModel，如果没有找到则为空。
}
/**
304
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
