You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2017/02/10 23:47:05 UTC

[1/5] incubator-freemarker git commit: - Totally redesigned TemplateLoader interface. The FM2 TemplateLoader can't be adapted (wrapped) to it, but usually

Repository: incubator-freemarker
Updated Branches:
  refs/heads/3 f8d405744 -> 3d0fdc8c7


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/test/CopyrightCommentRemoverTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/test/CopyrightCommentRemoverTemplateLoader.java b/src/test/java/freemarker/test/CopyrightCommentRemoverTemplateLoader.java
index 8c4a48d..a54128f 100644
--- a/src/test/java/freemarker/test/CopyrightCommentRemoverTemplateLoader.java
+++ b/src/test/java/freemarker/test/CopyrightCommentRemoverTemplateLoader.java
@@ -19,14 +19,27 @@
 package freemarker.test;
 
 import java.io.IOException;
+import java.io.InputStream;
 import java.io.Reader;
+import java.io.Serializable;
 import java.io.StringReader;
+import java.nio.charset.StandardCharsets;
 
 import org.apache.commons.io.IOUtils;
+import org.apache.commons.io.input.ReaderInputStream;
 
 import freemarker.cache.TemplateLoader;
+import freemarker.cache.TemplateLoaderSession;
+import freemarker.cache.TemplateLoadingResult;
+import freemarker.cache.TemplateLoadingResultStatus;
+import freemarker.cache.TemplateLoadingSource;
 import freemarker.test.utility.TestUtil;
 
+/**
+ * Removes the Apache copyright boiler plate from the beginning of the template, so that they don't mess up the expected
+ * template output. This can interfere with tests that try to test I/O errors and such low level things, so use with
+ * care. 
+ */
 public class CopyrightCommentRemoverTemplateLoader implements TemplateLoader {
 
     private final TemplateLoader innerTemplateLoader;
@@ -35,16 +48,38 @@ public class CopyrightCommentRemoverTemplateLoader implements TemplateLoader {
         this.innerTemplateLoader = innerTemplateLoader;
     }
 
-    public Object findTemplateSource(String name) throws IOException {
-        return innerTemplateLoader.findTemplateSource(name);
+    @Override
+    public TemplateLoaderSession createSession() {
+        return null;
+    }
+
+    @Override
+    public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom,
+            Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws IOException {
+        TemplateLoadingResult result = innerTemplateLoader.load(name, ifSourceDiffersFrom, ifVersionDiffersFrom, session);
+        if (result.getStatus() != TemplateLoadingResultStatus.OPENED) {
+            return result;
+        }
+        if (result.getInputStream() != null) {
+            return new TemplateLoadingResult(
+                    result.getSource(), result.getVersion(), getWithoutCopyrightHeader(result.getInputStream()),
+                    result.getTemplateConfiguration());
+        } else {
+            return new TemplateLoadingResult(
+                    result.getSource(), result.getVersion(), getWithoutCopyrightHeader(result.getReader()),
+                    result.getTemplateConfiguration());
+        }
     }
 
-    public long getLastModified(Object templateSource) {
-        return innerTemplateLoader.getLastModified(templateSource);
+    @Override
+    public void resetState() {
+        // Do nothing
     }
 
-    public Reader getReader(Object templateSource, String encoding) throws IOException {
-        Reader reader = innerTemplateLoader.getReader(templateSource, encoding);
+    private Reader getWithoutCopyrightHeader(Reader reader) throws IOException {
+        if (reader == null) {
+            return null;
+        }
         try {
             String content = IOUtils.toString(reader);
             return new StringReader(TestUtil.removeFTLCopyrightComment(content));
@@ -53,8 +88,19 @@ public class CopyrightCommentRemoverTemplateLoader implements TemplateLoader {
         }
     }
 
-    public void closeTemplateSource(Object templateSource) throws IOException {
-        innerTemplateLoader.closeTemplateSource(templateSource);
+    private InputStream getWithoutCopyrightHeader(InputStream in) throws IOException {
+        if (in == null) {
+            return null;
+        }
+        try {
+            // Encoding then decosing in ISO-8859-1 is binary loseless
+            String content = IOUtils.toString(in, StandardCharsets.ISO_8859_1.name());
+            return new ReaderInputStream(
+                    new StringReader(TestUtil.removeFTLCopyrightComment(content)),
+                    StandardCharsets.ISO_8859_1);
+        } finally {
+            in.close();
+        }
     }
-
+    
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/test/MonitoredTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/test/MonitoredTemplateLoader.java b/src/test/java/freemarker/test/MonitoredTemplateLoader.java
index e088ab3..450ee19 100644
--- a/src/test/java/freemarker/test/MonitoredTemplateLoader.java
+++ b/src/test/java/freemarker/test/MonitoredTemplateLoader.java
@@ -16,31 +16,312 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-
 package freemarker.test;
 
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.io.Serializable;
+import java.io.StringReader;
+import java.io.UnsupportedEncodingException;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.List;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+import com.google.common.base.Objects;
 
-import freemarker.cache.StringTemplateLoader;
+import freemarker.cache.TemplateLoader;
+import freemarker.cache.TemplateLoaderSession;
+import freemarker.cache.TemplateLoadingResult;
+import freemarker.cache.TemplateLoadingResultStatus;
+import freemarker.cache.TemplateLoadingSource;
 
-public class MonitoredTemplateLoader extends StringTemplateLoader {
+public class MonitoredTemplateLoader implements TemplateLoader {
+
+    private final List<AbstractTemplateLoader2Event> events
+            = Collections.synchronizedList(new ArrayList<AbstractTemplateLoader2Event>());
     
-    private final List<String> templatesTried = new ArrayList<String>();
+    private Map<String, StoredTemplate> templates
+            = new ConcurrentHashMap<String, MonitoredTemplateLoader.StoredTemplate>();
+
+    @Override
+    public TemplateLoaderSession createSession() {
+        events.add(CreateSessionEvent.INSTANCE);
+        return new MonitoredTemplateLoader2Session();
+    }
+
+    @Override
+    public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom, Serializable ifVersionDiffersFrom,
+            TemplateLoaderSession session)
+            throws IOException {
+        TemplateLoadingResult result = loadInner(name, ifSourceDiffersFrom, ifVersionDiffersFrom, session);
+        events.add(new LoadEvent(name, result.getStatus()));
+        return result;
+    }
+
+    private TemplateLoadingResult loadInner(String name, TemplateLoadingSource ifSourceDiffersFrom,
+            Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws UnsupportedEncodingException {
+        if (session.isClosed()) {
+            throw new IllegalArgumentException("Template loader session is already closed.");
+        }
+        
+        StoredTemplate storedTemplate = templates.get(name);
+        if (storedTemplate == null) {
+            return TemplateLoadingResult.NOT_FOUND;
+        }
+        
+        TemplateLoadingSource source = storedTemplate.getSource();
+        Serializable version = storedTemplate.getVersion();
+        if (ifSourceDiffersFrom != null
+                && ifSourceDiffersFrom.equals(source)
+                && Objects.equal(ifVersionDiffersFrom, version)) {
+            return TemplateLoadingResult.NOT_MODIFIED;
+        }
+        
+        String content = storedTemplate.getContent();
+        return storedTemplate.inputStreamEncoding == null
+                ? new TemplateLoadingResult(source, version, new StringReader(content), null)
+                : new TemplateLoadingResult(source, version,
+                        new ByteArrayInputStream(content.getBytes(storedTemplate.inputStreamEncoding)), null);
+    }
     
     @Override
-    public Object findTemplateSource(String name) {
-        templatesTried.add(name);
-        return super.findTemplateSource(name);
+    public void resetState() {
+        events.add(ResetStateEvent.INSTANCE);
+    }
+
+    public StoredTemplate putTextTemplate(String name, String content) {
+        return putTextTemplate(name, "v1", content);
+    }
+    
+    public StoredTemplate putTextTemplate(String name, Serializable version, String content) {
+        StoredTemplate storedTemplate = new StoredTemplate(name, version, content, null);
+        templates.put(name, storedTemplate);
+        return storedTemplate;
+    }
+
+    public StoredTemplate putBinaryTemplate(String name, String content) {
+        return putBinaryTemplate(name, content, "v1");
+    }
+    
+    public StoredTemplate putBinaryTemplate(String name, String content, Serializable version) {
+        return putBinaryTemplate(name, content, null, version);
+    }
+    
+    public StoredTemplate putBinaryTemplate(String name, String content,
+            Charset inputStreamEncoding, Serializable version) {
+        StoredTemplate storedTemplate = new StoredTemplate(name, version, content,
+                inputStreamEncoding != null ? inputStreamEncoding : StandardCharsets.UTF_8);
+        templates.put(name, storedTemplate);
+        return storedTemplate;
+    }
+
+    public List<AbstractTemplateLoader2Event> getEvents() {
+        return events;
+    }
+
+    /**
+     * Gets a filtered event list.
+     */
+    @SuppressWarnings("unchecked")
+    public <E extends AbstractTemplateLoader2Event> List<E> getEvents(Class<E> eventClass) {
+        List<E> result = new ArrayList<>();
+        for (AbstractTemplateLoader2Event event : events) {
+            if (eventClass.isInstance(event)) {
+                result.add((E) event);
+            }
+        }
+        return result;
+    }
+    
+    /**
+     * Extract from the {@link #getEvents()} the template names for which {@link TemplateLoader#load} was called.
+     */
+    public List<String> getLoadNames() {
+        List<String> result = new ArrayList<>();
+        for (AbstractTemplateLoader2Event event : events) {
+            if (event instanceof LoadEvent) {
+                result.add(((LoadEvent) event).name);
+            }
+        }
+        return result;
+    }
+
+    public void clearEvents() {
+        events.clear();
+    }
+
+    @SuppressWarnings("serial")
+    public static class StoredTemplate implements TemplateLoadingSource {
+        private String name;
+        private Serializable version;
+        private String content;
+        private Charset inputStreamEncoding; 
+        
+        private StoredTemplate(String name, Serializable version, String content, Charset inputStreamEncoding) {
+            this.name = name;
+            this.version = version;
+            this.content = content;
+            this.inputStreamEncoding = inputStreamEncoding;
+        }
+    
+        public String getName() {
+            return name;
+        }
+    
+        public void setName(String name) {
+            this.name = name;
+        }
+    
+        public TemplateLoadingSource getSource() {
+            return this;
+        }
+    
+        public Serializable getVersion() {
+            return version;
+        }
+    
+        public void setVersion(Serializable version) {
+            this.version = version;
+        }
+    
+        public String getContent() {
+            return content;
+        }
+    
+        public void setContent(String content) {
+            this.content = content;
+        }
+    
+        public Charset getInputStreamEncoding() {
+            return inputStreamEncoding;
+        }
+    
+        public void setInputStreamEncoding(Charset inputStreamEncoding) {
+            this.inputStreamEncoding = inputStreamEncoding;
+        }
+        
     }
 
-    public List<String> getTemplatesTried() {
-        return templatesTried;
+    public abstract static class AbstractTemplateLoader2Event {
+        // empty
     }
+
+    public static class LoadEvent extends AbstractTemplateLoader2Event {
+        private final String name;
+        private final TemplateLoadingResultStatus resultStatus;
+        
+        public LoadEvent(String name, TemplateLoadingResultStatus resultStatus) {
+            this.name = name;
+            this.resultStatus = resultStatus;
+        }
+    
+        public String getName() {
+            return name;
+        }
+        
+        public TemplateLoadingResultStatus getResultStatus() {
+            return resultStatus;
+        }
     
-    public void clear() {
-        templatesTried.clear();
+        @Override
+        public String toString() {
+            return "LoadEvent [name=" + name + ", resultStatus=" + resultStatus + "]";
+        }
+    
+        @Override
+        public int hashCode() {
+            final int prime = 31;
+            int result = 1;
+            result = prime * result + ((name == null) ? 0 : name.hashCode());
+            result = prime * result + ((resultStatus == null) ? 0 : resultStatus.hashCode());
+            return result;
+        }
+    
+        @Override
+        public boolean equals(Object obj) {
+            if (this == obj)
+                return true;
+            if (obj == null)
+                return false;
+            if (getClass() != obj.getClass())
+                return false;
+            LoadEvent other = (LoadEvent) obj;
+            if (name == null) {
+                if (other.name != null)
+                    return false;
+            } else if (!name.equals(other.name))
+                return false;
+            if (resultStatus != other.resultStatus)
+                return false;
+            return true;
+        }
+        
     }
+
+    public static class ResetStateEvent extends AbstractTemplateLoader2Event {
     
+        public static ResetStateEvent INSTANCE = new ResetStateEvent();
+        
+        private ResetStateEvent() {
+            //
+        }
+        
+        @Override
+        public String toString() {
+            return "ResetStateEvent []";
+        }
+        
+    }
+
+    public static class CreateSessionEvent extends AbstractTemplateLoader2Event {
+        
+        public static CreateSessionEvent INSTANCE = new CreateSessionEvent();
+        
+        private CreateSessionEvent() {
+            //
+        }
+
+        @Override
+        public String toString() {
+            return "CreateSessionEvent []";
+        }
+        
+    }
+
+    public static class CloseSessionEvent extends AbstractTemplateLoader2Event {
+
+        public static CloseSessionEvent INSTANCE = new CloseSessionEvent();
+        
+        private CloseSessionEvent() {
+            //
+        }
+        
+        @Override
+        public String toString() {
+            return "CloseSessionEvent []";
+        }
+        
+    }
+
+    public class MonitoredTemplateLoader2Session implements TemplateLoaderSession {
+        
+        private boolean closed;
+
+        @Override
+        public void close() {
+            closed = true;
+            events.add(CloseSessionEvent.INSTANCE);
+        }
+
+        @Override
+        public boolean isClosed() {
+            return closed;
+        }
+        
+    }
     
-}
\ No newline at end of file
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/test/TemplateTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/test/TemplateTest.java b/src/test/java/freemarker/test/TemplateTest.java
index 5a1cdec..b1d22f6 100644
--- a/src/test/java/freemarker/test/TemplateTest.java
+++ b/src/test/java/freemarker/test/TemplateTest.java
@@ -19,12 +19,15 @@
 
 package freemarker.test;
 
-import static org.hamcrest.Matchers.*;
-import static org.junit.Assert.*;
+import static org.hamcrest.Matchers.instanceOf;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThat;
+import static org.junit.Assert.fail;
 
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.StringWriter;
+import java.nio.charset.StandardCharsets;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
@@ -33,8 +36,8 @@ import org.apache.commons.io.IOUtils;
 import org.junit.Ignore;
 
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+import freemarker.cache.ByteArrayTemplateLoader;
 import freemarker.cache.MultiTemplateLoader;
-import freemarker.cache.StringTemplateLoader;
 import freemarker.cache.TemplateLoader;
 import freemarker.core.ParseException;
 import freemarker.template.Configuration;
@@ -166,33 +169,33 @@ public abstract class TemplateTest {
     protected void addTemplate(String name, String content) {
         Configuration cfg = getConfiguration();
         TemplateLoader tl = cfg.getTemplateLoader();
-        StringTemplateLoader stl;
+        ByteArrayTemplateLoader btl;
         if (tl != null) {
-            stl = extractStringTemplateLoader(tl);
+            btl = extractByteArrayTemplateLoader(tl);
         } else {
-            stl = new StringTemplateLoader();
-            cfg.setTemplateLoader(stl);
+            btl = new ByteArrayTemplateLoader();
+            cfg.setTemplateLoader(btl);
         }
-        stl.putTemplate(name, content);
+        btl.putTemplate(name, content.getBytes(StandardCharsets.UTF_8));
     }
     
-    private StringTemplateLoader extractStringTemplateLoader(TemplateLoader tl) {
+    private ByteArrayTemplateLoader extractByteArrayTemplateLoader(TemplateLoader tl) {
         if (tl instanceof MultiTemplateLoader) {
             MultiTemplateLoader mtl = (MultiTemplateLoader) tl;
             for (int i = 0; i < mtl.getTemplateLoaderCount(); i++) {
                 TemplateLoader tli = mtl.getTemplateLoader(i);
-                if (tli instanceof StringTemplateLoader) {
-                    return (StringTemplateLoader) tli;
+                if (tli instanceof ByteArrayTemplateLoader) {
+                    return (ByteArrayTemplateLoader) tli;
                 }
             }
             throw new IllegalStateException(
-                    "The template loader was a MultiTemplateLoader that didn't contain StringTemplateLoader: "
+                    "The template loader was a MultiTemplateLoader that didn't contain ByteArrayTemplateLoader: "
                             + tl);
-        } else if (tl instanceof StringTemplateLoader) {
-            return (StringTemplateLoader) tl;
+        } else if (tl instanceof ByteArrayTemplateLoader) {
+            return (ByteArrayTemplateLoader) tl;
         } else {
             throw new IllegalStateException(
-                    "The template loader was already set to a non-StringTemplateLoader non-MultiTemplateLoader: "
+                    "The template loader was already set to a non-ByteArrayTemplateLoader non-MultiTemplateLoader: "
                             + tl);
         }
     }


[3/5] incubator-freemarker git commit: - Totally redesigned TemplateLoader interface. The FM2 TemplateLoader can't be adapted (wrapped) to it, but usually

Posted by dd...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateLookupContext.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateLookupContext.java b/src/main/java/freemarker/cache/TemplateLookupContext.java
index c605e15..72827e6 100644
--- a/src/main/java/freemarker/cache/TemplateLookupContext.java
+++ b/src/main/java/freemarker/cache/TemplateLookupContext.java
@@ -20,6 +20,7 @@
 package freemarker.cache;
 
 import java.io.IOException;
+import java.io.Serializable;
 import java.util.Locale;
 
 import freemarker.template.Configuration;
@@ -35,18 +36,25 @@ public abstract class TemplateLookupContext {
     private final String templateName;
     private final Locale templateLocale;
     private final Object customLookupCondition;
+    private final TemplateLoadingSource cachedResultSource;
+    private final Serializable cachedResultVersion;
 
     /**
      * Finds the template source based on its <em>normalized</em> name; handles {@code *} steps (so called acquisition),
-     * otherwise it just calls {@link TemplateLoader#findTemplateSource(String)}.
+     * otherwise it just calls {@link TemplateLoader#load(String, TemplateLoadingSource, Serializable,
+     * TemplateLoaderSession)}.
      * 
      * @param templateName
      *            Must be a normalized name, like {@code "foo/bar/baaz.ftl"}. A name is not normalized when, among
-     *            others, it starts with {@code /}, or contains {@code .} or {@code ..} paths steps, or it uses
-     *            backslash ({@code \}) instead of {@code /}. A normalized name might contains "*" steps.
+     *            others, it starts with {@code /}, or contains {@code .} or {@code ..} path steps, or it uses
+     *            backslash ({@code \}) instead of {@code /}. A normalized name might contains "*" path steps
+     *            (acquisition).
      * 
      * @return The result of the lookup. Not {@code null}; check {@link TemplateLookupResult#isPositive()} to see if the
-     *         lookup has found anything.
+     *         lookup has found anything. Note that in a positive result the content of the template is possibly
+     *         also already loaded (this is the case for {@link TemplateLoader}-s when the cached content is stale, but
+     *         not for {@link TemplateLoader}-s). Hence discarding a positive result and looking for another can
+     *         generate substantial extra I/O.
      */
     public abstract TemplateLookupResult lookupWithAcquisitionStrategy(String templateName) throws IOException;
 
@@ -62,10 +70,13 @@ public abstract class TemplateLookupContext {
             Locale templateLocale) throws IOException;
     
     /** Default visibility to prevent extending the class from outside this package. */
-    TemplateLookupContext(String templateName, Locale templateLocale, Object customLookupCondition) {
+    TemplateLookupContext(String templateName, Locale templateLocale, Object customLookupCondition,
+            TemplateLoadingSource cachedResultSource, Serializable cachedResultVersion) {
         this.templateName = templateName;
         this.templateLocale = templateLocale;
         this.customLookupCondition = customLookupCondition;
+        this.cachedResultSource = cachedResultSource;
+        this.cachedResultVersion = cachedResultVersion;
     }
 
     /**
@@ -103,5 +114,13 @@ public abstract class TemplateLookupContext {
     public TemplateLookupResult createNegativeLookupResult() {
         return TemplateLookupResult.createNegativeResult();
     }
+
+    TemplateLoadingSource getCachedResultSource() {
+        return cachedResultSource;
+    }
+
+    Serializable getCachedResultVersion() {
+        return cachedResultVersion;
+    }
     
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateLookupResult.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateLookupResult.java b/src/main/java/freemarker/cache/TemplateLookupResult.java
index cb7a58b..3fa29d3 100644
--- a/src/main/java/freemarker/cache/TemplateLookupResult.java
+++ b/src/main/java/freemarker/cache/TemplateLookupResult.java
@@ -37,9 +37,9 @@ public abstract class TemplateLookupResult {
     }
     
     /** Used internally to create the appropriate kind of result from the parameters. */
-    static TemplateLookupResult from(String templateSourceName, Object templateSource) {
-        return templateSource != null
-                ? new PositiveTemplateLookupResult(templateSourceName, templateSource)
+    static TemplateLookupResult from(String templateSourceName, TemplateLoadingResult templateLoaderResult) {
+        return templateLoaderResult.getStatus() != TemplateLoadingResultStatus.NOT_FOUND
+                ? new PositiveTemplateLookupResult(templateSourceName, templateLoaderResult)
                 : createNegativeResult();
     }
     
@@ -59,15 +59,15 @@ public abstract class TemplateLookupResult {
     public abstract boolean isPositive();
 
     /**
-     * Used internally to extract the {@link TemplateLoader} source; {@code null} if
-     * {@link #isPositive()} is {@code false}.
+     * Used internally to extract the {@link TemplateLoadingResult}; {@code null} if {@link #isPositive()} is
+     * {@code false}.
      */
-    abstract Object getTemplateSource();
+    abstract TemplateLoadingResult getTemplateLoaderResult();
 
     private static final class PositiveTemplateLookupResult extends TemplateLookupResult {
 
         private final String templateSourceName;
-        private final Object templateSource;
+        private final TemplateLoadingResult templateLoaderResult;
 
         /**
          * @param templateSourceName
@@ -77,20 +77,16 @@ public abstract class TemplateLookupResult {
          *            {@code "foo_de.ftl"}. Then this parameter must be {@code "foo_de.ftl"}, not {@code "foo.ftl"}. Not
          *            {@code null}.
          * 
-         * @param templateSource
-         *            See {@link TemplateLoader#findTemplateSource(String)} to understand what that means. Not
+         * @param templateLoaderResult
+         *            See {@link TemplateLoader#load} to understand what that means. Not
          *            {@code null}.
          */
-        private PositiveTemplateLookupResult(String templateSourceName, Object templateSource) {
+        private PositiveTemplateLookupResult(String templateSourceName, TemplateLoadingResult templateLoaderResult) {
             NullArgumentException.check("templateName", templateSourceName);
-            NullArgumentException.check("templateSource", templateSource);
-
-            if (templateSource instanceof TemplateLookupResult) {
-                throw new IllegalArgumentException();
-            }
+            NullArgumentException.check("templateLoaderResult", templateLoaderResult);
 
             this.templateSourceName = templateSourceName;
-            this.templateSource = templateSource;
+            this.templateLoaderResult = templateLoaderResult;
         }
 
         @Override
@@ -99,8 +95,8 @@ public abstract class TemplateLookupResult {
         }
 
         @Override
-        Object getTemplateSource() {
-            return templateSource;
+        TemplateLoadingResult getTemplateLoaderResult() {
+            return templateLoaderResult;
         }
 
         @Override
@@ -123,7 +119,7 @@ public abstract class TemplateLookupResult {
         }
 
         @Override
-        Object getTemplateSource() {
+        TemplateLoadingResult getTemplateLoaderResult() {
             return null;
         }
 

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/URLTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/URLTemplateLoader.java b/src/main/java/freemarker/cache/URLTemplateLoader.java
index e975869..bd5219c 100644
--- a/src/main/java/freemarker/cache/URLTemplateLoader.java
+++ b/src/main/java/freemarker/cache/URLTemplateLoader.java
@@ -20,29 +20,30 @@
 
 package freemarker.cache;
 
+import java.io.File;
 import java.io.IOException;
-import java.io.InputStreamReader;
-import java.io.Reader;
+import java.io.Serializable;
+import java.net.JarURLConnection;
 import java.net.URL;
 import java.net.URLConnection;
+import java.util.Objects;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import freemarker.template.Configuration;
 
 /**
  * This is an abstract template loader that can load templates whose
  * location can be described by an URL. Subclasses only need to override
- * the {@link #getURL(String)} method. Both {@link ClassTemplateLoader} and
- * {@link WebappTemplateLoader} are (quite trivial) subclasses of this class.
+ * the {@link #getURL(String)} method.
  */
+// TODO JUnit test
 public abstract class URLTemplateLoader implements TemplateLoader {
     
-    private Boolean urlConnectionUsesCaches;
+    private static final Logger LOG = LoggerFactory.getLogger("freemarker.cache");
     
-    public Object findTemplateSource(String name)
-    throws IOException {
-        URL url = getURL(name);
-        return url == null ? null : new URLTemplateSource(url, getURLConnectionUsesCaches());
-    }
+    private Boolean urlConnectionUsesCaches = false;
     
     /**
      * Given a template name (plus potential locale decorations) retrieves
@@ -54,22 +55,6 @@ public abstract class URLTemplateLoader implements TemplateLoader {
      */
     protected abstract URL getURL(String name);
     
-    public long getLastModified(Object templateSource) {
-        return ((URLTemplateSource) templateSource).lastModified();
-    }
-    
-    public Reader getReader(Object templateSource, String encoding)
-    throws IOException {
-        return new InputStreamReader(
-                ((URLTemplateSource) templateSource).getInputStream(),
-                encoding);
-    }
-    
-    public void closeTemplateSource(Object templateSource)
-    throws IOException {
-        ((URLTemplateSource) templateSource).close();
-    }
-
     /**
      * Can be used by subclasses to canonicalize URL path prefixes.
      * @param prefix the path prefix to canonicalize
@@ -98,22 +83,94 @@ public abstract class URLTemplateLoader implements TemplateLoader {
 
     /**
      * Sets if {@link URLConnection#setUseCaches(boolean)} will be called, and with what value. By default this is
-     * {@code null}; see the behavior then below. The recommended value is {@code false}, so that FreeMarker can always
-     * reliably detect when a template was changed. The default is {@code null} only for backward compatibility,
-     * and certainly will be changed to {@code false} in 2.4.0. As FreeMarker has its own template cache with its
-     * own update delay setting ({@link Configuration#setTemplateUpdateDelay(int)}), setting this to {@code false}
-     * shouldn't cause performance problems.
-     * 
-     * <p>Regarding {@code null} value: By default then {@link URLConnection#setUseCaches(boolean)} won't be called,
-     * and so the default of the {@link URLConnection} subclass will be in effect (usually {@code true}). That's the
-     * 2.3.0-compatible mode. However, if {@link Configuration#getIncompatibleImprovements()} is at least 2.3.21, then
-     * when {@code Configuration.getTemplate} is used, {@code null} will mean {@code false}. Note that this 2.3.21 trick
-     * only works if the template is loaded through {@code Configuration.getTemplate} (or {@link TemplateCache}). 
-     * 
-     * @since 2.3.21
+     * {@code false}, becase FreeMarker has its own template cache with its own update delay setting
+     * ({@link Configuration#setTemplateUpdateDelay(int)}). If this is set to {@code null},
+     * {@link URLConnection#setUseCaches(boolean)} won't be called.
      */
     public void setURLConnectionUsesCaches(Boolean urlConnectionUsesCaches) {
         this.urlConnectionUsesCaches = urlConnectionUsesCaches;
     }
+
+    @Override
+    public TemplateLoaderSession createSession() {
+        return null;
+    }
+
+    @Override
+    public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom,
+            Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws IOException {
+        URL url = getURL(name);
+        if (url == null) {
+            return TemplateLoadingResult.NOT_FOUND;             
+        }
+        
+        URLConnection conn = url.openConnection();
+        Boolean urlConnectionUsesCaches = getURLConnectionUsesCaches();
+        if (urlConnectionUsesCaches != null) {
+            conn.setUseCaches(urlConnectionUsesCaches);
+        }
+        
+        // To prevent clustering issues, getLastModified(fallbackToJarLMD=false)
+        long lmd = getLastModified(conn, false);
+        Long version = lmd != -1 ? lmd : null;
+        
+        URLTemplateLoadingSource source = new URLTemplateLoadingSource(url);
+        
+        if (ifSourceDiffersFrom != null && ifSourceDiffersFrom.equals(source)
+                && Objects.equals(ifVersionDiffersFrom, version)) {
+            return TemplateLoadingResult.NOT_MODIFIED;
+        }
+        
+        return new TemplateLoadingResult(source, version, conn.getInputStream(), null);
+    }
+
+    @Override
+    public void resetState() {
+        // Do nothing
+    }
+
+    /**
+     * {@link URLConnection#getLastModified()} with JDK bug workarounds. Because of JDK-6956385, for files inside a jar,
+     * it returns the last modification time of the jar itself, rather than the last modification time of the file
+     * inside the jar.
+     * 
+     * @param fallbackToJarLMD
+     *            Tells if the file is in side jar, then we should return the last modification time of the jar itself,
+     *            or -1 (to work around JDK-6956385).
+     */
+    public static long getLastModified(URLConnection conn, boolean fallbackToJarLMD) throws IOException {
+        if (conn instanceof JarURLConnection) {
+            // There is a bug in sun's jar url connection that causes file handle leaks when calling getLastModified()
+            // (see https://bugs.openjdk.java.net/browse/JDK-6956385).
+            // Since the time stamps of jar file contents can't vary independent from the jar file timestamp, just use
+            // the jar file timestamp
+            if (fallbackToJarLMD) {
+                URL jarURL = ((JarURLConnection) conn).getJarFileURL();
+                if (jarURL.getProtocol().equals("file")) {
+                    // Return the last modified time of the underlying file - saves some opening and closing
+                    return new File(jarURL.getFile()).lastModified();
+                } else {
+                    // Use the URL mechanism
+                    URLConnection jarConn = null;
+                    try {
+                        jarConn = jarURL.openConnection();
+                        return jarConn.getLastModified();
+                    } finally {
+                        try {
+                            if (jarConn != null) {
+                                jarConn.getInputStream().close();
+                            }
+                        } catch (IOException e) {
+                            LOG.warn("Failed to close URL connection for: {}", conn, e);
+                        }
+                    }
+                }
+            } else {
+                return -1;
+            }
+        } else {
+          return conn.getLastModified();
+        }
+    }
     
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/URLTemplateLoadingSource.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/URLTemplateLoadingSource.java b/src/main/java/freemarker/cache/URLTemplateLoadingSource.java
new file mode 100644
index 0000000..bf84bef
--- /dev/null
+++ b/src/main/java/freemarker/cache/URLTemplateLoadingSource.java
@@ -0,0 +1,56 @@
+/*
+ * 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.cache;
+
+import java.net.URL;
+
+import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+import freemarker.template.utility.NullArgumentException;
+
+@SuppressWarnings("serial")
+public class URLTemplateLoadingSource implements TemplateLoadingSource {
+
+    private final URL url;
+
+    public URLTemplateLoadingSource(URL url) {
+        NullArgumentException.check("url", url);
+        this.url = url;
+    }
+
+    public URL getUrl() {
+        return url;
+    }
+
+    @Override
+    public int hashCode() {
+        return url.hashCode();
+    }
+
+    @Override
+    @SuppressFBWarnings("EQ_CHECK_FOR_OPERAND_NOT_COMPATIBLE_WITH_THIS")
+    public boolean equals(Object obj) {
+        return url.equals(obj);
+    }
+
+    @Override
+    public String toString() {
+        return url.toString();
+    }
+    
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/URLTemplateSource.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/URLTemplateSource.java b/src/main/java/freemarker/cache/URLTemplateSource.java
deleted file mode 100644
index 716b642..0000000
--- a/src/main/java/freemarker/cache/URLTemplateSource.java
+++ /dev/null
@@ -1,144 +0,0 @@
-/*
- * 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.cache;
-
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-import java.net.JarURLConnection;
-import java.net.URL;
-import java.net.URLConnection;
-
-/**
- * Wraps a <code>java.net.URL</code>, and implements methods required for a typical template source.
- */
-class URLTemplateSource {
-    private final URL url;
-    private URLConnection conn;
-    private InputStream inputStream;
-    private Boolean useCaches;
-
-    /**
-     * @param useCaches {@code null} if this aspect wasn't set in the parent {@link TemplateLoader}.
-     */
-    URLTemplateSource(URL url, Boolean useCaches) throws IOException {
-        this.url = url;
-        this.conn = url.openConnection();
-        this.useCaches = useCaches;
-        if (useCaches != null) {
-            conn.setUseCaches(useCaches.booleanValue());
-        }
-    }
-
-    @Override
-    public boolean equals(Object o) {
-        if (o instanceof URLTemplateSource) {
-            return url.equals(((URLTemplateSource) o).url);
-        } else {
-            return false;
-        }
-    }
-
-    @Override
-    public int hashCode() {
-        return url.hashCode();
-    }
-
-    @Override
-    public String toString() {
-        return url.toString();
-    }
-    
-    long lastModified() {
-        if (conn instanceof JarURLConnection) {
-          // There is a bug in sun's jar url connection that causes file handle leaks when calling getLastModified()
-          // Since the time stamps of jar file contents can't vary independent from the jar file timestamp, just use
-          // the jar file timestamp
-          URL jarURL = ((JarURLConnection) conn).getJarFileURL();
-          if (jarURL.getProtocol().equals("file")) {
-            // Return the last modified time of the underlying file - saves some opening and closing
-            return new File(jarURL.getFile()).lastModified();
-          } else {
-            // Use the URL mechanism
-            URLConnection jarConn = null;
-            try {
-              jarConn = jarURL.openConnection();
-              return jarConn.getLastModified();
-            } catch (IOException e) {
-              return -1;
-            } finally {
-              try {
-                if (jarConn != null) jarConn.getInputStream().close();
-              } catch (IOException e) { }
-            }
-          }
-        } else {
-          long lastModified = conn.getLastModified();
-          if (lastModified == -1L && url.getProtocol().equals("file")) {
-              // Hack for obtaining accurate last modified time for
-              // URLs that point to the local file system. This is fixed
-              // in JDK 1.4, but prior JDKs returns -1 for file:// URLs.
-              return new File(url.getFile()).lastModified();
-          } else {
-              return lastModified;
-          }
-        }
-    }
-
-    InputStream getInputStream() throws IOException {
-        if (inputStream != null) {
-            // Ensure that the returned InputStream reads from the beginning of the resource when getInputStream()
-            // is called for the second time:
-            try {
-                inputStream.close();
-            } catch (IOException e) {
-                // Ignore; this is maybe because it was closed for the 2nd time now
-            }
-            this.conn = url.openConnection();
-        }
-        inputStream = conn.getInputStream();
-        return inputStream;
-    }
-
-    void close() throws IOException {
-        try {
-          if (inputStream != null) {
-              inputStream.close();
-          } else {
-              conn.getInputStream().close();
-          }
-        } finally {
-          inputStream = null;
-          conn = null;
-        }
-    }
-
-    Boolean getUseCaches() {
-        return useCaches;
-    }
-
-    void setUseCaches(boolean useCaches) {
-        if (this.conn != null) {
-            conn.setUseCaches(useCaches);
-            this.useCaches = Boolean.valueOf(useCaches);
-        }
-    }
-    
-}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/WebAppTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/WebAppTemplateLoader.java b/src/main/java/freemarker/cache/WebAppTemplateLoader.java
new file mode 100644
index 0000000..1ddaa68
--- /dev/null
+++ b/src/main/java/freemarker/cache/WebAppTemplateLoader.java
@@ -0,0 +1,296 @@
+/*
+ * 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.cache;
+
+import java.io.File;
+import java.io.FileInputStream;
+import java.io.IOException;
+import java.io.Serializable;
+import java.lang.reflect.Method;
+import java.net.MalformedURLException;
+import java.net.URL;
+import java.net.URLConnection;
+import java.util.Objects;
+
+import javax.servlet.ServletContext;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import freemarker.template.Configuration;
+import freemarker.template.utility.CollectionUtils;
+import freemarker.template.utility.NullArgumentException;
+import freemarker.template.utility.StringUtil;
+
+/**
+ * A {@link TemplateLoader} that uses streams reachable through {@link ServletContext#getResource(String)} as its source
+ * of templates.  
+ */
+public class WebAppTemplateLoader implements TemplateLoader {
+
+    private static final Logger LOG = LoggerFactory.getLogger("freemarker.cache");
+
+    private final ServletContext servletContext;
+    private final String subdirPath;
+
+    private Boolean urlConnectionUsesCaches = false;
+
+    private boolean attemptFileAccess = true;
+
+    /**
+     * Creates a template loader that will use the specified servlet context to load the resources. It will use
+     * the base path of <code>"/"</code> meaning templates will be resolved relative to the servlet context root
+     * location.
+     * 
+     * @param servletContext
+     *            the servlet context whose {@link ServletContext#getResource(String)} will be used to load the
+     *            templates.
+     */
+    public WebAppTemplateLoader(ServletContext servletContext) {
+        this(servletContext, "/");
+    }
+
+    /**
+     * Creates a template loader that will use the specified servlet context to load the resources. It will use the
+     * specified base path, which is interpreted relatively to the context root (does not mater if you start it with "/"
+     * or not). Path components should be separated by forward slashes independently of the separator character used by
+     * the underlying operating system.
+     * 
+     * @param servletContext
+     *            the servlet context whose {@link ServletContext#getResource(String)} will be used to load the
+     *            templates.
+     * @param subdirPath
+     *            the base path to template resources.
+     */
+    public WebAppTemplateLoader(ServletContext servletContext, String subdirPath) {
+        NullArgumentException.check("servletContext", servletContext);
+        NullArgumentException.check("subdirPath", subdirPath);
+
+        subdirPath = subdirPath.replace('\\', '/');
+        if (!subdirPath.endsWith("/")) {
+            subdirPath += "/";
+        }
+        if (!subdirPath.startsWith("/")) {
+            subdirPath = "/" + subdirPath;
+        }
+        this.subdirPath = subdirPath;
+        this.servletContext = servletContext;
+    }
+
+    /**
+     * Getter pair of {@link #setURLConnectionUsesCaches(Boolean)}.
+     * 
+     * @since 2.3.21
+     */
+    public Boolean getURLConnectionUsesCaches() {
+        return urlConnectionUsesCaches;
+    }
+
+    /**
+     * It does the same as {@link URLTemplateLoader#setURLConnectionUsesCaches(Boolean)}; see there.
+     * 
+     * @since 2.3.21
+     */
+    public void setURLConnectionUsesCaches(Boolean urlConnectionUsesCaches) {
+        this.urlConnectionUsesCaches = urlConnectionUsesCaches;
+    }
+
+    /**
+     * Show class name and some details that are useful in template-not-found errors.
+     * 
+     * @since 2.3.21
+     */
+    @Override
+    public String toString() {
+        return TemplateLoaderUtils.getClassNameForToString(this)
+                + "(subdirPath=" + StringUtil.jQuote(subdirPath)
+                + ", servletContext={contextPath=" + StringUtil.jQuote(getContextPath())
+                + ", displayName=" + StringUtil.jQuote(servletContext.getServletContextName()) + "})";
+    }
+
+    /** Gets the context path if we are on Servlet 2.5+, or else returns failure description string. */
+    private String getContextPath() {
+        try {
+            Method m = servletContext.getClass().getMethod("getContextPath", CollectionUtils.EMPTY_CLASS_ARRAY);
+            return (String) m.invoke(servletContext, CollectionUtils.EMPTY_OBJECT_ARRAY);
+        } catch (Throwable e) {
+            return "[can't query before Serlvet 2.5]";
+        }
+    }
+
+    /**
+     * Getter pair of {@link #setAttemptFileAccess(boolean)}.
+     * 
+     * @since 2.3.23
+     */
+    public boolean getAttemptFileAccess() {
+        return attemptFileAccess;
+    }
+
+    /**
+     * Specifies that before loading templates with {@link ServletContext#getResource(String)}, it should try to load
+     * the template as {@link File}; default is {@code true}, though it's not always recommended anymore. This is a
+     * workaround for the case when the servlet container doesn't show template modifications after the template was
+     * already loaded earlier. But it's certainly better to counter this problem by disabling the URL connection cache
+     * with {@link #setURLConnectionUsesCaches(Boolean)}, which is also the default behavior with
+     * {@link Configuration#setIncompatibleImprovements(freemarker.template.Version) incompatible_improvements} 2.3.21
+     * and later.
+     * 
+     * @since 2.3.23
+     */
+    public void setAttemptFileAccess(boolean attemptLoadingFromFile) {
+        this.attemptFileAccess = attemptLoadingFromFile;
+    }
+
+    @Override
+    public TemplateLoaderSession createSession() {
+        return null;
+    }
+
+    @Override
+    public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom,
+            Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws IOException {
+        WebAppTemplateLoadingSource source = createSource(name);
+        if (source == null) {
+            return TemplateLoadingResult.NOT_FOUND;
+        }
+        
+        if (source.url != null) {
+            URLConnection conn = source.url.openConnection();
+            Boolean urlConnectionUsesCaches = getURLConnectionUsesCaches();
+            if (urlConnectionUsesCaches != null) {
+                conn.setUseCaches(urlConnectionUsesCaches);
+            }
+            
+            // To prevent clustering issues, getLastModified(fallbackToJarLMD=false)
+            long lmd = URLTemplateLoader.getLastModified(conn, false);
+            Long version = lmd != -1 ? lmd : null;
+            
+            if (ifSourceDiffersFrom != null && ifSourceDiffersFrom.equals(source)
+                    && Objects.equals(ifVersionDiffersFrom, version)) {
+                return TemplateLoadingResult.NOT_MODIFIED;
+            }
+            
+            return new TemplateLoadingResult(source, version, conn.getInputStream(), null);
+        } else { // source.file != null
+            long lmd = source.file.lastModified();
+            Long version = lmd != -1 ? lmd : null;
+
+            if (ifSourceDiffersFrom != null && ifSourceDiffersFrom.equals(source)
+                    && Objects.equals(ifVersionDiffersFrom, version)) {
+                return TemplateLoadingResult.NOT_MODIFIED;
+            }
+            
+            return new TemplateLoadingResult(source, version, new FileInputStream(source.file), null);
+        }
+    }
+    
+    private WebAppTemplateLoadingSource createSource(String name) {
+        String fullPath = subdirPath + name;
+
+        if (attemptFileAccess) {
+            // First try to open as plain file (to bypass servlet container resource caches).
+            try {
+                String realPath = servletContext.getRealPath(fullPath);
+                if (realPath != null) {
+                    File file = new File(realPath);
+                    if (file.canRead() && file.isFile()) {
+                        return new WebAppTemplateLoadingSource(file);
+                    }
+                }
+            } catch (SecurityException e) {
+                ;// ignore
+            }
+        }
+
+        // If it fails, try to open it with servletContext.getResource.
+        URL url = null;
+        try {
+            url = servletContext.getResource(fullPath);
+        } catch (MalformedURLException e) {
+            if (LOG.isWarnEnabled()) {
+                LOG.warn("Could not retrieve resource " + StringUtil.jQuoteNoXSS(fullPath), e);
+            }
+            return null;
+        }
+        return url == null ? null : new WebAppTemplateLoadingSource(url);
+    }
+
+    @Override
+    public void resetState() {
+        // Do nothing
+    }
+    
+    @SuppressWarnings("serial")
+    private class WebAppTemplateLoadingSource implements TemplateLoadingSource {
+        private final File file;
+        private final URL url;
+        
+        WebAppTemplateLoadingSource(File file) {
+            this.file = file;
+            this.url = null;
+        }
+
+        WebAppTemplateLoadingSource(URL url) {
+            this.file = null;
+            this.url = url;
+        }
+
+        @Override
+        public int hashCode() {
+            final int prime = 31;
+            int result = 1;
+            result = prime * result + getOuterType().hashCode();
+            result = prime * result + ((file == null) ? 0 : file.hashCode());
+            result = prime * result + ((url == null) ? 0 : url.hashCode());
+            return result;
+        }
+
+        @Override
+        public boolean equals(Object obj) {
+            if (this == obj)
+                return true;
+            if (obj == null)
+                return false;
+            if (getClass() != obj.getClass())
+                return false;
+            WebAppTemplateLoadingSource other = (WebAppTemplateLoadingSource) obj;
+            if (!getOuterType().equals(other.getOuterType()))
+                return false;
+            if (file == null) {
+                if (other.file != null)
+                    return false;
+            } else if (!file.equals(other.file))
+                return false;
+            if (url == null) {
+                if (other.url != null)
+                    return false;
+            } else if (!url.equals(other.url))
+                return false;
+            return true;
+        }
+
+        private WebAppTemplateLoader getOuterType() {
+            return WebAppTemplateLoader.this;
+        }
+        
+    }
+
+}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/WebappTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/WebappTemplateLoader.java b/src/main/java/freemarker/cache/WebappTemplateLoader.java
deleted file mode 100644
index 57fb1f4..0000000
--- a/src/main/java/freemarker/cache/WebappTemplateLoader.java
+++ /dev/null
@@ -1,228 +0,0 @@
-/*
- * 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.cache;
-
-import java.io.File;
-import java.io.FileInputStream;
-import java.io.IOException;
-import java.io.InputStreamReader;
-import java.io.Reader;
-import java.lang.reflect.Method;
-import java.net.MalformedURLException;
-import java.net.URL;
-
-import javax.servlet.ServletContext;
-
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-import freemarker.template.Configuration;
-import freemarker.template.utility.CollectionUtils;
-import freemarker.template.utility.StringUtil;
-
-/**
- * A {@link TemplateLoader} that uses streams reachable through {@link ServletContext#getResource(String)} as its source
- * of templates.  
- */
-public class WebappTemplateLoader implements TemplateLoader {
-
-    private static final Logger LOG = LoggerFactory.getLogger("freemarker.cache");
-
-    private final ServletContext servletContext;
-    private final String subdirPath;
-
-    private Boolean urlConnectionUsesCaches;
-
-    private boolean attemptFileAccess = true;
-
-    /**
-     * Creates a template loader that will use the specified servlet context to load the resources. It will use
-     * the base path of <code>"/"</code> meaning templates will be resolved relative to the servlet context root
-     * location.
-     * 
-     * @param servletContext
-     *            the servlet context whose {@link ServletContext#getResource(String)} will be used to load the
-     *            templates.
-     */
-    public WebappTemplateLoader(ServletContext servletContext) {
-        this(servletContext, "/");
-    }
-
-    /**
-     * Creates a template loader that will use the specified servlet context to load the resources. It will use the
-     * specified base path, which is interpreted relatively to the context root (does not mater if you start it with "/"
-     * or not). Path components should be separated by forward slashes independently of the separator character used by
-     * the underlying operating system.
-     * 
-     * @param servletContext
-     *            the servlet context whose {@link ServletContext#getResource(String)} will be used to load the
-     *            templates.
-     * @param subdirPath
-     *            the base path to template resources.
-     */
-    public WebappTemplateLoader(ServletContext servletContext, String subdirPath) {
-        if (servletContext == null) {
-            throw new IllegalArgumentException("servletContext == null");
-        }
-        if (subdirPath == null) {
-            throw new IllegalArgumentException("path == null");
-        }
-
-        subdirPath = subdirPath.replace('\\', '/');
-        if (!subdirPath.endsWith("/")) {
-            subdirPath += "/";
-        }
-        if (!subdirPath.startsWith("/")) {
-            subdirPath = "/" + subdirPath;
-        }
-        this.subdirPath = subdirPath;
-        this.servletContext = servletContext;
-    }
-
-    @Override
-    public Object findTemplateSource(String name) throws IOException {
-        String fullPath = subdirPath + name;
-
-        if (attemptFileAccess) {
-            // First try to open as plain file (to bypass servlet container resource caches).
-            try {
-                String realPath = servletContext.getRealPath(fullPath);
-                if (realPath != null) {
-                    File file = new File(realPath);
-                    if (file.canRead() && file.isFile()) {
-                        return file;
-                    }
-                }
-            } catch (SecurityException e) {
-                ;// ignore
-            }
-        }
-
-        // If it fails, try to open it with servletContext.getResource.
-        URL url = null;
-        try {
-            url = servletContext.getResource(fullPath);
-        } catch (MalformedURLException e) {
-            if (LOG.isWarnEnabled()) {
-                LOG.warn("Could not retrieve resource " + StringUtil.jQuoteNoXSS(fullPath), e);
-            }
-            return null;
-        }
-        return url == null ? null : new URLTemplateSource(url, getURLConnectionUsesCaches());
-    }
-
-    @Override
-    public long getLastModified(Object templateSource) {
-        if (templateSource instanceof File) {
-            return ((File) templateSource).lastModified();
-        } else {
-            return ((URLTemplateSource) templateSource).lastModified();
-        }
-    }
-
-    @Override
-    public Reader getReader(Object templateSource, String encoding)
-            throws IOException {
-        if (templateSource instanceof File) {
-            return new InputStreamReader(
-                    new FileInputStream((File) templateSource),
-                    encoding);
-        } else {
-            return new InputStreamReader(
-                    ((URLTemplateSource) templateSource).getInputStream(),
-                    encoding);
-        }
-    }
-
-    @Override
-    public void closeTemplateSource(Object templateSource) throws IOException {
-        if (templateSource instanceof File) {
-            // Do nothing.
-        } else {
-            ((URLTemplateSource) templateSource).close();
-        }
-    }
-
-    /**
-     * Getter pair of {@link #setURLConnectionUsesCaches(Boolean)}.
-     * 
-     * @since 2.3.21
-     */
-    public Boolean getURLConnectionUsesCaches() {
-        return urlConnectionUsesCaches;
-    }
-
-    /**
-     * It does the same as {@link URLTemplateLoader#setURLConnectionUsesCaches(Boolean)}; see there.
-     * 
-     * @since 2.3.21
-     */
-    public void setURLConnectionUsesCaches(Boolean urlConnectionUsesCaches) {
-        this.urlConnectionUsesCaches = urlConnectionUsesCaches;
-    }
-
-    /**
-     * Show class name and some details that are useful in template-not-found errors.
-     * 
-     * @since 2.3.21
-     */
-    @Override
-    public String toString() {
-        return TemplateLoaderUtils.getClassNameForToString(this)
-                + "(subdirPath=" + StringUtil.jQuote(subdirPath)
-                + ", servletContext={contextPath=" + StringUtil.jQuote(getContextPath())
-                + ", displayName=" + StringUtil.jQuote(servletContext.getServletContextName()) + "})";
-    }
-
-    /** Gets the context path if we are on Servlet 2.5+, or else returns failure description string. */
-    private String getContextPath() {
-        try {
-            Method m = servletContext.getClass().getMethod("getContextPath", CollectionUtils.EMPTY_CLASS_ARRAY);
-            return (String) m.invoke(servletContext, CollectionUtils.EMPTY_OBJECT_ARRAY);
-        } catch (Throwable e) {
-            return "[can't query before Serlvet 2.5]";
-        }
-    }
-
-    /**
-     * Getter pair of {@link #setAttemptFileAccess(boolean)}.
-     * 
-     * @since 2.3.23
-     */
-    public boolean getAttemptFileAccess() {
-        return attemptFileAccess;
-    }
-
-    /**
-     * Specifies that before loading templates with {@link ServletContext#getResource(String)}, it should try to load
-     * the template as {@link File}; default is {@code true}, though it's not always recommended anymore. This is a
-     * workaround for the case when the servlet container doesn't show template modifications after the template was
-     * already loaded earlier. But it's certainly better to counter this problem by disabling the URL connection cache
-     * with {@link #setURLConnectionUsesCaches(Boolean)}, which is also the default behavior with
-     * {@link Configuration#setIncompatibleImprovements(freemarker.template.Version) incompatible_improvements} 2.3.21
-     * and later.
-     * 
-     * @since 2.3.23
-     */
-    public void setAttemptFileAccess(boolean attemptLoadingFromFile) {
-        this.attemptFileAccess = attemptLoadingFromFile;
-    }
-
-}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/core/BuiltInsForStringsMisc.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/BuiltInsForStringsMisc.java b/src/main/java/freemarker/core/BuiltInsForStringsMisc.java
index 1b67eed..4d7634b 100644
--- a/src/main/java/freemarker/core/BuiltInsForStringsMisc.java
+++ b/src/main/java/freemarker/core/BuiltInsForStringsMisc.java
@@ -80,7 +80,7 @@ class BuiltInsForStringsMisc {
                     }
                     
                     FMParser parser = new FMParser(
-                            parentTemplate, false, tkMan, pCfg);
+                            parentTemplate, false, tkMan, pCfg, TemplateSpecifiedEncodingHandler.DEFAULT);
                     
                     exp = parser.Expression();
                 } catch (TokenMgrError e) {

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/core/Configurable.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/Configurable.java b/src/main/java/freemarker/core/Configurable.java
index 5dc7c49..b5486ee 100644
--- a/src/main/java/freemarker/core/Configurable.java
+++ b/src/main/java/freemarker/core/Configurable.java
@@ -2145,7 +2145,7 @@ public class Configurable {
      *   <li><p>{@code "template_loader"}:
      *       See: {@link Configuration#setTemplateLoader(TemplateLoader)}.
      *       <br>String value: {@code "default"} (case insensitive) for the default, or else interpreted as an
-     *       <a href="#fm_obe">object builder expression</a>.
+     *       <a href="#fm_obe">object builder expression</a>. {@code "null"} is also allowed.
      *       
      *   <li><p>{@code "template_lookup_strategy"}:
      *       See: {@link Configuration#setTemplateLookupStrategy(freemarker.cache.TemplateLookupStrategy)}.

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/core/Environment.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/Environment.java b/src/main/java/freemarker/core/Environment.java
index 740a9a9..7e61587 100644
--- a/src/main/java/freemarker/core/Environment.java
+++ b/src/main/java/freemarker/core/Environment.java
@@ -2416,7 +2416,7 @@ public final class Environment extends Configurable {
     }
 
     /**
-     * Emulates <code>include</code> directive, except that <code>name</code> must be tempate root relative.
+     * Emulates <code>include</code> directive, except that <code>name</code> must be template root relative.
      *
      * <p>
      * It's the same as <code>include(getTemplateForInclusion(name, encoding, parse))</code>. But, you may want to
@@ -2488,7 +2488,7 @@ public final class Environment extends Configurable {
 
     private String getIncludedTemplateEncoding() {
         String encoding;
-        // This branch shouldn't exist, as it doesn't make much sense to inherit encoding. But we have to keep BC.
+        // [FM3] This branch shouldn't exist, as it doesn't make much sense to inherit encoding. But we have to keep BC.
         encoding = getTemplate().getEncoding();
         if (encoding == null) {
             encoding = configuration.getEncoding(this.getLocale());

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/core/MarkReleaserTemplateSpecifiedEncodingHandler.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/MarkReleaserTemplateSpecifiedEncodingHandler.java b/src/main/java/freemarker/core/MarkReleaserTemplateSpecifiedEncodingHandler.java
new file mode 100644
index 0000000..9fb8050
--- /dev/null
+++ b/src/main/java/freemarker/core/MarkReleaserTemplateSpecifiedEncodingHandler.java
@@ -0,0 +1,55 @@
+/*
+ * 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.core;
+
+import java.io.InputStream;
+
+import freemarker.template.Template.WrongEncodingException;
+
+/**
+ * A {@link TemplateSpecifiedEncodingHandler} that discards the mark of the specified {@link InputStream} when
+ * the template parsing gets to a point where it's known that we can't receive a template specified encoding anymore.
+ * This allows freeing up the mark buffer early during parsing.
+ * 
+ * @since 2.3.16
+ */
+public class MarkReleaserTemplateSpecifiedEncodingHandler implements TemplateSpecifiedEncodingHandler {
+
+    private final InputStream markedInputStream;
+
+    /**
+     * @param markedInputStream Input stream with marked template content start position
+     */
+    public MarkReleaserTemplateSpecifiedEncodingHandler(InputStream markedInputStream) {
+        this.markedInputStream = markedInputStream;
+    }
+
+    public void handle(String templateSpecificEncoding, String constructorSpecifiedEncoding)
+            throws WrongEncodingException {
+        TemplateSpecifiedEncodingHandler.DEFAULT.handle(templateSpecificEncoding, constructorSpecifiedEncoding);
+        
+        // There was no WrongEncodingException exception, release mark buffer:
+        markedInputStream.mark(0); // 
+    }
+
+    public InputStream getMarkedInputStream() {
+        return markedInputStream;
+    }
+
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/core/StringLiteral.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/StringLiteral.java b/src/main/java/freemarker/core/StringLiteral.java
index da1c1bd..a81f726 100644
--- a/src/main/java/freemarker/core/StringLiteral.java
+++ b/src/main/java/freemarker/core/StringLiteral.java
@@ -63,7 +63,8 @@ final class StringLiteral extends Expression implements TemplateScalarModel {
                 FMParserTokenManager tkMan = new FMParserTokenManager(
                         simpleCharacterStream);
                 
-                FMParser parser = new FMParser(parentTemplate, false, tkMan, pcfg);
+                FMParser parser = new FMParser(parentTemplate, false, tkMan, pcfg,
+                        TemplateSpecifiedEncodingHandler.DEFAULT);
                 // We continue from the parent parser's current state:
                 parser.setupStringLiteralMode(parentTkMan, outputFormat);
                 try {
@@ -129,6 +130,7 @@ final class StringLiteral extends Expression implements TemplateScalarModel {
         }
     }
 
+    @Override
     public String getAsString() {
         return value;
     }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/core/TemplateConfiguration.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/TemplateConfiguration.java b/src/main/java/freemarker/core/TemplateConfiguration.java
index 353d453..019f547 100644
--- a/src/main/java/freemarker/core/TemplateConfiguration.java
+++ b/src/main/java/freemarker/core/TemplateConfiguration.java
@@ -49,7 +49,7 @@ import freemarker.template.utility.NullArgumentException;
  * <p>
  * Note that the result value of the reader methods (getter and "is" methods) is usually not useful unless the value of
  * that setting was already set on this object. Otherwise you will get the value from the parent {@link Configuration},
- * which is {@link Configuration#getDefaultConfiguration()} before this object is associated to a {@link Configuration}.
+ * or an {@link IllegalStateException} before this object is associated to a {@link Configuration}.
  * 
  * <p>
  * If you are using this class for your own template loading and caching solution, rather than with the standard one,
@@ -146,6 +146,11 @@ public final class TemplateConfiguration extends Configurable implements ParserC
     public Configuration getParentConfiguration() {
         return parentConfigurationSet ? (Configuration) getParent() : null;
     }
+
+    private Configuration getNonNullParentConfiguration() {
+        checkParentConfigurationSet();
+        return (Configuration) getParent();
+    }
     
     /**
      * Set all settings in this {@link TemplateConfiguration} that were set in the parameter
@@ -271,8 +276,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
      *             If the parent configuration wasn't yet set.
      */
     public void apply(Template template) {
-        checkParentConfigurationSet();
-        Configuration cfg = getParentConfiguration();
+        Configuration cfg = getNonNullParentConfiguration();
         if (template.getConfiguration() != cfg) {
             // This is actually not a problem right now, but for future BC we enforce this.
             throw new IllegalArgumentException(
@@ -377,7 +381,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
      */
     @Override
     public int getTagSyntax() {
-        return tagSyntax != null ? tagSyntax.intValue() : getParentConfiguration().getTagSyntax();
+        return tagSyntax != null ? tagSyntax.intValue() : getNonNullParentConfiguration().getTagSyntax();
     }
 
     /**
@@ -400,7 +404,8 @@ public final class TemplateConfiguration extends Configurable implements ParserC
      */
     @Override
     public int getNamingConvention() {
-        return namingConvention != null ? namingConvention.intValue() : getParentConfiguration().getNamingConvention();
+        return namingConvention != null ? namingConvention.intValue()
+                : getNonNullParentConfiguration().getNamingConvention();
     }
 
     /**
@@ -423,7 +428,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
     @Override
     public boolean getWhitespaceStripping() {
         return whitespaceStripping != null ? whitespaceStripping.booleanValue()
-                : getParentConfiguration().getWhitespaceStripping();
+                : getNonNullParentConfiguration().getWhitespaceStripping();
     }
 
     /**
@@ -447,7 +452,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
     @Override
     public int getAutoEscapingPolicy() {
         return autoEscapingPolicy != null ? autoEscapingPolicy.intValue()
-                : getParentConfiguration().getAutoEscapingPolicy();
+                : getNonNullParentConfiguration().getAutoEscapingPolicy();
     }
 
     /**
@@ -470,7 +475,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
      */
     @Override
     public OutputFormat getOutputFormat() {
-        return outputFormat != null ? outputFormat : getParentConfiguration().getOutputFormat();
+        return outputFormat != null ? outputFormat : getNonNullParentConfiguration().getOutputFormat();
     }
 
     /**
@@ -493,7 +498,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
     @Override
     public boolean getRecognizeStandardFileExtensions() {
         return recognizeStandardFileExtensions != null ? recognizeStandardFileExtensions.booleanValue()
-                : getParentConfiguration().getRecognizeStandardFileExtensions();
+                : getNonNullParentConfiguration().getRecognizeStandardFileExtensions();
     }
     
     /**
@@ -502,7 +507,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
     public boolean isRecognizeStandardFileExtensionsSet() {
         return recognizeStandardFileExtensions != null;
     }
-
+    
     @Override
     public void setStrictBeanModels(boolean strict) {
         throw new UnsupportedOperationException(
@@ -510,7 +515,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
     }
 
     public String getEncoding() {
-        return encoding != null ? encoding : getParentConfiguration().getDefaultEncoding();
+        return encoding != null ? encoding : getNonNullParentConfiguration().getDefaultEncoding();
     }
 
     /**
@@ -552,7 +557,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
     @Override
     public int getTabSize() {
         return tabSize != null ? tabSize.intValue()
-                : getParentConfiguration().getTabSize();
+                : getNonNullParentConfiguration().getTabSize();
     }
     
     /**
@@ -573,8 +578,7 @@ public final class TemplateConfiguration extends Configurable implements ParserC
      */
     @Override
     public Version getIncompatibleImprovements() {
-        checkParentConfigurationSet();
-        return getParentConfiguration().getIncompatibleImprovements();
+        return getNonNullParentConfiguration().getIncompatibleImprovements();
     }
 
     private void checkParentConfigurationSet() {

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/core/TemplateSpecifiedEncodingHandler.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/TemplateSpecifiedEncodingHandler.java b/src/main/java/freemarker/core/TemplateSpecifiedEncodingHandler.java
new file mode 100644
index 0000000..2c3f0bf
--- /dev/null
+++ b/src/main/java/freemarker/core/TemplateSpecifiedEncodingHandler.java
@@ -0,0 +1,61 @@
+/*
+ * 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.core;
+
+import freemarker.template.Template;
+import freemarker.template.Template.WrongEncodingException;
+
+/**
+ * Specifies the behavior when the template specifies its own encoding (via {@code <#ftl encoding=...>}) in the template
+ * content itself, and also when it doesn't do that.
+ */
+public interface TemplateSpecifiedEncodingHandler {
+    
+    TemplateSpecifiedEncodingHandler DEFAULT = new TemplateSpecifiedEncodingHandler() {
+
+        @Override
+        public void handle(String templateSpecificEncoding, String constructorSpecifiedEncoding)
+                throws WrongEncodingException {
+            if (constructorSpecifiedEncoding != null && templateSpecificEncoding != null
+                    && !constructorSpecifiedEncoding.equalsIgnoreCase(templateSpecificEncoding)) {
+                throw new Template.WrongEncodingException(templateSpecificEncoding, constructorSpecifiedEncoding);
+            }
+        }
+        
+    };
+
+    /**
+     * Called once during template parsing, either when the {@code #ftl} directive is processed, or near the beginning
+     * of the template processing when there's no {@code #ftl} directive in the template.
+     * 
+     * @param templateSpecificEncoding
+     *            The encoding specified via {@code <#ftl encoding=...>}, or {@code null} if that was missing (either
+     *            the {@code encoding} parameter or the whole {@code #ftl} directive).
+     * @param constructorSpecifiedEncoding
+     *            The encoding specified to the {@link Template} constructor; also the value of
+     *            {@link Template#getEncoding()}. If there was an encoding used for decoding the template file, it
+     *            should be that, or if there was no encoding, it should be {@code null}.
+     * 
+     * @throws WrongEncodingException
+     *             If the template "file" has to be re-read and the {@link Template} re-created with the encoding
+     *             specified in the constructor of {@link WrongEncodingException}.
+     */
+    void handle(String templateSpecificEncoding, String constructorSpecifiedEncoding) throws WrongEncodingException;
+    
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/core/_CoreAPI.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/core/_CoreAPI.java b/src/main/java/freemarker/core/_CoreAPI.java
index 56a81b6..9f75ac5 100644
--- a/src/main/java/freemarker/core/_CoreAPI.java
+++ b/src/main/java/freemarker/core/_CoreAPI.java
@@ -215,8 +215,9 @@ public class _CoreAPI {
         return te.getChild(index);
     }
     
-    public static FMParser newFMParser(Template template, Reader reader, ParserConfiguration pCfg) {
-        return new FMParser(template, reader, pCfg);
+    public static FMParser newFMParser(Template template, Reader reader, ParserConfiguration pCfg,
+            TemplateSpecifiedEncodingHandler templateSpecifiedEncodingHandler) {
+        return new FMParser(template, reader, pCfg, templateSpecifiedEncodingHandler);
     }
     
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java b/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
index ea78ac4..cf15f02 100644
--- a/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
+++ b/src/main/java/freemarker/ext/servlet/FreemarkerServlet.java
@@ -22,6 +22,7 @@ package freemarker.ext.servlet;
 import java.io.IOException;
 import java.io.Writer;
 import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
 import java.util.ArrayList;
@@ -48,7 +49,7 @@ import freemarker.cache.ClassTemplateLoader;
 import freemarker.cache.FileTemplateLoader;
 import freemarker.cache.MultiTemplateLoader;
 import freemarker.cache.TemplateLoader;
-import freemarker.cache.WebappTemplateLoader;
+import freemarker.cache.WebAppTemplateLoader;
 import freemarker.core.Configurable;
 import freemarker.core.Environment;
 import freemarker.core.OutputFormat;
@@ -129,8 +130,8 @@ import freemarker.template.utility.StringUtil;
  * Any of the above can have a {@code ?setting(name=value, ...)} postfix to set the JavaBeans properties of the
  * {@link TemplateLoader} created. For example,
  * {@code /templates?settings(attemptFileAccess=false, URLConnectionUsesCaches=true)} calls
- * {@link WebappTemplateLoader#setAttemptFileAccess(boolean)} and
- * {@link WebappTemplateLoader#setURLConnectionUsesCaches(Boolean)} to tune the {@link WebappTemplateLoader}. For
+ * {@link WebAppTemplateLoader#setAttemptFileAccess(boolean)} and
+ * {@link WebAppTemplateLoader#setURLConnectionUsesCaches(Boolean)} to tune the {@link WebAppTemplateLoader}. For
  * backward compatibility (not recommended!), you can use the {@code class://} prefix, like in
  * <tt>class://com/example/templates</tt> format, which is similar to {@code classpath:}, except that it uses the
  * defining class loader of this servlet's class. This can cause template-not-found errors, if that class (in
@@ -206,8 +207,9 @@ import freemarker.template.utility.StringUtil;
  * <li>{@value #INIT_PARAM_VALUE_FROM_TEMPLATE}: This should be used in most applications, but it's not the default for
  * backward compatibility. It reads the {@link Configurable#getOutputEncoding()} setting of the template (note that the
  * template usually just inherits that from the {@link Configuration}), and if that's not set, then reads the source
- * charset of the template, just like {@value #INIT_PARAM_VALUE_LEGACY}. Then it passes the charset acquired this way to
- * {@link HttpServletResponse#setCharacterEncoding(String)} and {@link Environment#setOutputEncoding(String)}. (It
+ * charset of the template, just like {@value #INIT_PARAM_VALUE_LEGACY}, and if that's {@code null} (which happens if
+ * the template was loaded from a non-binary source) then it will be UTF-8. Then it passes the charset acquired this way
+ * to {@link HttpServletResponse#setCharacterEncoding(String)} and {@link Environment#setOutputEncoding(String)}. (It
  * doesn't call the legacy {@link HttpServletResponse#setContentType(String)} API to set the charset.) (Note that if the
  * template has a {@code content_type} template attribute (which is deprecated) that specifies a charset, it will be
  * used as the output charset of that template.)
@@ -747,7 +749,7 @@ public class FreemarkerServlet extends HttpServlet {
     /**
      * Create the template loader. The default implementation will create a {@link ClassTemplateLoader} if the template
      * path starts with {@code "class://"}, a {@link FileTemplateLoader} if the template path starts with
-     * {@code "file://"}, and a {@link WebappTemplateLoader} otherwise. Also, if
+     * {@code "file://"}, and a {@link WebAppTemplateLoader} otherwise. Also, if
      * {@link Configuration#Configuration(freemarker.template.Version) incompatible_improvements} is 2.3.22 or higher,
      * it will create a {@link MultiTemplateLoader} if the template path starts with {@code "["}.
      * 
@@ -839,7 +841,7 @@ public class FreemarkerServlet extends HttpServlet {
                 if (responseCharacterEncoding == ResponseCharacterEncoding.LEGACY && !contentType.containsCharset) {
                     // In legacy mode we don't call response.setCharacterEncoding, so the charset must be set here:
                     response.setContentType(
-                            contentType.httpHeaderValue + "; charset=" + getTemplateSpecificOutputEncoding(template));
+                            contentType.httpHeaderValue + "; charset=" + getOutputEncodingForTemplate(template));
                 } else {
                     response.setContentType(contentType.httpHeaderValue);
                 }
@@ -851,7 +853,7 @@ public class FreemarkerServlet extends HttpServlet {
             // Using the Servlet 2.4 way of setting character encoding.
             if (responseCharacterEncoding != ResponseCharacterEncoding.FORCE_CHARSET) {
                 if (!tempSpecContentTypeContainsCharset) {
-                    response.setCharacterEncoding(getTemplateSpecificOutputEncoding(template));
+                    response.setCharacterEncoding(getOutputEncodingForTemplate(template));
                 }
             } else {
                 response.setCharacterEncoding(forcedResponseCharacterEncoding.name());
@@ -911,10 +913,13 @@ public class FreemarkerServlet extends HttpServlet {
         env.process();
     }
 
-    private String getTemplateSpecificOutputEncoding(Template template) {
+    private String getOutputEncodingForTemplate(Template template) {
         String outputEncoding = responseCharacterEncoding == ResponseCharacterEncoding.LEGACY ? null
                 : template.getOutputEncoding();
-        return outputEncoding != null ? outputEncoding : template.getEncoding();
+        // [FM3] Don't use template.getEncoding() here; it might can't encode the dynamic values inserted.
+        return outputEncoding != null ? outputEncoding
+                : template.getEncoding() != null ? template.getEncoding()
+                : StandardCharsets.UTF_8.name();
     }
 
     private ContentType getTemplateSpecificContentType(final Template template) {
@@ -928,7 +933,9 @@ public class FreemarkerServlet extends HttpServlet {
         if (outputFormatMimeType != null) {
             if (responseCharacterEncoding == ResponseCharacterEncoding.LEGACY) {
                 // In legacy mode we won't call serlvetResponse.setCharacterEncoding(...), so:
-                return new ContentType(outputFormatMimeType + "; charset=" + getTemplateSpecificOutputEncoding(template), true);
+                return new ContentType(
+                        outputFormatMimeType + "; charset=" + getOutputEncodingForTemplate(template),
+                        true);
             } else {
                 return new ContentType(outputFormatMimeType, false);
             }
@@ -1630,6 +1637,7 @@ public class FreemarkerServlet extends HttpServlet {
     }
     
     private enum ResponseCharacterEncoding implements InitParamValueEnum {
+        // [FM3] Get rid of LEGACY
         LEGACY(INIT_PARAM_VALUE_LEGACY),
         FROM_TEMPLATE(INIT_PARAM_VALUE_FROM_TEMPLATE),
         DO_NOT_SET(INIT_PARAM_VALUE_DO_NOT_SET),

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/ext/servlet/InitParamParser.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/ext/servlet/InitParamParser.java b/src/main/java/freemarker/ext/servlet/InitParamParser.java
index c7c4f98..feb5b98 100644
--- a/src/main/java/freemarker/ext/servlet/InitParamParser.java
+++ b/src/main/java/freemarker/ext/servlet/InitParamParser.java
@@ -34,7 +34,7 @@ import freemarker.cache.ClassTemplateLoader;
 import freemarker.cache.FileTemplateLoader;
 import freemarker.cache.MultiTemplateLoader;
 import freemarker.cache.TemplateLoader;
-import freemarker.cache.WebappTemplateLoader;
+import freemarker.cache.WebAppTemplateLoader;
 import freemarker.core._ObjectBuilderSettingEvaluator;
 import freemarker.core._SettingEvaluationEnvironment;
 import freemarker.template.Configuration;
@@ -101,7 +101,7 @@ final class InitParamParser {
                 && cfg.getIncompatibleImprovements().intValue() >= _TemplateAPI.VERSION_INT_2_3_22) {
             throw new TemplatePathParsingException("Template paths starting with \"{\" are reseved for future purposes");
         } else {
-            templateLoader = new WebappTemplateLoader(srvCtx, pureTemplatePath);
+            templateLoader = new WebAppTemplateLoader(srvCtx, pureTemplatePath);
         }
         
         if (settingAssignmentsStart != -1) {

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/template/Configuration.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/Configuration.java b/src/main/java/freemarker/template/Configuration.java
index ea188dd..b2f9b0e 100644
--- a/src/main/java/freemarker/template/Configuration.java
+++ b/src/main/java/freemarker/template/Configuration.java
@@ -845,7 +845,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
     
     private void createTemplateCache() {
         cache = new TemplateCache(
-                getDefaultTemplateLoader(),
+                null,
                 getDefaultCacheStorage(),
                 getDefaultTemplateLookupStrategy(),
                 getDefaultTemplateNameFormat(),
@@ -862,7 +862,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
         TemplateCache oldCache = cache;
         cache = new TemplateCache(
                 loader, storage, templateLookupStrategy, templateNameFormat, templateConfigurations, this);
-        cache.clear(); // for fully BC behavior
+        cache.clear(false);
         cache.setDelay(oldCache.getDelay());
         cache.setLocalizedLookup(localizedLookup);
     }
@@ -873,41 +873,6 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
                 getTemplateConfigurations());
     }
     
-    private TemplateLoader getDefaultTemplateLoader() {
-        return createDefaultTemplateLoader(getIncompatibleImprovements(), getTemplateLoader());
-    }
-
-    static TemplateLoader createDefaultTemplateLoader(Version incompatibleImprovements) {
-        return createDefaultTemplateLoader(incompatibleImprovements, null);
-    }
-    
-    private static TemplateLoader createDefaultTemplateLoader(
-            Version incompatibleImprovements, TemplateLoader existingTemplateLoader) {
-        if (incompatibleImprovements.intValue() < _TemplateAPI.VERSION_INT_2_3_21) {
-            if (existingTemplateLoader instanceof LegacyDefaultFileTemplateLoader) {
-                return existingTemplateLoader;
-            }
-            try {
-                return new LegacyDefaultFileTemplateLoader();
-            } catch (Exception e) {
-                LOG.warn("Couldn't create legacy default TemplateLoader which accesses the current directory. "
-                        + "(Use new Configuration(Configuration.VERSION_2_3_21) or higher to avoid this.)", e);
-                return null;
-            }
-        } else {
-            return null;
-        }
-    }
-    
-    // [FM3] Remove
-    private static class LegacyDefaultFileTemplateLoader extends FileTemplateLoader {
-
-        public LegacyDefaultFileTemplateLoader() throws IOException {
-            super();
-        }
-        
-    }
-    
     private TemplateLookupStrategy getDefaultTemplateLookupStrategy() {
         return getDefaultTemplateLookupStrategy(getIncompatibleImprovements());
     }
@@ -1179,7 +1144,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
      */
     public void unsetTemplateLoader() {
         if (templateLoaderExplicitlySet) {
-            setTemplateLoader(getDefaultTemplateLoader());
+            setTemplateLoader(null);
             templateLoaderExplicitlySet = false;
         }
     }
@@ -1425,9 +1390,9 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
 
     /**
      * Sets the servlet context from which to load templates.
-     * This is equivalent to {@code setTemplateLoader(new WebappTemplateLoader(sctxt, path))}
-     * or {@code setTemplateLoader(new WebappTemplateLoader(sctxt))} if {@code path} was
-     * {@code null}, so see {@code freemarker.cache.WebappTemplateLoader} for more details.
+     * This is equivalent to {@code setTemplateLoader(new WebAppTemplateLoader(sctxt, path))}
+     * or {@code setTemplateLoader(new WebAppTemplateLoader(sctxt))} if {@code path} was
+     * {@code null}, so see {@code freemarker.cache.WebAppTemplateLoader} for more details.
      * 
      * @param servletContext the {@code javax.servlet.ServletContext} object. (The declared type is {@link Object}
      *        to prevent class loading error when using FreeMarker in an environment where
@@ -1439,7 +1404,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
     public void setServletContextForTemplateLoading(Object servletContext, String path) {
         try {
             // Don't introduce linking-time dependency on servlets
-            final Class webappTemplateLoaderClass = ClassUtil.forName("freemarker.cache.WebappTemplateLoader");
+            final Class webappTemplateLoaderClass = ClassUtil.forName("freemarker.cache.WebAppTemplateLoader");
             
             // Don't introduce linking-time dependency on servlets
             final Class servletContextClass = ClassUtil.forName("javax.servlet.ServletContext");
@@ -2943,7 +2908,7 @@ public class Configuration extends Configurable implements Cloneable, ParserConf
                     unsetTemplateLoader();
                 } else {
                     setTemplateLoader((TemplateLoader) _ObjectBuilderSettingEvaluator.eval(
-                            value, TemplateLoader.class, false, _SettingEvaluationEnvironment.getCurrent()));
+                            value, TemplateLoader.class, true, _SettingEvaluationEnvironment.getCurrent()));
                 }
             } else if (TEMPLATE_LOOKUP_STRATEGY_KEY_SNAKE_CASE.equals(name)
                     || TEMPLATE_LOOKUP_STRATEGY_KEY_CAMEL_CASE.equals(name)) {

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/template/Template.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/Template.java b/src/main/java/freemarker/template/Template.java
index 31149f9..ac9bde2 100644
--- a/src/main/java/freemarker/template/Template.java
+++ b/src/main/java/freemarker/template/Template.java
@@ -50,10 +50,12 @@ import freemarker.core.ParseException;
 import freemarker.core.ParserConfiguration;
 import freemarker.core.TemplateConfiguration;
 import freemarker.core.TemplateElement;
+import freemarker.core.TemplateSpecifiedEncodingHandler;
 import freemarker.core.TextBlock;
 import freemarker.core.TokenMgrError;
 import freemarker.core._CoreAPI;
 import freemarker.debug.impl.DebuggerService;
+import freemarker.template.utility.NullArgumentException;
 
 /**
  * <p>
@@ -136,11 +138,7 @@ public class Template extends Configurable {
     /**
      * Convenience constructor for {@link #Template(String, String, Reader, Configuration, String) Template(name, null,
      * reader, cfg, encoding)}.
-     * 
-     * @deprecated In most applications, use {@link #Template(String, Reader, Configuration)} instead, which doesn't
-     *             specify the encoding.
      */
-    @Deprecated
     public Template(String name, Reader reader, Configuration cfg, String encoding) throws IOException {
         this(name, null, reader, cfg, encoding);
     }
@@ -168,7 +166,9 @@ public class Template extends Configurable {
      *            See {@link #getSourceName()} for the meaning. Can be {@code null}, in which case
      *            {@link #getSourceName()} will return the same as {@link #getName()}.
      * @param reader
-     *            The character stream to read from. It will always be closed ({@link Reader#close()}) by this method.
+     *            The character stream to read from. The {@link Reader} is <em>not</em> closed by this method (unlike
+     *            in FreeMarker 2.x.x), so be sure that it's closed somewhere. (Except of course, readers like
+     *            {@link StringReader} need not be closed.)
      * @param cfg
      *            The Configuration object that this Template is associated with. If this is {@code null}, the "default"
      *            {@link Configuration} object is used, which is highly discouraged, because it can easily lead to
@@ -186,20 +186,17 @@ public class Template extends Configurable {
      * recommended).
      *
      * @param encoding
-     *            This is the encoding that we are supposed to be using. But it's not really necessary because we have a
-     *            {@link Reader} which is already decoded, but it's kept as meta-info. It also has an impact when
-     *            {@code #include}-ing/{@code #import}-ing another template from this template, as its default encoding
-     *            will be this. But this behavior of said directives is considered to be harmful, and will be probably
-     *            phased out. Until that, it's better to leave this on {@code null}, so that the encoding will come from
-     *            the {@link Configuration}. Note that if this is non-{@code null} and there's an {@code #ftl} header
-     *            with encoding, they must match, or else a {@link WrongEncodingException} is thrown.
-     * 
-     * @deprecated In most applications, use {@link #Template(String, String, Reader, Configuration)} instead, which
-     *             doesn't specify the encoding.
+     *            This is the encoding that we are supposed to be using. At the first glance it's unnecessary because we
+     *            already have a {@link Reader} (so decoding with the charset has already happened), however, if this is
+     *            non-{@code null} and there's an {@code #ftl} header with {@code encoding} parameter, they must match,
+     *            or else a {@link WrongEncodingException} is thrown. Thus, it should be set if to decode the template,
+     *            we were using an encoding (a charset), otherwise it should be {@code null}. It's also kept as
+     *            meta-info (returned by {@link #getEncoding()}). It also has an impact when {@code #include}-ing or
+     *            {@code #import}-ing another template from this template, as its default encoding will be this. But
+     *            this behavior of said directives is considered to be harmful, and will be probably phased out.
      * 
      * @since 2.3.22
      */
-   @Deprecated
    public Template(
            String name, String sourceName, Reader reader, Configuration cfg, String encoding) throws IOException {
        this(name, sourceName, reader, cfg, null, encoding);
@@ -223,18 +220,35 @@ public class Template extends Configurable {
      *            {@link Configurable} settings will be set too, because this constructor only uses it as a
      *            {@link ParserConfiguration}.
      * @param encoding
-     *            Same as in {@link #Template(String, String, Reader, Configuration, String)}. When it's non-{@code
-     *            null}, it overrides the value coming from the {@link TemplateConfiguration#getEncoding()} method of
-     *            the {@code templateConfiguration} parameter.
+     *            Same as in {@link #Template(String, String, Reader, Configuration, String)}.
      * 
      * @since 2.3.24
      */
-    public Template(
-            String name, String sourceName, Reader reader,
-            Configuration cfg, ParserConfiguration customParserConfiguration,
-            String encoding) throws IOException {
+   public Template(
+           String name, String sourceName, Reader reader,
+           Configuration cfg, ParserConfiguration customParserConfiguration,
+           String encoding) throws IOException {
+       this(name, sourceName, reader, cfg, customParserConfiguration, encoding,
+               TemplateSpecifiedEncodingHandler.DEFAULT);
+    }
+   
+   /**
+    * Same as {@link #Template(String, String, Reader, Configuration, ParserConfiguration, String)}, but allows
+    * specifying a non-default (non-{@link TemplateSpecifiedEncodingHandler#DEFAULT}) behavior regarding encoding
+    * specified in the template content.
+    *  
+    * @param templateSpecifiedEncodingHandler Not {@code null}.
+    * 
+    * @since 2.3.26
+    */
+   public Template(
+           String name, String sourceName, Reader reader,
+           Configuration cfg, ParserConfiguration customParserConfiguration,
+           String encoding, TemplateSpecifiedEncodingHandler templateSpecifiedEncodingHandler) throws IOException {
         this(name, sourceName, cfg, customParserConfiguration);
-        
+       
+        NullArgumentException.check("templateSpecifiedEncodingHandler", templateSpecifiedEncodingHandler);
+       
         this.setEncoding(encoding);
         LineTableBuilder ltbReader;
         try {
@@ -247,7 +261,8 @@ public class Template extends Configurable {
             reader = ltbReader;
             
             try {
-                parser = _CoreAPI.newFMParser(this, reader, actualParserConfiguration);
+                parser = _CoreAPI.newFMParser(
+                        this, reader, actualParserConfiguration, templateSpecifiedEncodingHandler);
                 try {
                     this.rootElement = parser.Root();
                 } catch (IndexOutOfBoundsException exc) {
@@ -271,8 +286,6 @@ public class Template extends Configurable {
         } catch (ParseException e) {
             e.setTemplateName(getSourceName());
             throw e;
-        } finally {
-            reader.close();
         }
         
         // Throws any exception that JavaCC has silently treated as EOF:
@@ -606,7 +619,8 @@ public class Template extends Configurable {
     }
 
     /**
-     * Returns the default character encoding used for reading included files.
+     * Returns the default character encoding used for reading included/imported files; if {@code null}, then
+     * the encoding returned by {@link Configuration#getEncoding(java.util.Locale)} should be used instead.
      */
     public String getEncoding() {
         return this.encoding;

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/template/_TemplateAPI.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/template/_TemplateAPI.java b/src/main/java/freemarker/template/_TemplateAPI.java
index 52606f6..bf6b227 100644
--- a/src/main/java/freemarker/template/_TemplateAPI.java
+++ b/src/main/java/freemarker/template/_TemplateAPI.java
@@ -22,7 +22,6 @@ package freemarker.template;
 import java.util.Set;
 
 import freemarker.cache.CacheStorage;
-import freemarker.cache.TemplateLoader;
 import freemarker.cache.TemplateLookupStrategy;
 import freemarker.cache.TemplateNameFormat;
 import freemarker.core.Expression;
@@ -83,10 +82,6 @@ public class _TemplateAPI {
         return Configuration.getDefaultLogTemplateExceptions(incompatibleImprovements);
     }
 
-    public static TemplateLoader createDefaultTemplateLoader(Version incompatibleImprovements) {
-        return Configuration.createDefaultTemplateLoader(incompatibleImprovements);
-    }
-
     public static CacheStorage createDefaultCacheStorage(Version incompatibleImprovements) {
         return Configuration.createDefaultCacheStorage(incompatibleImprovements);
     }


[5/5] incubator-freemarker git commit: - Totally redesigned TemplateLoader interface. The FM2 TemplateLoader can't be adapted (wrapped) to it, but usually

Posted by dd...@apache.org.
- Totally redesigned TemplateLoader interface. The FM2 TemplateLoader can't be adapted (wrapped) to it, but usually

  it's fairly trivial to "rearrange" an old custom TemplateLoader for the new interface. The new TemplateLoader comes
  with several advantages, such as:
  - It can work more efficiently with sophisticated storage mechanisms like a database, as it's now possible to pack
    together the existence check, the last modification change check, and reading operations into less storage level
    operations (like you can do all of them with a single SQL statement).
  - The new TemplateLoader allows returning the template content either as an InputStream or as a Reader. Almost all
    TemplateLoader-s should return InputStream, and FreeMarker takes care of charset issues transparently (as a result,
    TemplateLoader-s don't have to support re-reading a template anymore, as we solve charset detection misses in
    memory). TemplateLoader-s that are inherently backed by text (String-s), such as templates stored in a varchar or
    CLOB column, should return a Reader. Note that templates created from a Reader will have template.getEncoding()
    null (logically, as no charset was involved), which was impossible in FreeMarker 2.
  - The change detection of the template doesn't have to rely on a millisecond resolution timestamp anymore; you can
    use what's most appropriate for the storage mechanism, such as a cryptographic hash or a revision number.
  - Template lookups (where you try multiple names until you find the best template) can now be transactional and/or
    atomic if the backing storage mechanism supports that, by utilizing the TemplateLoaderSession interface.
  - TemplateLoader can now return template-level settings like the output format (MIME type basically) of the loaded
    template, in case the backing storage stores such extra information. This mechanism can be used together with
    the TemplateConfiguration mechanism (already familiar from FreeMarker 2), and overrides the individual settings
    coming from there.

- Template constructors won't close the Reader passed in as agrument anymore (because a Reader should be closed
  by who has created it). This avoids some surprises from the past, such as the unablility to reset a Reader to a mark
  after parsing. If you call those constructors, be sure that you close the Reader yourself. (Obviously, it doesn't
  mater for StringReader-s.)


Project: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/commit/3d0fdc8c
Tree: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/tree/3d0fdc8c
Diff: http://git-wip-us.apache.org/repos/asf/incubator-freemarker/diff/3d0fdc8c

Branch: refs/heads/3
Commit: 3d0fdc8c7250b36b374dc19489ff16050366cf10
Parents: f8d4057
Author: ddekany <dd...@apache.org>
Authored: Sun Feb 5 19:38:32 2017 +0100
Committer: ddekany <dd...@apache.org>
Committed: Sat Feb 11 00:46:46 2017 +0100

----------------------------------------------------------------------
 .../cache/ByteArrayTemplateLoader.java          | 203 +++--
 .../freemarker/cache/ClassTemplateLoader.java   |  58 +-
 ...ConditionalTemplateConfigurationFactory.java |   6 +-
 .../freemarker/cache/FileTemplateLoader.java    | 129 ++--
 .../FirstMatchTemplateConfigurationFactory.java |   4 +-
 .../MergingTemplateConfigurationFactory.java    |   4 +-
 .../freemarker/cache/MultiTemplateLoader.java   | 207 ++----
 .../cache/StatefulTemplateLoader.java           |  35 -
 .../freemarker/cache/StringTemplateLoader.java  | 233 +++---
 .../java/freemarker/cache/TemplateCache.java    | 735 +++++++++++--------
 .../cache/TemplateConfigurationFactory.java     |   8 +-
 .../java/freemarker/cache/TemplateLoader.java   | 138 ++--
 .../freemarker/cache/TemplateLoaderSession.java |  73 ++
 .../freemarker/cache/TemplateLoaderUtils.java   |   3 +-
 .../freemarker/cache/TemplateLoadingResult.java | 199 +++++
 .../cache/TemplateLoadingResultStatus.java      |  49 ++
 .../freemarker/cache/TemplateLoadingSource.java |  66 ++
 .../freemarker/cache/TemplateLookupContext.java |  29 +-
 .../freemarker/cache/TemplateLookupResult.java  |  34 +-
 .../freemarker/cache/URLTemplateLoader.java     | 135 +++-
 .../cache/URLTemplateLoadingSource.java         |  56 ++
 .../freemarker/cache/URLTemplateSource.java     | 144 ----
 .../freemarker/cache/WebAppTemplateLoader.java  | 296 ++++++++
 .../freemarker/cache/WebappTemplateLoader.java  | 228 ------
 .../freemarker/core/BuiltInsForStringsMisc.java |   2 +-
 src/main/java/freemarker/core/Configurable.java |   2 +-
 src/main/java/freemarker/core/Environment.java  |   4 +-
 ...eleaserTemplateSpecifiedEncodingHandler.java |  55 ++
 .../java/freemarker/core/StringLiteral.java     |   4 +-
 .../freemarker/core/TemplateConfiguration.java  |  32 +-
 .../core/TemplateSpecifiedEncodingHandler.java  |  61 ++
 src/main/java/freemarker/core/_CoreAPI.java     |   5 +-
 .../ext/servlet/FreemarkerServlet.java          |  30 +-
 .../freemarker/ext/servlet/InitParamParser.java |   4 +-
 .../java/freemarker/template/Configuration.java |  51 +-
 src/main/java/freemarker/template/Template.java |  70 +-
 .../java/freemarker/template/_TemplateAPI.java  |   5 -
 src/main/javacc/FTL.jj                          |  26 +-
 src/manual/en_US/FM3-CHANGE-LOG.txt             |  45 +-
 .../cache/MultiTemplateLoaderTest.java          |  47 +-
 .../freemarker/cache/TemplateCacheTest.java     | 330 +++++----
 .../cache/TemplateConfigurationFactoryTest.java |  19 +-
 .../cache/TemplateNameFormatTest.java           |  18 +-
 .../IncludeAndImportConfigurableLayersTest.java |   5 +-
 .../freemarker/core/IncludeAndImportTest.java   |  15 +-
 .../core/ObjectBuilderSettingsTest.java         |  20 +-
 .../freemarker/core/TemplatGetEncodingTest.java |  14 +-
 .../ext/jsp/RealServletContainertTest.java      |   6 +-
 .../ext/servlet/FreemarkerServletTest.java      |  64 +-
 .../ext/servlet/InitParamParserTest.java        |  29 +-
 .../java/freemarker/manual/ExamplesTest.java    |   4 +-
 .../freemarker/template/ConfigurationTest.java  |  44 +-
 .../template/TemplateLookupStrategyTest.java    | 174 ++---
 .../template/TemplateNotFoundMessageTest.java   |  35 +-
 .../CopyrightCommentRemoverTemplateLoader.java  |  64 +-
 .../test/MonitoredTemplateLoader.java           | 305 +++++++-
 src/test/java/freemarker/test/TemplateTest.java |  33 +-
 57 files changed, 2836 insertions(+), 1858 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/ByteArrayTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/ByteArrayTemplateLoader.java b/src/main/java/freemarker/cache/ByteArrayTemplateLoader.java
index 11b2182..974a0ef 100644
--- a/src/main/java/freemarker/cache/ByteArrayTemplateLoader.java
+++ b/src/main/java/freemarker/cache/ByteArrayTemplateLoader.java
@@ -20,12 +20,14 @@
 package freemarker.cache;
 
 import java.io.ByteArrayInputStream;
-import java.io.InputStreamReader;
-import java.io.Reader;
-import java.io.UnsupportedEncodingException;
-import java.util.HashMap;
-import java.util.Iterator;
+import java.io.IOException;
+import java.io.ObjectOutputStream;
+import java.io.Serializable;
 import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+import java.util.concurrent.atomic.AtomicLong;
 
 import freemarker.template.utility.StringUtil;
 
@@ -33,93 +35,79 @@ import freemarker.template.utility.StringUtil;
  * A {@link TemplateLoader} that uses a {@link Map} with {@code byte[]} as its source of templates. This is similar to
  * {@link StringTemplateLoader}, but uses {@code byte[]} instead of {@link String}; see more details there.
  * 
- * @since 2.3.24
+ * <p>Note that {@link ByteArrayTemplateLoader} can't be used with a distributed (cluster-wide) {@link CacheStorage},
+ * as it produces {@link TemplateLoadingSource}-s that deliberately throw exception on serialization (because the
+ * content is only accessible within a single JVM, and is also volatile).
  */
+// TODO JUnit tests
 public class ByteArrayTemplateLoader implements TemplateLoader {
     
-    private final Map<String, ByteArrayTemplateSource> templates = new HashMap<String, ByteArrayTemplateSource>();
+    private static final AtomicLong INSTANCE_COUNTER = new AtomicLong();
     
-    /**
-     * Puts a template into the loader. A call to this method is identical to 
-     * the call to the three-arg {@link #putTemplate(String, byte[], long)} 
-     * passing <tt>System.currentTimeMillis()</tt> as the third argument.
-     * @param name the name of the template.
-     * @param templateSource the source code of the template.
-     */
-    public void putTemplate(String name, byte[] templateSource) {
-        putTemplate(name, templateSource, System.currentTimeMillis());
-    }
+    private final long instanceId = INSTANCE_COUNTER.get();
+    private final AtomicLong templatesRevision = new AtomicLong();
+    private final ConcurrentMap<String, ContentHolder> templates = new ConcurrentHashMap<>();
     
     /**
-     * Puts a template into the loader. The name can contain slashes to denote
-     * logical directory structure, but must not start with a slash. If the 
-     * method is called multiple times for the same name and with different
-     * last modified time, the configuration's template cache will reload the 
-     * template according to its own refresh settings (note that if the refresh 
-     * is disabled in the template cache, the template will not be reloaded).
-     * Also, since the cache uses lastModified to trigger reloads, calling the
-     * method with different source and identical timestamp won't trigger
-     * reloading.
-     * @param name the name of the template.
-     * @param templateSource the source code of the template.
-     * @param lastModified the time of last modification of the template in 
-     * terms of <tt>System.currentTimeMillis()</tt>
+     * Puts a template into the template loader. The name can contain slashes to denote logical directory structure, but
+     * must not start with a slash. Each template will get an unique revision number, thus replacing a template will
+     * cause the template cache to reload it (when the update delay expires).
+     * 
+     * <p>This method is thread-safe.
+     * 
+     * @param name
+     *            the name of the template.
+     * @param content
+     *            the source code of the template.
      */
-    public void putTemplate(String name, byte[] templateSource, long lastModified) {
-        templates.put(name, new ByteArrayTemplateSource(name, templateSource, lastModified));
-    }
-    
-    public void closeTemplateSource(Object templateSource) {
-    }
-    
-    public Object findTemplateSource(String name) {
-        return templates.get(name);
+    public void putTemplate(String name, byte[] content) {
+        templates.put(
+                name,
+                new ContentHolder(content, new Source(instanceId, name), templatesRevision.incrementAndGet()));
     }
     
-    public long getLastModified(Object templateSource) {
-        return ((ByteArrayTemplateSource) templateSource).lastModified;
+    /**
+     * Removes the template with the specified name if it was added earlier.
+     * 
+     * <p>
+     * This method is thread-safe.
+     * 
+     * @param name
+     *            Exactly the key with which the template was added.
+     * 
+     * @return Whether a template was found with the given key (and hence was removed now)
+     */ 
+    public boolean removeTemplate(String name) {
+        return templates.remove(name) != null;
     }
     
-    public Reader getReader(Object templateSource, String encoding) throws UnsupportedEncodingException {
-        return new InputStreamReader(
-                new ByteArrayInputStream(((ByteArrayTemplateSource) templateSource).source),
-                encoding);
+    @Override
+    public TemplateLoaderSession createSession() {
+        return null;
     }
-    
-    private static class ByteArrayTemplateSource {
-        private final String name;
-        private final byte[] source;
-        private final long lastModified;
-        
-        ByteArrayTemplateSource(String name, byte[] source, long lastModified) {
-            if (name == null) {
-                throw new IllegalArgumentException("name == null");
-            }
-            if (source == null) {
-                throw new IllegalArgumentException("source == null");
-            }
-            if (lastModified < -1L) {
-                throw new IllegalArgumentException("lastModified < -1L");
-            }
-            this.name = name;
-            this.source = source;
-            this.lastModified = lastModified;
-        }
-        
-        @Override
-        public boolean equals(Object obj) {
-            if (obj instanceof ByteArrayTemplateSource) {
-                return name.equals(((ByteArrayTemplateSource) obj).name);
-            }
-            return false;
-        }
-        
-        @Override
-        public int hashCode() {
-            return name.hashCode();
+
+    @Override
+    public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom,
+            Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws IOException {
+        ContentHolder contentHolder = templates.get(name);
+        if (contentHolder == null) {
+            return TemplateLoadingResult.NOT_FOUND;
+        } else if (ifSourceDiffersFrom != null && ifSourceDiffersFrom.equals(contentHolder.source)
+                && Objects.equals(ifVersionDiffersFrom, contentHolder.version)) {
+            return TemplateLoadingResult.NOT_MODIFIED;
+        } else {
+            return new TemplateLoadingResult(
+                    contentHolder.source, contentHolder.version,
+                    new ByteArrayInputStream(contentHolder.content),
+                    null);
         }
     }
-    
+
+    @Override
+    public void resetState() {
+        // Do nothing
+    }
+
     /**
      * Show class name and some details that are useful in template-not-found errors.
      */
@@ -129,7 +117,7 @@ public class ByteArrayTemplateLoader implements TemplateLoader {
         sb.append(TemplateLoaderUtils.getClassNameForToString(this));
         sb.append("(Map { ");
         int cnt = 0;
-        for (Iterator it = templates.keySet().iterator(); it.hasNext(); ) {
+        for (String name : templates.keySet()) {
             cnt++;
             if (cnt != 1) {
                 sb.append(", ");
@@ -138,7 +126,7 @@ public class ByteArrayTemplateLoader implements TemplateLoader {
                 sb.append("...");
                 break;
             }
-            sb.append(StringUtil.jQuote(it.next()));
+            sb.append(StringUtil.jQuote(name));
             sb.append("=...");
         }
         if (cnt != 0) {
@@ -147,5 +135,60 @@ public class ByteArrayTemplateLoader implements TemplateLoader {
         sb.append("})");
         return sb.toString();
     }
+
+    private static class ContentHolder {
+        private final byte[] content;
+        private final Source source;
+        private final long version;
+        
+        public ContentHolder(byte[] content, Source source, long version) {
+            this.content = content;
+            this.source = source;
+            this.version = version;
+        }
+        
+    }
+    
+    @SuppressWarnings("serial")
+    private static class Source implements TemplateLoadingSource {
+        
+        private final long instanceId;
+        private final String name;
+        
+        public Source(long instanceId, String name) {
+            this.instanceId = instanceId;
+            this.name = name;
+        }
+    
+        @Override
+        public int hashCode() {
+            final int prime = 31;
+            int result = 1;
+            result = prime * result + (int) (instanceId ^ (instanceId >>> 32));
+            result = prime * result + ((name == null) ? 0 : name.hashCode());
+            return result;
+        }
+    
+        @Override
+        public boolean equals(Object obj) {
+            if (this == obj) return true;
+            if (obj == null) return false;
+            if (getClass() != obj.getClass()) return false;
+            Source other = (Source) obj;
+            if (instanceId != other.instanceId) return false;
+            if (name == null) {
+                if (other.name != null) return false;
+            } else if (!name.equals(other.name)) {
+                return false;
+            }
+            return true;
+        }
+        
+        private void writeObject(ObjectOutputStream out) throws IOException {
+            throw new IOException(ByteArrayTemplateLoader.class.getName()
+                    + " sources can't be serialized, as they don't support clustering.");
+        }
+        
+    }
     
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/ClassTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/ClassTemplateLoader.java b/src/main/java/freemarker/cache/ClassTemplateLoader.java
index 1bfbec8..e9825fe 100644
--- a/src/main/java/freemarker/cache/ClassTemplateLoader.java
+++ b/src/main/java/freemarker/cache/ClassTemplateLoader.java
@@ -29,48 +29,14 @@ import freemarker.template.utility.StringUtil;
  * anywhere where Java can load classes from. Internally, it uses {@link Class#getResource(String)} or
  * {@link ClassLoader#getResource(String)} to load templates.
  */
+// TODO
 public class ClassTemplateLoader extends URLTemplateLoader {
     
-    private final Class resourceLoaderClass;
+    private final Class<?> resourceLoaderClass;
     private final ClassLoader classLoader;
     private final String basePackagePath;
 
     /**
-     * Creates a template loader that will use the {@link Class#getResource(String)} method of its own class to load the
-     * resources, and {@code "/"} as base package path. This means that that template paths will be resolved relatively
-     * the root package of the class hierarchy, so you hardly ever should use this constructor, rather do something like
-     * this:<br>
-     * {@link #ClassTemplateLoader(Class, String) new ClassTemplateLoader(com.example.myapplication.SomeClass.class,
-     * "templates")}
-     *
-     * <p>
-     * If you extend this class, then the extending class will be used to load the resources.
-     *
-     * @deprecated It's a confusing constructor, and seldom useful; use {@link #ClassTemplateLoader(Class, String)}
-     *             instead.
-     */
-    @Deprecated
-    public ClassTemplateLoader() {
-        this(null, true, null, "/");
-    }
-
-    /**
-     * Creates a template loader that will use the {@link Class#getResource(String)} method of the specified class to
-     * load the resources, and {@code ""} as base package path. This means that template paths will be resolved
-     * relatively to the class location, that is, relatively to the directory (package) of the class.
-     *
-     * @param resourceLoaderClass
-     *            the class whose {@link Class#getResource(String)} will be used to load the templates.
-     *
-     * @deprecated It's confusing that the base path is {@code ""}; use {@link #ClassTemplateLoader(Class, String)}
-     *             instead.
-     */
-    @Deprecated
-    public ClassTemplateLoader(Class resourceLoaderClass) {
-        this(resourceLoaderClass, "");
-    }
-
-    /**
      * Creates a template loader that will use the {@link Class#getResource(String)} method of the specified class to
      * load the resources, and the specified base package path (absolute or relative).
      *
@@ -96,7 +62,7 @@ public class ClassTemplateLoader extends URLTemplateLoader {
      * 
      * @see #ClassTemplateLoader(ClassLoader, String)
      */
-    public ClassTemplateLoader(Class resourceLoaderClass, String basePackagePath) {
+    public ClassTemplateLoader(Class<?> resourceLoaderClass, String basePackagePath) {
         this(resourceLoaderClass, false, null, basePackagePath);
     }
 
@@ -105,16 +71,14 @@ public class ClassTemplateLoader extends URLTemplateLoader {
      * {@link ClassLoader#getResource(String)}. Because a {@link ClassLoader} isn't bound to any Java package, it
      * doesn't mater if the {@code basePackagePath} starts with {@code /} or not, it will be always relative to the root
      * of the package hierarchy
-     * 
-     * @since 2.3.22
      */
     public ClassTemplateLoader(ClassLoader classLoader, String basePackagePath) {
         this(null, true, classLoader, basePackagePath);
     }
 
-    private ClassTemplateLoader(Class resourceLoaderClass, boolean allowNullBaseClass, ClassLoader classLoader,
-            String basePackagePath) {
-        if (!allowNullBaseClass) {
+    private ClassTemplateLoader(Class<?> resourceLoaderClass, boolean allowNullResourceLoaderClass,
+            ClassLoader classLoader, String basePackagePath) {
+        if (!allowNullResourceLoaderClass) {
             NullArgumentException.check("resourceLoaderClass", resourceLoaderClass);
         }
         NullArgumentException.check("basePackagePath", basePackagePath);
@@ -167,8 +131,6 @@ public class ClassTemplateLoader extends URLTemplateLoader {
 
     /**
      * Show class name and some details that are useful in template-not-found errors.
-     * 
-     * @since 2.3.21
      */
     @Override
     public String toString() {
@@ -189,18 +151,14 @@ public class ClassTemplateLoader extends URLTemplateLoader {
     /**
      * See the similar parameter of {@link #ClassTemplateLoader(Class, String)}; {@code null} when other mechanism is
      * used to load the resources.
-     * 
-     * @since 2.3.22
      */
-    public Class getResourceLoaderClass() {
+    public Class<?> getResourceLoaderClass() {
         return resourceLoaderClass;
     }
 
     /**
      * See the similar parameter of {@link #ClassTemplateLoader(ClassLoader, String)}; {@code null} when other mechanism
      * is used to load the resources.
-     * 
-     * @since 2.3.22
      */
     public ClassLoader getClassLoader() {
         return classLoader;
@@ -209,8 +167,6 @@ public class ClassTemplateLoader extends URLTemplateLoader {
     /**
      * See the similar parameter of {@link #ClassTemplateLoader(ClassLoader, String)}; note that this is a normalized
      * version of what was actually passed to the constructor.
-     * 
-     * @since 2.3.22
      */
     public String getBasePackagePath() {
         return basePackagePath;

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/ConditionalTemplateConfigurationFactory.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/ConditionalTemplateConfigurationFactory.java b/src/main/java/freemarker/cache/ConditionalTemplateConfigurationFactory.java
index 430632e..5110467 100644
--- a/src/main/java/freemarker/cache/ConditionalTemplateConfigurationFactory.java
+++ b/src/main/java/freemarker/cache/ConditionalTemplateConfigurationFactory.java
@@ -50,11 +50,11 @@ public class ConditionalTemplateConfigurationFactory extends TemplateConfigurati
     }
 
     @Override
-    public TemplateConfiguration get(String sourceName, Object templateSource)
+    public TemplateConfiguration get(String sourceName, TemplateLoadingSource templateLoadingSource)
             throws IOException, TemplateConfigurationFactoryException {
-        if (matcher.matches(sourceName, templateSource)) {
+        if (matcher.matches(sourceName, templateLoadingSource)) {
             if (templateConfigurationFactory != null) {
-                return templateConfigurationFactory.get(sourceName, templateSource);
+                return templateConfigurationFactory.get(sourceName, templateLoadingSource);
             } else {
                 return templateConfiguration;
             }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/FileTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/FileTemplateLoader.java b/src/main/java/freemarker/cache/FileTemplateLoader.java
index 166f128..fef103c 100644
--- a/src/main/java/freemarker/cache/FileTemplateLoader.java
+++ b/src/main/java/freemarker/cache/FileTemplateLoader.java
@@ -23,12 +23,13 @@ import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileNotFoundException;
 import java.io.IOException;
-import java.io.InputStreamReader;
-import java.io.Reader;
+import java.io.InputStream;
+import java.io.Serializable;
 import java.security.AccessController;
 import java.security.PrivilegedAction;
 import java.security.PrivilegedActionException;
 import java.security.PrivilegedExceptionAction;
+import java.util.Objects;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -41,8 +42,8 @@ import freemarker.template.utility.StringUtil;
  * A {@link TemplateLoader} that uses files inside a specified directory as the source of templates. By default it does
  * security checks on the <em>canonical</em> path that will prevent it serving templates outside that specified
  * directory. If you want symbolic links that point outside the template directory to work, you need to disable this
- * feature by using {@link #FileTemplateLoader(File, boolean)} with {@code true} second argument, but before that, check
- * the security implications there!
+ * feature by using {@link #FileTemplateLoader(File, boolean)} with {@code true} second argument, but before that,
+ * check the security implications there!
  */
 public class FileTemplateLoader implements TemplateLoader {
     
@@ -77,20 +78,6 @@ public class FileTemplateLoader implements TemplateLoader {
     private MruCacheStorage correctCasePaths;
 
     /**
-     * Creates a new file template cache that will use the current directory (the value of the system property
-     * <code>user.dir</code> as the base directory for loading templates. It will not allow access to template files
-     * that are accessible through symlinks that point outside the base directory.
-     * 
-     * @deprecated Relying on what the current directory is is a bad practice; use
-     *             {@link FileTemplateLoader#FileTemplateLoader(File)} instead.
-     */
-    @Deprecated
-    public FileTemplateLoader()
-    throws IOException {
-        this(new File(SecurityUtilities.getSystemProperty("user.dir")));
-    }
-
-    /**
      * Creates a new file template loader that will use the specified directory
      * as the base directory for loading templates. It will not allow access to
      * template files that are accessible through symlinks that point outside 
@@ -121,9 +108,9 @@ public class FileTemplateLoader implements TemplateLoader {
     public FileTemplateLoader(final File baseDir, final boolean disableCanonicalPathCheck)
     throws IOException {
         try {
-            Object[] retval = (Object[]) AccessController.doPrivileged(new PrivilegedExceptionAction() {
+            Object[] retval = AccessController.doPrivileged(new PrivilegedExceptionAction<Object[]>() {
                 @Override
-                public Object run() throws IOException {
+                public Object[] run() throws IOException {
                     if (!baseDir.exists()) {
                         throw new FileNotFoundException(baseDir + " does not exist.");
                     }
@@ -156,13 +143,11 @@ public class FileTemplateLoader implements TemplateLoader {
         }
     }
     
-    @Override
-    public Object findTemplateSource(final String name)
-    throws IOException {
+    private File getFile(final String name) throws IOException {
         try {
-            return AccessController.doPrivileged(new PrivilegedExceptionAction() {
+            return AccessController.doPrivileged(new PrivilegedExceptionAction<File>() {
                 @Override
-                public Object run() throws IOException {
+                public File run() throws IOException {
                     File source = new File(baseDir, SEP_IS_SLASH ? name : 
                         name.replace('/', File.separatorChar));
                     if (!source.isFile()) {
@@ -192,34 +177,22 @@ public class FileTemplateLoader implements TemplateLoader {
         }
     }
     
-    @Override
-    public long getLastModified(final Object templateSource) {
-        return ((Long) (AccessController.doPrivileged(new PrivilegedAction()
-        {
+    private long getLastModified(final File templateSource) {
+        return (AccessController.<Long>doPrivileged(new PrivilegedAction<Long>() {
             @Override
-            public Object run() {
-                return Long.valueOf(((File) templateSource).lastModified());
+            public Long run() {
+                return Long.valueOf((templateSource).lastModified());
             }
-        }))).longValue();
-        
-        
+        })).longValue();
     }
     
-    @Override
-    public Reader getReader(final Object templateSource, final String encoding)
+    private InputStream getInputStream(final File templateSource)
     throws IOException {
         try {
-            return (Reader) AccessController.doPrivileged(new PrivilegedExceptionAction()
-            {
+            return AccessController.doPrivileged(new PrivilegedExceptionAction<InputStream>() {
                 @Override
-                public Object run()
-                throws IOException {
-                    if (!(templateSource instanceof File)) {
-                        throw new IllegalArgumentException(
-                                "templateSource wasn't a File, but a: " + 
-                                templateSource.getClass().getName());
-                    }
-                    return new InputStreamReader(new FileInputStream((File) templateSource), encoding);
+                public InputStream run() throws IOException {
+                    return new FileInputStream(templateSource);
                 }
             });
         } catch (PrivilegedActionException e) {
@@ -228,9 +201,7 @@ public class FileTemplateLoader implements TemplateLoader {
     }
     
     /**
-     * Called by {@link #findTemplateSource(String)} when {@link #getEmulateCaseSensitiveFileSystem()} is {@code true}. Should throw
-     * {@link FileNotFoundException} if there's a mismatch; the error message should contain both the requested and the
-     * correct file name.
+     * Called by {@link #getFile(String)} when {@link #getEmulateCaseSensitiveFileSystem()} is {@code true}.
      */
     private boolean isNameCaseCorrect(File source) throws IOException {
         final String sourcePath = source.getPath();
@@ -278,11 +249,6 @@ public class FileTemplateLoader implements TemplateLoader {
         }
         return true;
     }
-
-    @Override
-    public void closeTemplateSource(Object templateSource) {
-        // Do nothing.
-    }
     
     /**
      * Returns the base directory in which the templates are searched. This comes from the constructor argument, but
@@ -356,5 +322,60 @@ public class FileTemplateLoader implements TemplateLoader {
                 + (emulateCaseSensitiveFileSystem ? ", emulateCaseSensitiveFileSystem=true" : "")
                 + ")";
     }
+
+    @Override
+    public TemplateLoaderSession createSession() {
+        return null;
+    }
+
+    @Override
+    public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom,
+            Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws IOException {
+        File file = getFile(name);
+        if (file == null) {
+            return TemplateLoadingResult.NOT_FOUND;
+        }
+        
+        FileTemplateLoadingSource source = new FileTemplateLoadingSource(file);
+        
+        long lmd = getLastModified(file);
+        Long version = lmd != -1 ? lmd : null;
+        
+        if (ifSourceDiffersFrom != null && ifSourceDiffersFrom.equals(source) 
+                && Objects.equals(ifVersionDiffersFrom, version)) {
+            return TemplateLoadingResult.NOT_MODIFIED;
+        }
+        
+        return new TemplateLoadingResult(source, version, getInputStream(file), null);
+    }
+
+    @Override
+    public void resetState() {
+        // Does nothing
+    }
+    
+    @SuppressWarnings("serial")
+    private static class FileTemplateLoadingSource implements TemplateLoadingSource {
+        
+        private final File file;
+
+        FileTemplateLoadingSource(File file) {
+            this.file = file;
+        }
+
+        @Override
+        public int hashCode() {
+            return file.hashCode();
+        }
+
+        @Override
+        public boolean equals(Object obj) {
+            if (this == obj) return true;
+            if (obj == null) return false;
+            if (getClass() != obj.getClass()) return false;
+            return file.equals(((FileTemplateLoadingSource) obj).file);
+        }
+        
+    }
     
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/FirstMatchTemplateConfigurationFactory.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/FirstMatchTemplateConfigurationFactory.java b/src/main/java/freemarker/cache/FirstMatchTemplateConfigurationFactory.java
index 9382656..d521cc2 100644
--- a/src/main/java/freemarker/cache/FirstMatchTemplateConfigurationFactory.java
+++ b/src/main/java/freemarker/cache/FirstMatchTemplateConfigurationFactory.java
@@ -39,10 +39,10 @@ public class FirstMatchTemplateConfigurationFactory extends TemplateConfiguratio
     }
 
     @Override
-    public TemplateConfiguration get(String sourceName, Object templateSource)
+    public TemplateConfiguration get(String sourceName, TemplateLoadingSource templateLoadingSource)
             throws IOException, TemplateConfigurationFactoryException {
         for (TemplateConfigurationFactory tcf : templateConfigurationFactories) {
-            TemplateConfiguration tc = tcf.get(sourceName, templateSource); 
+            TemplateConfiguration tc = tcf.get(sourceName, templateLoadingSource); 
             if (tc != null) {
                 return tc;
             }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/MergingTemplateConfigurationFactory.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/MergingTemplateConfigurationFactory.java b/src/main/java/freemarker/cache/MergingTemplateConfigurationFactory.java
index 3675d19..b0df922 100644
--- a/src/main/java/freemarker/cache/MergingTemplateConfigurationFactory.java
+++ b/src/main/java/freemarker/cache/MergingTemplateConfigurationFactory.java
@@ -39,12 +39,12 @@ public class MergingTemplateConfigurationFactory extends TemplateConfigurationFa
     }
 
     @Override
-    public TemplateConfiguration get(String sourceName, Object templateSource)
+    public TemplateConfiguration get(String sourceName, TemplateLoadingSource templateLoadingSource)
             throws IOException, TemplateConfigurationFactoryException {
         TemplateConfiguration mergedTC = null;
         TemplateConfiguration resultTC = null;
         for (TemplateConfigurationFactory tcf : templateConfigurationFactories) {
-            TemplateConfiguration tc = tcf.get(sourceName, templateSource);
+            TemplateConfiguration tc = tcf.get(sourceName, templateLoadingSource);
             if (tc != null) {
                 if (resultTC == null) {
                     resultTC = tc;

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/MultiTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/MultiTemplateLoader.java b/src/main/java/freemarker/cache/MultiTemplateLoader.java
index c86baa3..583f62e 100644
--- a/src/main/java/freemarker/cache/MultiTemplateLoader.java
+++ b/src/main/java/freemarker/cache/MultiTemplateLoader.java
@@ -20,153 +20,49 @@
 package freemarker.cache;
 
 import java.io.IOException;
-import java.io.Reader;
+import java.io.Serializable;
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
+import freemarker.template.utility.NullArgumentException;
+
 /**
  * A {@link TemplateLoader} that uses a set of other loaders to load the templates. On every request, loaders are
- * queried in the order of their appearance in the array of loaders provided to the constructor. However, by default, if
+ * queried in the order of their appearance in the array of loaders provided to the constructor. Except, when the
+ * {@linkplain #setSticky(boolean)} sticky} setting is set to {@code true} (default is false {@code false}), if
  * a request for some template name was already satisfied in the past by one of the loaders, that loader is queried
- * first (stickiness). This behavior can be disabled with {@link #setSticky(boolean)}, then the loaders are always
- * queried in the order of their appearance in the array.
+ * first (stickiness).
  * 
  * <p>This class is thread-safe.
  */
-public class MultiTemplateLoader implements StatefulTemplateLoader {
+// TODO JUnit test
+public class MultiTemplateLoader implements TemplateLoader {
 
-    private final TemplateLoader[] loaders;
-    private final Map<String, TemplateLoader> lastLoaderForName = new ConcurrentHashMap<String, TemplateLoader>();
+    private final TemplateLoader[] templateLoaders;
+    private final Map<String, TemplateLoader> lastTemplateLoaderForName = new ConcurrentHashMap<String, TemplateLoader>();
     
-    private boolean sticky = true;
+    private boolean sticky = false;
 
     /**
-     * Creates a new multi template Loader that will use the specified loaders.
+     * Creates a new instance that will use the specified template loaders.
      * 
-     * @param loaders
-     *            the loaders that are used to load templates.
+     * @param templateLoaders
+     *            the template loaders that are used to load templates, in the order as they will be searched
+     *            (except where {@linkplain #setSticky(boolean) stickiness} says otherwise).
      */
-    public MultiTemplateLoader(TemplateLoader[] loaders) {
-        this.loaders = loaders.clone();
-    }
-
-    public Object findTemplateSource(String name)
-            throws IOException {
-        if (sticky) {
-            // Use soft affinity - give the loader that last found this
-            // resource a chance to find it again first.
-            TemplateLoader lastLoader = lastLoaderForName.get(name);
-            if (lastLoader != null) {
-                Object source = lastLoader.findTemplateSource(name);
-                if (source != null) {
-                    return new MultiSource(source, lastLoader);
-                }
-            }
-        }
-
-        // If there is no affine loader, or it could not find the resource
-        // again, try all loaders in order of appearance. If any manages
-        // to find the resource, then associate it as the new affine loader
-        // for this resource.
-        for (int i = 0; i < loaders.length; ++i) {
-            TemplateLoader loader = loaders[i];
-            Object source = loader.findTemplateSource(name);
-            if (source != null) {
-                if (sticky) {
-                    lastLoaderForName.put(name, loader);
-                }
-                return new MultiSource(source, loader);
-            }
-        }
-
-        if (sticky) {
-            lastLoaderForName.remove(name);
-        }
-        // Resource not found
-        return null;
-    }
-
-    private Object modifyForIcI(Object source) {
-        // TODO Auto-generated method stub
-        return null;
-    }
-
-    public long getLastModified(Object templateSource) {
-        return ((MultiSource) templateSource).getLastModified();
-    }
-
-    public Reader getReader(Object templateSource, String encoding)
-            throws IOException {
-        return ((MultiSource) templateSource).getReader(encoding);
-    }
-
-    public void closeTemplateSource(Object templateSource)
-            throws IOException {
-        ((MultiSource) templateSource).close();
+    public MultiTemplateLoader(TemplateLoader... templateLoaders) {
+        NullArgumentException.check("templateLoaders", templateLoaders);
+        this.templateLoaders = templateLoaders.clone();
     }
 
     /**
-     * Clears the soft affinity memory, also resets all enclosed {@link StatefulTemplateLoader}-s.
+     * Clears the sickiness memory, also resets the state of all enclosed {@link TemplateLoader}-s.
      */
+    @Override
     public void resetState() {
-        lastLoaderForName.clear();
-        for (int i = 0; i < loaders.length; i++) {
-            TemplateLoader loader = loaders[i];
-            if (loader instanceof StatefulTemplateLoader) {
-                ((StatefulTemplateLoader) loader).resetState();
-            }
-        }
-    }
-
-    /**
-     * Represents a template source bound to a specific template loader. It serves as the complete template source
-     * descriptor used by the MultiTemplateLoader class.
-     */
-    static final class MultiSource {
-
-        private final Object source;
-        private final TemplateLoader loader;
-
-        MultiSource(Object source, TemplateLoader loader) {
-            this.source = source;
-            this.loader = loader;
-        }
-
-        long getLastModified() {
-            return loader.getLastModified(source);
-        }
-
-        Reader getReader(String encoding)
-                throws IOException {
-            return loader.getReader(source, encoding);
-        }
-
-        void close()
-                throws IOException {
-            loader.closeTemplateSource(source);
-        }
-
-        Object getWrappedSource() {
-            return source;
-        }
-
-        @Override
-        public boolean equals(Object o) {
-            if (o instanceof MultiSource) {
-                MultiSource m = (MultiSource) o;
-                return m.loader.equals(loader) && m.source.equals(source);
-            }
-            return false;
-        }
-
-        @Override
-        public int hashCode() {
-            return loader.hashCode() + 31 * source.hashCode();
-        }
-
-        @Override
-        public String toString() {
-            return source.toString();
+        lastTemplateLoaderForName.clear();
+        for (TemplateLoader templateLoader : templateLoaders) {
+            templateLoader.resetState();
         }
     }
 
@@ -179,11 +75,11 @@ public class MultiTemplateLoader implements StatefulTemplateLoader {
     public String toString() {
         StringBuilder sb = new StringBuilder();
         sb.append("MultiTemplateLoader(");
-        for (int i = 0; i < loaders.length; i++) {
+        for (int i = 0; i < templateLoaders.length; i++) {
             if (i != 0) {
                 sb.append(", ");
             }
-            sb.append("loader").append(i + 1).append(" = ").append(loaders[i]);
+            sb.append("loader").append(i + 1).append(" = ").append(templateLoaders[i]);
         }
         sb.append(")");
         return sb.toString();
@@ -195,7 +91,7 @@ public class MultiTemplateLoader implements StatefulTemplateLoader {
      * @since 2.3.23
      */
     public int getTemplateLoaderCount() {
-        return loaders.length;
+        return templateLoaders.length;
     }
 
     /**
@@ -205,22 +101,67 @@ public class MultiTemplateLoader implements StatefulTemplateLoader {
      *            Must be below {@link #getTemplateLoaderCount()}.
      */
     public TemplateLoader getTemplateLoader(int index) {
-        return loaders[index];
+        return templateLoaders[index];
     }
 
     /**
-     * @since 2.3.24
+     * Getter pair of {@link #setSticky(boolean)}.
      */
     public boolean isSticky() {
         return sticky;
     }
 
     /**
-     * @since 2.3.24
+     * Sets if for a name that was already loaded earlier the same {@link TemplateLoader} will be tried first, or
+     * we always try the {@link TemplateLoader}-s strictly in the order as it was specified in the constructor.
+     * The default is {@code false}.
      */
     public void setSticky(boolean sticky) {
         this.sticky = sticky;
     }
 
+    @Override
+    public TemplateLoaderSession createSession() {
+        return null;
+    }
+
+    @Override
+    public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom,
+            Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws IOException {
+        TemplateLoader lastLoader = null;
+        if (sticky) {
+            // Use soft affinity - give the loader that last found this
+            // resource a chance to find it again first.
+            lastLoader = lastTemplateLoaderForName.get(name);
+            if (lastLoader != null) {
+                TemplateLoadingResult result = lastLoader.load(name, ifSourceDiffersFrom, ifVersionDiffersFrom, session);
+                if (result.getStatus() != TemplateLoadingResultStatus.NOT_FOUND) {
+                    return result;
+                }
+            }
+        }
+
+        // If there is no affine loader, or it could not find the resource
+        // again, try all loaders in order of appearance. If any manages
+        // to find the resource, then associate it as the new affine loader
+        // for this resource.
+        for (TemplateLoader templateLoader : templateLoaders) {
+            if (lastLoader != templateLoader) {
+                TemplateLoadingResult result = templateLoader.load(
+                        name, ifSourceDiffersFrom, ifVersionDiffersFrom, session);
+                if (result.getStatus() != TemplateLoadingResultStatus.NOT_FOUND) {
+                    if (sticky) {
+                        lastTemplateLoaderForName.put(name, templateLoader);
+                    }
+                    return result;
+                }
+            }
+        }
+
+        if (sticky) {
+            lastTemplateLoaderForName.remove(name);
+        }
+        return TemplateLoadingResult.NOT_FOUND;
+    }
 
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/StatefulTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/StatefulTemplateLoader.java b/src/main/java/freemarker/cache/StatefulTemplateLoader.java
deleted file mode 100644
index 0e0a21c..0000000
--- a/src/main/java/freemarker/cache/StatefulTemplateLoader.java
+++ /dev/null
@@ -1,35 +0,0 @@
-/*
- * 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.cache;
-
-import freemarker.template.Configuration;
-
-/**
- * Interface that can be implemented by {@link TemplateLoader}-s that maintain some 
- * sort of internal state (i.e. caches of earlier lookups for performance 
- * optimization purposes etc.) and support resetting of their state. 
- */
-public interface StatefulTemplateLoader extends TemplateLoader {
-    /**
-     * Invoked by {@link Configuration#clearTemplateCache()} to instruct this
-     * template loader to throw away its current state and start afresh. 
-     */
-    public void resetState();
-}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/StringTemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/StringTemplateLoader.java b/src/main/java/freemarker/cache/StringTemplateLoader.java
index 8b8bd4a..34f568a 100644
--- a/src/main/java/freemarker/cache/StringTemplateLoader.java
+++ b/src/main/java/freemarker/cache/StringTemplateLoader.java
@@ -19,147 +19,97 @@
 
 package freemarker.cache;
 
-import java.io.Reader;
+import java.io.IOException;
+import java.io.ObjectOutputStream;
+import java.io.Serializable;
 import java.io.StringReader;
-import java.util.HashMap;
-import java.util.Iterator;
 import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ConcurrentMap;
+import java.util.concurrent.atomic.AtomicLong;
 
 import freemarker.template.utility.StringUtil;
 
 /**
- * A {@link TemplateLoader} that uses a {@link Map} with {@link String}-s as its source of 
- * templates.
- *
- * In most case the regular way of loading templates from files will be fine.
- * However, there can be situations where you don't want to or can't load a
- * template from a file, e.g. if you have to deploy a single jar for 
- * JavaWebStart or if they are contained within a database.
- * A single template can be created manually
- * e.g.
- * <pre>
- *   String templateStr="Hello ${user}";
- *   Template t = new Template("name", new StringReader(templateStr),
- *               new Configuration());
- * </pre>
- * If, however, you want to create templates from strings which import other 
- * templates this method doesn't work.
- *
- * In that case you can create a StringTemplateLoader and add each template to 
- * it:
- * <pre>
- *   StringTemplateLoader stringLoader = new StringTemplateLoader();
- *   stringLoader.putTemplate("greetTemplate", "&lt;#macro greet&gt;Hello&lt;/#macro&gt;");
- *   stringLoader.putTemplate("myTemplate", "&lt;#include \"greetTemplate\"&gt;&lt;@greet/&gt; World!");
- * </pre>
- * Then you tell your Configuration object to use it:
- * <pre>
- *   cfg.setTemplateLoader(stringLoader);
- * </pre>
- * After that you should be able to use the templates as usual. Often you will
- * want to combine a <tt>StringTemplateLoader</tt> with another loader. You can
- * do so using a {@link freemarker.cache.MultiTemplateLoader}.
+ * A {@link TemplateLoader} that uses a {@link Map} with {@code String} as its source of templates. This is similar to
+ * {@link StringTemplateLoader}, but uses {@code String} instead of {@link String}; see more details there.
+ * 
+ * <p>Note that {@link StringTemplateLoader} can't be used with a distributed (cluster-wide) {@link CacheStorage},
+ * as it produces {@link TemplateLoadingSource}-s that deliberately throw exception on serialization (because the
+ * content is only accessible within a single JVM, and is also volatile).
  */
+// TODO JUnit tests
 public class StringTemplateLoader implements TemplateLoader {
     
-    private final Map<String, StringTemplateSource> templates = new HashMap<String, StringTemplateSource>();
+    private static final AtomicLong INSTANCE_COUNTER = new AtomicLong();
     
-    /**
-     * Puts a template into the loader. A call to this method is identical to 
-     * the call to the three-arg {@link #putTemplate(String, String, long)} 
-     * passing <tt>System.currentTimeMillis()</tt> as the third argument.
-     * @param name the name of the template.
-     * @param templateSource the source code of the template.
-     */
-    public void putTemplate(String name, String templateSource) {
-        putTemplate(name, templateSource, System.currentTimeMillis());
-    }
+    private final long instanceId = INSTANCE_COUNTER.get();
+    private final AtomicLong templatesRevision = new AtomicLong();
+    private final ConcurrentMap<String, ContentHolder> templates = new ConcurrentHashMap<>();
     
     /**
-     * Puts a template into the loader. The name can contain slashes to denote
-     * logical directory structure, but must not start with a slash. If the 
-     * method is called multiple times for the same name and with different
-     * last modified time, the configuration's template cache will reload the 
-     * template according to its own refresh settings (note that if the refresh 
-     * is disabled in the template cache, the template will not be reloaded).
-     * Also, since the cache uses lastModified to trigger reloads, calling the
-     * method with different source and identical timestamp won't trigger
-     * reloading.
-     * @param name the name of the template.
-     * @param templateSource the source code of the template.
-     * @param lastModified the time of last modification of the template in 
-     * terms of <tt>System.currentTimeMillis()</tt>
+     * Puts a template into the template loader. The name can contain slashes to denote logical directory structure, but
+     * must not start with a slash. Each template will get an unique revision number, thus replacing a template will
+     * cause the template cache to reload it (when the update delay expires).
+     * 
+     * <p>This method is thread-safe.
+     * 
+     * @param name
+     *            the name of the template.
+     * @param content
+     *            the source code of the template.
      */
-    public void putTemplate(String name, String templateSource, long lastModified) {
-        templates.put(name, new StringTemplateSource(name, templateSource, lastModified));
+    public void putTemplate(String name, String content) {
+        templates.put(
+                name,
+                new ContentHolder(content, new Source(instanceId, name), templatesRevision.incrementAndGet()));
     }
     
     /**
      * Removes the template with the specified name if it was added earlier.
      * 
-     * @param name Exactly the key with which the template was added.
+     * <p>
+     * This method is thread-safe.
      * 
-     * @return Whether a template was found with the given key (and hence was removed now) 
+     * @param name
+     *            Exactly the key with which the template was added.
      * 
-     * @since 2.3.24
-     */
+     * @return Whether a template was found with the given key (and hence was removed now)
+     */ 
     public boolean removeTemplate(String name) {
         return templates.remove(name) != null;
     }
     
-    public void closeTemplateSource(Object templateSource) {
-    }
-    
-    public Object findTemplateSource(String name) {
-        return templates.get(name);
-    }
-    
-    public long getLastModified(Object templateSource) {
-        return ((StringTemplateSource) templateSource).lastModified;
-    }
-    
-    public Reader getReader(Object templateSource, String encoding) {
-        return new StringReader(((StringTemplateSource) templateSource).source);
+    @Override
+    public TemplateLoaderSession createSession() {
+        return null;
     }
-    
-    private static class StringTemplateSource {
-        private final String name;
-        private final String source;
-        private final long lastModified;
-        
-        StringTemplateSource(String name, String source, long lastModified) {
-            if (name == null) {
-                throw new IllegalArgumentException("name == null");
-            }
-            if (source == null) {
-                throw new IllegalArgumentException("source == null");
-            }
-            if (lastModified < -1L) {
-                throw new IllegalArgumentException("lastModified < -1L");
-            }
-            this.name = name;
-            this.source = source;
-            this.lastModified = lastModified;
-        }
-        
-        @Override
-        public boolean equals(Object obj) {
-            if (obj instanceof StringTemplateSource) {
-                return name.equals(((StringTemplateSource) obj).name);
-            }
-            return false;
-        }
-        
-        @Override
-        public int hashCode() {
-            return name.hashCode();
+
+    @Override
+    public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom,
+            Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws IOException {
+        ContentHolder contentHolder = templates.get(name);
+        if (contentHolder == null) {
+            return TemplateLoadingResult.NOT_FOUND;
+        } else if (ifSourceDiffersFrom != null && ifSourceDiffersFrom.equals(contentHolder.source)
+                && Objects.equals(ifVersionDiffersFrom, contentHolder.version)) {
+            return TemplateLoadingResult.NOT_MODIFIED;
+        } else {
+            return new TemplateLoadingResult(
+                    contentHolder.source, contentHolder.version,
+                    new StringReader(contentHolder.content),
+                    null);
         }
     }
-    
+
+    @Override
+    public void resetState() {
+        // Do nothing
+    }
+
     /**
      * Show class name and some details that are useful in template-not-found errors.
-     * 
-     * @since 2.3.21
      */
     @Override
     public String toString() {
@@ -167,7 +117,7 @@ public class StringTemplateLoader implements TemplateLoader {
         sb.append(TemplateLoaderUtils.getClassNameForToString(this));
         sb.append("(Map { ");
         int cnt = 0;
-        for (Iterator it = templates.keySet().iterator(); it.hasNext(); ) {
+        for (String name : templates.keySet()) {
             cnt++;
             if (cnt != 1) {
                 sb.append(", ");
@@ -176,7 +126,7 @@ public class StringTemplateLoader implements TemplateLoader {
                 sb.append("...");
                 break;
             }
-            sb.append(StringUtil.jQuote(it.next()));
+            sb.append(StringUtil.jQuote(name));
             sb.append("=...");
         }
         if (cnt != 0) {
@@ -185,5 +135,60 @@ public class StringTemplateLoader implements TemplateLoader {
         sb.append("})");
         return sb.toString();
     }
+
+    private static class ContentHolder {
+        private final String content;
+        private final Source source;
+        private final long version;
+        
+        public ContentHolder(String content, Source source, long version) {
+            this.content = content;
+            this.source = source;
+            this.version = version;
+        }
+        
+    }
+    
+    @SuppressWarnings("serial")
+    private static class Source implements TemplateLoadingSource {
+        
+        private final long instanceId;
+        private final String name;
+        
+        public Source(long instanceId, String name) {
+            this.instanceId = instanceId;
+            this.name = name;
+        }
+    
+        @Override
+        public int hashCode() {
+            final int prime = 31;
+            int result = 1;
+            result = prime * result + (int) (instanceId ^ (instanceId >>> 32));
+            result = prime * result + ((name == null) ? 0 : name.hashCode());
+            return result;
+        }
+    
+        @Override
+        public boolean equals(Object obj) {
+            if (this == obj) return true;
+            if (obj == null) return false;
+            if (getClass() != obj.getClass()) return false;
+            Source other = (Source) obj;
+            if (instanceId != other.instanceId) return false;
+            if (name == null) {
+                if (other.name != null) return false;
+            } else if (!name.equals(other.name)) {
+                return false;
+            }
+            return true;
+        }
+        
+        private void writeObject(ObjectOutputStream out) throws IOException {
+            throw new IOException(StringTemplateLoader.class.getName()
+                    + " sources can't be serialized, as they don't support clustering.");
+        }
+        
+    }
     
 }


[4/5] incubator-freemarker git commit: - Totally redesigned TemplateLoader interface. The FM2 TemplateLoader can't be adapted (wrapped) to it, but usually

Posted by dd...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateCache.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateCache.java b/src/main/java/freemarker/cache/TemplateCache.java
index fa8df50..d545986 100644
--- a/src/main/java/freemarker/cache/TemplateCache.java
+++ b/src/main/java/freemarker/cache/TemplateCache.java
@@ -19,12 +19,13 @@
 
 package freemarker.cache;
 
+import java.io.BufferedInputStream;
 import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
 import java.io.Reader;
 import java.io.Serializable;
-import java.io.StringWriter;
 import java.lang.reflect.Method;
-import java.net.URLConnection;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
@@ -33,10 +34,11 @@ import java.util.StringTokenizer;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-import freemarker.cache.MultiTemplateLoader.MultiSource;
 import freemarker.core.BugException;
 import freemarker.core.Environment;
+import freemarker.core.MarkReleaserTemplateSpecifiedEncodingHandler;
 import freemarker.core.TemplateConfiguration;
+import freemarker.core.TemplateSpecifiedEncodingHandler;
 import freemarker.template.Configuration;
 import freemarker.template.MalformedTemplateNameException;
 import freemarker.template.Template;
@@ -76,12 +78,12 @@ public class TemplateCache {
     private final TemplateLoader templateLoader;
     
     /** Here we keep our cached templates */
-    private final CacheStorage storage;
+    private final CacheStorage cacheStorage;
     private final TemplateLookupStrategy templateLookupStrategy;
     private final TemplateNameFormat templateNameFormat;
     private final TemplateConfigurationFactory templateConfigurations;
     
-    private final boolean isStorageConcurrent;
+    private final boolean isCacheStorageConcurrent;
     /** {@link Configuration#setTemplateUpdateDelayMilliseconds(long)} */
     private long updateDelay = DEFAULT_TEMPLATE_UPDATE_DELAY_MILLIS;
     /** {@link Configuration#setLocalizedLookup(boolean)} */
@@ -90,35 +92,6 @@ public class TemplateCache {
     private Configuration config;
 
     /**
-     * Returns a template cache that will first try to load a template from
-     * the file system relative to the current user directory (i.e. the value
-     * of the system property <code>user.dir</code>), then from the classpath.
-     * 
-     * @deprecated Use {@link #TemplateCache(TemplateLoader)} instead. The default loader is useless in most
-     *     applications, also it can mean a security risk.
-     */
-    @Deprecated
-    public TemplateCache() {
-        this(_TemplateAPI.createDefaultTemplateLoader(Configuration.VERSION_2_3_0));
-    }
-
-    /**
-     * @deprecated Use {@link #TemplateCache(TemplateLoader, CacheStorage, Configuration)} instead.
-     */
-    @Deprecated
-    public TemplateCache(TemplateLoader templateLoader) {
-        this(templateLoader, (Configuration) null);
-    }
-
-    /**
-     * @deprecated Use {@link #TemplateCache(TemplateLoader, CacheStorage, Configuration)} instead.
-     */
-    @Deprecated
-    public TemplateCache(TemplateLoader templateLoader, CacheStorage cacheStorage) {
-        this(templateLoader, cacheStorage, null);
-    }
-
-    /**
      * Same as {@link #TemplateCache(TemplateLoader, CacheStorage, Configuration)} with a new {@link SoftCacheStorage}
      * as the 2nd parameter.
      * 
@@ -157,7 +130,8 @@ public class TemplateCache {
 
     /**
      * @param templateLoader
-     *            The {@link TemplateLoader} to use. Can't be {@code null}.
+     *            The {@link TemplateLoader} to use. Can be {@code null}, though than you won't be able to load
+     *            anything.
      * @param cacheStorage
      *            The {@link CacheStorage} to use. Can't be {@code null}.
      * @param templateLookupStrategy
@@ -166,10 +140,10 @@ public class TemplateCache {
      *            The {@link TemplateNameFormat} to use. Can't be {@code null}.
      * @param templateConfigurations
      *            The {@link TemplateConfigurationFactory} to use. Can be {@code null} (then all templates will use the
-     *            settings coming from the {@link Configuration} as is).
+     *            settings coming from the {@link Configuration} as is, except in the very rare case where a
+     *            {@link TemplateLoader} itself specifies a {@link TemplateConfiguration}).
      * @param config
-     *            The {@link Configuration} this cache will be used for. Can be {@code null} for backward compatibility,
-     *            as it can be set with {@link #setConfiguration(Configuration)} later.
+     *            The {@link Configuration} this cache will be used for. Can't be {@code null}.
      * 
      * @since 2.3.24
      */
@@ -180,8 +154,8 @@ public class TemplateCache {
         this.templateLoader = templateLoader;
         
         NullArgumentException.check("cacheStorage", cacheStorage);
-        this.storage = cacheStorage;
-        isStorageConcurrent = cacheStorage instanceof ConcurrentCacheStorage &&
+        this.cacheStorage = cacheStorage;
+        isCacheStorageConcurrent = cacheStorage instanceof ConcurrentCacheStorage &&
                 ((ConcurrentCacheStorage) cacheStorage).isConcurrent();
         
         NullArgumentException.check("templateLookupStrategy", templateLookupStrategy);
@@ -193,28 +167,24 @@ public class TemplateCache {
         // Can be null
         this.templateConfigurations = templateConfigurations;
         
+        NullArgumentException.check("config", config);
         this.config = config;
     }
     
     /**
-     * Sets the configuration object to which this cache belongs. This
-     * method is called by the configuration itself to establish the
-     * relation, and should not be called by users.
-     * 
-     * @deprecated Use the {@link #TemplateCache(TemplateLoader, CacheStorage, Configuration)} constructor.
+     * Returns the configuration for internal usage.
      */
-    @Deprecated
-    public void setConfiguration(Configuration config) {
-        this.config = config;
-        clear();
+    // [FM3] After setConfiguration was removed, this can be too.
+    Configuration getConfiguration() {
+        return config;
     }
 
     public TemplateLoader getTemplateLoader() {
         return templateLoader;
     }
-    
+
     public CacheStorage getCacheStorage() {
-        return storage;
+        return cacheStorage;
     }
     
     /**
@@ -287,12 +257,12 @@ public class TemplateCache {
         }
         
         if (templateLoader == null) {
-            return new MaybeMissingTemplate(name, "The TemplateLoader was null.");
+            return new MaybeMissingTemplate(name, "The TemplateLoader (and TemplateLoader2) was null.");
         }
         
         Template template = getTemplateInternal(name, locale, customLookupCondition, encoding, parseAsFTL);
         return template != null ? new MaybeMissingTemplate(template) : new MaybeMissingTemplate(name, (String) null);
-    }    
+    }
 
     /**
      * Similar to {@link #getTemplate(String, Locale, Object, String, boolean)} with {@code null}
@@ -310,158 +280,236 @@ public class TemplateCache {
         return getTemplate(name, locale, null, encoding, parseAsFTL).getTemplate();
     }
     
-    /**
-     * Returns the deprecated default template loader of FreeMarker 2.3.0.
-     * 
-     * @deprecated The {@link TemplateLoader} should be always specified by the constructor caller.
-     */
-    @Deprecated
-    protected static TemplateLoader createLegacyDefaultTemplateLoader() {
-        return _TemplateAPI.createDefaultTemplateLoader(Configuration.VERSION_2_3_0);        
-    }
-    
     private Template getTemplateInternal(
             final String name, final Locale locale, final Object customLookupCondition,
             final String encoding, final boolean parseAsFTL)
     throws IOException {
         final boolean debug = LOG.isDebugEnabled();
-        final String debugName = debug
-                ? buildDebugName(name, locale, customLookupCondition, encoding, parseAsFTL)
+        final String debugPrefix = debug
+                ? getDebugPrefix("getTemplate", name, locale, customLookupCondition, encoding, parseAsFTL)
                 : null;
-        final TemplateKey tk = new TemplateKey(name, locale, customLookupCondition, encoding, parseAsFTL);
+        final CachedResultKey cacheKey = new CachedResultKey(name, locale, customLookupCondition, encoding, parseAsFTL);
         
-        CachedTemplate cachedTemplate;
-        if (isStorageConcurrent) {
-            cachedTemplate = (CachedTemplate) storage.get(tk);
+        CachedResult oldCachedResult;
+        if (isCacheStorageConcurrent) {
+            oldCachedResult = (CachedResult) cacheStorage.get(cacheKey);
         } else {
-            synchronized (storage) {
-                cachedTemplate = (CachedTemplate) storage.get(tk);
+            synchronized (cacheStorage) {
+                oldCachedResult = (CachedResult) cacheStorage.get(cacheKey);
             }
         }
         
         final long now = System.currentTimeMillis();
         
-        long lastModified = -1L;
-        boolean rethrown = false;
+        boolean rethrownCachedException = false;
+        boolean suppressFinallyException = false;
         TemplateLookupResult newLookupResult = null;
+        CachedResult newCachedResult = null;
+        TemplateLoaderSession session = null;
         try {
-            if (cachedTemplate != null) {
-                // If we're within the refresh delay, return the cached copy
-                if (now - cachedTemplate.lastChecked < updateDelay) {
+            if (oldCachedResult != null) {
+                // If we're within the refresh delay, return the cached result
+                if (now - oldCachedResult.lastChecked < updateDelay) {
                     if (debug) {
-                        LOG.debug(debugName + " cached copy not yet stale; using cached.");
+                        LOG.debug(debugPrefix + "Cached copy not yet stale; using cached.");
                     }
-                    // Can be null, indicating a cached negative lookup
-                    Object t = cachedTemplate.templateOrException;
+                    Object t = oldCachedResult.templateOrException;
+                    // t can be null, indicating a cached negative lookup
                     if (t instanceof Template || t == null) {
                         return (Template) t;
                     } else if (t instanceof RuntimeException) {
-                        throwLoadFailedException((RuntimeException) t);
+                        rethrowCachedException((RuntimeException) t);
                     } else if (t instanceof IOException) {
-                        rethrown = true;
-                        throwLoadFailedException((IOException) t);
+                        rethrownCachedException = true;
+                        rethrowCachedException((IOException) t);
                     }
-                    throw new BugException("t is " + t.getClass().getName());
+                    throw new BugException("Unhandled class for t: " + t.getClass().getName());
                 }
+                // The freshness of the cache result must be checked.
                 
-                // Clone as the instance bound to the map should be treated as
-                // immutable to ensure proper concurrent semantics
-                cachedTemplate = cachedTemplate.cloneCachedTemplate();
-                // Update the last-checked flag
-                cachedTemplate.lastChecked = now;
+                // Clone, as the instance in the cache store must not be modified to ensure proper concurrent behavior.
+                newCachedResult = oldCachedResult.clone();
+                newCachedResult.lastChecked = now;
 
-                // Find the template source
-                newLookupResult = lookupTemplate(name, locale, customLookupCondition);
+                session = templateLoader.createSession();
+                if (debug && session != null) {
+                    LOG.debug(debugPrefix + "Session created.");
+                }
+                
+                // Find the template source, load it if it doesn't correspond to the cached result.
+                newLookupResult = lookupAndLoadTemplateIfChanged(
+                        name, locale, customLookupCondition, oldCachedResult.source, oldCachedResult.version, session);
 
-                // Template source was removed
-                if (!newLookupResult.isPositive()) {
+                // Template source was removed (TemplateLoader2ResultStatus.NOT_FOUND, or no TemplateLoader2Result)
+                if (!newLookupResult.isPositive()) { 
                     if (debug) {
-                        LOG.debug(debugName + " no source found.");
+                        LOG.debug(debugPrefix + "No source found.");
                     } 
-                    storeNegativeLookup(tk, cachedTemplate, null);
+                    setToNegativeAndPutIntoCache(cacheKey, newCachedResult, null);
                     return null;
                 }
 
-                // If the source didn't change and its last modified date
-                // also didn't change, return the cached version.
-                final Object newLookupResultSource = newLookupResult.getTemplateSource();
-                lastModified = templateLoader.getLastModified(newLookupResultSource);
-                boolean lastModifiedNotChanged = lastModified == cachedTemplate.lastModified;
-                boolean sourceEquals = newLookupResultSource.equals(cachedTemplate.source);
-                if (lastModifiedNotChanged && sourceEquals) {
+                final TemplateLoadingResult newTemplateLoaderResult = newLookupResult.getTemplateLoaderResult();
+                if (newTemplateLoaderResult.getStatus() == TemplateLoadingResultStatus.NOT_MODIFIED) {
+                    // Return the cached version.
                     if (debug) {
-                        LOG.debug(debugName + ": using cached since " + newLookupResultSource + " hasn't changed.");
+                        LOG.debug(debugPrefix + ": Using cached template "
+                                + "(source: " + newTemplateLoaderResult.getSource() + ")"
+                                + " as it hasn't been changed on the backing store.");
                     }
-                    storeCached(tk, cachedTemplate);
-                    return (Template) cachedTemplate.templateOrException;
-                } else if (debug) {
-                    if (!sourceEquals) {
-                        LOG.debug("Updating source because: " + 
-                            "sourceEquals=" + sourceEquals + 
-                            ", newlyFoundSource=" + StringUtil.jQuoteNoXSS(newLookupResultSource) + 
-                            ", cached.source=" + StringUtil.jQuoteNoXSS(cachedTemplate.source));
-                    } else if (!lastModifiedNotChanged) {
-                        LOG.debug("Updating source because: " + 
-                            "lastModifiedNotChanged=" + lastModifiedNotChanged + 
-                            ", cached.lastModified=" + cachedTemplate.lastModified + 
-                            " != source.lastModified=" + lastModified);
+                    putIntoCache(cacheKey, newCachedResult);
+                    return (Template) newCachedResult.templateOrException;
+                } else {
+                    if (newTemplateLoaderResult.getStatus() != TemplateLoadingResultStatus.OPENED) {
+                        // TemplateLoader2ResultStatus.NOT_FOUND was already handler earlier
+                        throw new BugException("Unxpected status: " + newTemplateLoaderResult.getStatus());
+                    }
+                    if (debug) {
+                        StringBuilder debugMsg = new StringBuilder();
+                        debugMsg.append(debugPrefix)
+                                .append("Reloading template instead of using the cached result because ");
+                        if (newCachedResult.templateOrException instanceof Throwable) {
+                            debugMsg.append("it's a cached error (retrying).");
+                        } else {
+                            Object newSource = newTemplateLoaderResult.getSource();
+                            if (!nullSafeEquals(newSource, oldCachedResult.source)) {
+                                debugMsg.append("the source has been changed: ")
+                                        .append("cached.source=").append(StringUtil.jQuoteNoXSS(oldCachedResult.source))
+                                        .append(", current.source=").append(StringUtil.jQuoteNoXSS(newSource));
+                            } else {
+                                Serializable newVersion = newTemplateLoaderResult.getVersion();
+                                if (!nullSafeEquals(oldCachedResult.version, newVersion)) {
+                                    debugMsg.append("the version has been changed: ")
+                                            .append("cached.version=").append(oldCachedResult.version) 
+                                            .append(", current.version=").append(newVersion);
+                                } else {
+                                    debugMsg.append("??? (unknown reason)");
+                                }
+                            }
+                        }
+                        LOG.debug(debugMsg.toString());
                     }
                 }
-            } else {
+            } else { // if there was no cached result
                 if (debug) {
-                    LOG.debug("Couldn't find template in cache for " + debugName + "; will try to load it.");
+                    LOG.debug(debugPrefix + "No cached result was found; will try to load template.");
                 }
                 
-                // Construct a new CachedTemplate entry. Note we set the
-                // cachedTemplate.lastModified to Long.MIN_VALUE. This is
-                // a flag that signs it has to be explicitly queried later on.
-                cachedTemplate = new CachedTemplate();
-                cachedTemplate.lastChecked = now;
+                newCachedResult = new CachedResult();
+                newCachedResult.lastChecked = now;
+            
+                session = templateLoader.createSession();
+                if (debug && session != null) {
+                    LOG.debug(debugPrefix + "Session created.");
+                } 
                 
-                newLookupResult = lookupTemplate(name, locale, customLookupCondition);
+                newLookupResult = lookupAndLoadTemplateIfChanged(
+                        name, locale, customLookupCondition, null, null, session);
                 
                 if (!newLookupResult.isPositive()) {
-                    storeNegativeLookup(tk, cachedTemplate, null);
+                    setToNegativeAndPutIntoCache(cacheKey, newCachedResult, null);
                     return null;
                 }
-                
-                cachedTemplate.lastModified = lastModified = Long.MIN_VALUE;
             }
+            // We have newCachedResult and newLookupResult initialized at this point.
 
-            Object source = newLookupResult.getTemplateSource();
-            cachedTemplate.source = source;
+            TemplateLoadingResult templateLoaderResult = newLookupResult.getTemplateLoaderResult();
+            newCachedResult.source = templateLoaderResult.getSource();
             
             // If we get here, then we need to (re)load the template
             if (debug) {
-                LOG.debug("Loading template for " + debugName + " from " + StringUtil.jQuoteNoXSS(source));
+                LOG.debug(debugPrefix + "Reading template content (source: "
+                        + StringUtil.jQuoteNoXSS(newCachedResult.source) + ")");
             }
             
-            lastModified = lastModified == Long.MIN_VALUE ? templateLoader.getLastModified(source) : lastModified;            
             Template template = loadTemplate(
-                    templateLoader, source,
+                    templateLoaderResult,
                     name, newLookupResult.getTemplateSourceName(), locale, customLookupCondition,
                     encoding, parseAsFTL);
-            cachedTemplate.templateOrException = template;
-            cachedTemplate.lastModified = lastModified;
-            storeCached(tk, cachedTemplate);
+            if (session != null) {
+                session.close();
+                if (debug) {
+                    LOG.debug(debugPrefix + "Session closed.");
+                } 
+            }
+            newCachedResult.templateOrException = template;
+            newCachedResult.version = templateLoaderResult.getVersion();
+            putIntoCache(cacheKey, newCachedResult);
             return template;
         } catch (RuntimeException e) {
-            if (cachedTemplate != null) {
-                storeNegativeLookup(tk, cachedTemplate, e);
+            if (newCachedResult != null) {
+                setToNegativeAndPutIntoCache(cacheKey, newCachedResult, e);
             }
+            suppressFinallyException = true;
             throw e;
         } catch (IOException e) {
-            if (!rethrown) {
-                storeNegativeLookup(tk, cachedTemplate, e);
+            // Rethrown cached exceptions are wrapped into IOException-s, so we only need this condition here.
+            if (!rethrownCachedException) {
+                setToNegativeAndPutIntoCache(cacheKey, newCachedResult, e);
             }
+            suppressFinallyException = true;
             throw e;
         } finally {
-            if (newLookupResult != null && newLookupResult.isPositive()) {
-                templateLoader.closeTemplateSource(newLookupResult.getTemplateSource());
+            try {
+                // Close streams first:
+                
+                if (newLookupResult != null && newLookupResult.isPositive()) {
+                    TemplateLoadingResult templateLoaderResult = newLookupResult.getTemplateLoaderResult();
+                    Reader reader = templateLoaderResult.getReader();
+                    if (reader != null) {
+                        try {
+                            reader.close();
+                        } catch (IOException e) { // [FM3] Exception e
+                            if (suppressFinallyException) {
+                                if (LOG.isWarnEnabled()) { 
+                                    LOG.warn("Failed to close template content Reader for: " + name, e);
+                                }
+                            } else {
+                                suppressFinallyException = true;
+                                throw e;
+                            }
+                        }
+                    } else if (templateLoaderResult.getInputStream() != null) {
+                        try {
+                            templateLoaderResult.getInputStream().close();
+                        } catch (IOException e) { // [FM3] Exception e
+                            if (suppressFinallyException) {
+                                if (LOG.isWarnEnabled()) { 
+                                    LOG.warn("Failed to close template content InputStream for: " + name, e);
+                                }
+                            } else {
+                                suppressFinallyException = true;
+                                throw e;
+                            }
+                        }
+                    }
+                }
+            } finally {
+                // Then close streams:
+                
+                if (session != null && !session.isClosed()) {
+                    try {
+                        session.close();
+                        if (debug) {
+                            LOG.debug(debugPrefix + "Session closed.");
+                        } 
+                    } catch (IOException e) { // [FM3] Exception e
+                        if (suppressFinallyException) {
+                            if (LOG.isWarnEnabled()) { 
+                                LOG.warn("Failed to close template loader session for" + name, e);
+                            }
+                        } else {
+                            suppressFinallyException = true;
+                            throw e;
+                        }
+                    }
+                }
             }
         }
     }
 
+    
+    
     private static final Method INIT_CAUSE = getInitCauseMethod();
     
     private static final Method getInitCauseMethod() {
@@ -498,39 +546,59 @@ public class TemplateCache {
         return ioe;
     }
     
-    private void throwLoadFailedException(Throwable e) throws IOException {
+    private void rethrowCachedException(Throwable e) throws IOException {
         throw newIOException("There was an error loading the " +
                 "template on an earlier attempt; see cause exception.", e);
     }
 
-    private void storeNegativeLookup(TemplateKey tk, 
-            CachedTemplate cachedTemplate, Exception e) {
-        cachedTemplate.templateOrException = e;
-        cachedTemplate.source = null;
-        cachedTemplate.lastModified = 0L;
-        storeCached(tk, cachedTemplate);
+    private void setToNegativeAndPutIntoCache(CachedResultKey cacheKey, CachedResult cachedResult, Exception e) {
+        cachedResult.templateOrException = e;
+        cachedResult.source = null;
+        cachedResult.version = null;
+        putIntoCache(cacheKey, cachedResult);
     }
 
-    private void storeCached(TemplateKey tk, CachedTemplate cachedTemplate) {
-        if (isStorageConcurrent) {
-            storage.put(tk, cachedTemplate);
+    private void putIntoCache(CachedResultKey tk, CachedResult cachedTemplate) {
+        if (isCacheStorageConcurrent) {
+            cacheStorage.put(tk, cachedTemplate);
         } else {
-            synchronized (storage) {
-                storage.put(tk, cachedTemplate);
+            synchronized (cacheStorage) {
+                cacheStorage.put(tk, cachedTemplate);
             }
         }
     }
 
+    @SuppressWarnings("deprecation")
     private Template loadTemplate(
-            final TemplateLoader templateLoader, final Object source,
+            TemplateLoadingResult templateLoaderResult,
             final String name, final String sourceName, Locale locale, final Object customLookupCondition,
             String initialEncoding, final boolean parseAsFTL) throws IOException {
-        final TemplateConfiguration tc;
-        try {
-            tc = templateConfigurations != null ? templateConfigurations.get(sourceName, source) : null;
-        } catch (TemplateConfigurationFactoryException e) {
-            throw newIOException("Error while getting TemplateConfiguration; see cause exception.", e);
+        TemplateConfiguration tc;
+        {
+            TemplateConfiguration cfgTC;
+            try {
+                cfgTC = templateConfigurations != null
+                        ? templateConfigurations.get(sourceName, templateLoaderResult.getSource()) : null;
+            } catch (TemplateConfigurationFactoryException e) {
+                throw newIOException("Error while getting TemplateConfiguration; see cause exception.", e);
+            }
+            TemplateConfiguration resultTC = templateLoaderResult.getTemplateConfiguration();
+            if (resultTC != null) {
+                TemplateConfiguration mergedTC = new TemplateConfiguration();
+                if (cfgTC != null) {
+                    mergedTC.merge(cfgTC);
+                }
+                if (resultTC != null) {
+                    mergedTC.merge(resultTC);
+                }
+                mergedTC.setParentConfiguration(config);
+                
+                tc = mergedTC;
+            } else {
+                tc = cfgTC;
+            }
         }
+        
         if (tc != null) {
             // TC.{encoding,locale} is stronger than the cfg.getTemplate arguments by design.
             if (tc.isEncodingSet()) {
@@ -543,47 +611,70 @@ public class TemplateCache {
         
         Template template;
         {
-            if (parseAsFTL) {
-                try {
-                    final Reader reader = templateLoader.getReader(source, initialEncoding);
-                    try {
-                        template = new Template(name, sourceName, reader, config, tc, initialEncoding);
-                    } finally {
-                        reader.close();
-                    }
-                } catch (Template.WrongEncodingException wee) {
-                    String actualEncoding = wee.getTemplateSpecifiedEncoding();
-                    if (LOG.isDebugEnabled()) {
-                        LOG.debug("Initial encoding \"" + initialEncoding + "\" was incorrect, re-reading with \""
-                                + actualEncoding + "\". Template: " + sourceName);
-                    }
-                    
-                    final Reader reader = templateLoader.getReader(source, actualEncoding);
-                    try {
-                        template = new Template(name, sourceName, reader, config, tc, actualEncoding);
-                    } finally {
-                        reader.close();
+            Reader reader = templateLoaderResult.getReader();
+            InputStream inputStream = templateLoaderResult.getInputStream();
+            TemplateSpecifiedEncodingHandler templateSpecifiedEncodingHandler;
+            if (reader != null) {
+                if (inputStream != null) {
+                    throw new IllegalStateException("For a(n) " + templateLoaderResult.getClass().getName()
+                            + ", both getReader() and getInputStream() has returned non-null.");
+                }
+                initialEncoding = null;  // No charset decoding has happened
+                templateSpecifiedEncodingHandler = TemplateSpecifiedEncodingHandler.DEFAULT; 
+            } else if (inputStream != null) {
+                if (parseAsFTL) {
+                    // We need mark support, to restart if the charset suggested by <#ftl encoding=...> differs
+                    // from that we use initially.
+                    if (!inputStream.markSupported()) {
+                        inputStream = new BufferedInputStream(inputStream);
                     }
+                    inputStream.mark(Integer.MAX_VALUE); // [FM3] Mark should be released after the 1st FTL tag
+                    templateSpecifiedEncodingHandler = new MarkReleaserTemplateSpecifiedEncodingHandler(
+                            inputStream);
+                } else {
+                    templateSpecifiedEncodingHandler = null; 
                 }
+                reader = new InputStreamReader(inputStream, initialEncoding);
             } else {
-                // Read the contents into a StringWriter, then construct a single-text-block template from it.
-                final StringWriter sw = new StringWriter();
-                final char[] buf = new char[4096];
-                final Reader reader = templateLoader.getReader(source, initialEncoding);
-                try {
-                    fetchChars: while (true) {
-                        int charsRead = reader.read(buf);
-                        if (charsRead > 0) {
-                            sw.write(buf, 0, charsRead);
-                        } else if (charsRead < 0) {
-                            break fetchChars;
+                throw new IllegalStateException("For a(n) " + templateLoaderResult.getClass().getName()
+                        + ", both getReader() and getInputStream() has returned null.");
+            }
+            
+            try {
+                if (parseAsFTL) {
+                    try {
+                        template = new Template(name, sourceName, reader, config, tc,
+                                initialEncoding, templateSpecifiedEncodingHandler);
+                    } catch (Template.WrongEncodingException wee) {
+                        final String templateSpecifiedEncoding = wee.getTemplateSpecifiedEncoding();
+                        
+                        if (inputStream != null) {
+                            // We restart InputStream to re-decode it with the new charset.
+                            inputStream.reset();
+                            
+                            // Don't close `reader`; it's an InputStreamReader that would close the wrapped InputStream.
+                            reader = new InputStreamReader(inputStream, templateSpecifiedEncoding);
+                        } else {
+                            // Should be impossible to get here
+                            throw new BugException();
                         }
+                        
+                        template = new Template(name, sourceName, reader, config, tc,
+                                templateSpecifiedEncoding, templateSpecifiedEncodingHandler);
+                    }
+                } else {
+                    // Read the contents into a StringWriter, then construct a single-text-block template from it.
+                    final StringBuilder sb = new StringBuilder();
+                    final char[] buf = new char[4096];
+                    int charsRead;
+                    while ((charsRead = reader.read(buf)) > 0) {
+                        sb.append(buf, 0, charsRead);
                     }
-                } finally {
-                    reader.close();
+                    template = Template.getPlainTextTemplate(name, sourceName, sb.toString(), config);
+                    template.setEncoding(initialEncoding);
                 }
-                template = Template.getPlainTextTemplate(name, sourceName, sw.toString(), config);
-                template.setEncoding(initialEncoding);
+            } finally {
+                reader.close();
             }
         }
 
@@ -644,17 +735,29 @@ public class TemplateCache {
     }
 
     /**
-     * Removes all entries from the cache, forcing reloading of templates
-     * on subsequent {@link #getTemplate(String, Locale, String, boolean)}
-     * calls. If the configured template loader is 
-     * {@link StatefulTemplateLoader stateful}, then its 
-     * {@link StatefulTemplateLoader#resetState()} method is invoked as well.
+     * Removes all entries from the cache, forcing reloading of templates on subsequent
+     * {@link #getTemplate(String, Locale, String, boolean)} calls.
+     * 
+     * @param resetTemplateLoader
+     *            Whether to call {@link TemplateLoader#resetState()}. on the template loader.
+     */
+    public void clear(boolean resetTemplateLoader) {
+        synchronized (cacheStorage) {
+            cacheStorage.clear();
+            if (templateLoader != null && resetTemplateLoader) {
+                templateLoader.resetState();
+            }
+        }
+    }
+    
+    /**
+     * Same as {@link #clear(boolean)} with {@code true} {@code resetTemplateLoader} argument.
      */
     public void clear() {
-        synchronized (storage) {
-            storage.clear();
-            if (templateLoader instanceof StatefulTemplateLoader) {
-                ((StatefulTemplateLoader) templateLoader).resetState();
+        synchronized (cacheStorage) {
+            cacheStorage.clear();
+            if (templateLoader != null) {
+                templateLoader.resetState();
             }
         }
     }
@@ -691,31 +794,32 @@ public class TemplateCache {
         name = templateNameFormat.normalizeAbsoluteName(name);
         if (name != null && templateLoader != null) {
             boolean debug = LOG.isDebugEnabled();
-            String debugName = debug
-                    ? buildDebugName(name, locale, customLookupCondition, encoding, parse)
+            String debugPrefix = debug
+                    ? getDebugPrefix("removeTemplate", name, locale, customLookupCondition, encoding, parse)
                     : null;
-            TemplateKey tk = new TemplateKey(name, locale, customLookupCondition, encoding, parse);
+            CachedResultKey tk = new CachedResultKey(name, locale, customLookupCondition, encoding, parse);
             
-            if (isStorageConcurrent) {
-                storage.remove(tk);
+            if (isCacheStorageConcurrent) {
+                cacheStorage.remove(tk);
             } else {
-                synchronized (storage) {
-                    storage.remove(tk);
+                synchronized (cacheStorage) {
+                    cacheStorage.remove(tk);
                 }
             }
             if (debug) {
-                LOG.debug(debugName + " was removed from the cache, if it was there");
+                LOG.debug(debugPrefix + "Template was removed from the cache, if it was there");
             }
         }
     }
 
-    private String buildDebugName(String name, Locale locale, Object customLookupCondition, String encoding,
+    private String getDebugPrefix(String operation, String name, Locale locale, Object customLookupCondition, String encoding,
             boolean parse) {
-        return StringUtil.jQuoteNoXSS(name) + "("
+        return operation + " " + StringUtil.jQuoteNoXSS(name) + "("
                 + StringUtil.jQuoteNoXSS(locale)
                 + (customLookupCondition != null ? ", cond=" + StringUtil.jQuoteNoXSS(customLookupCondition) : "")
                 + ", " + encoding
-                + (parse ? ", parsed)" : ", unparsed]");
+                + (parse ? ", parsed)" : ", unparsed]")
+                + ": ";
     }    
 
     /**
@@ -735,110 +839,55 @@ public class TemplateCache {
         }
     }
 
-    private TemplateLookupResult lookupTemplate(String name, Locale locale, Object customLookupCondition)
-            throws IOException {
+    /**
+     * Looks up according the {@link TemplateLookupStrategy} and then starts reading the template, if it was changed
+     * compared to the cached result, or if there was no cached result yet.
+     */
+    private TemplateLookupResult lookupAndLoadTemplateIfChanged(
+            String name, Locale locale, Object customLookupCondition,
+            TemplateLoadingSource cachedResultSource, Serializable cachedResultVersion,
+            TemplateLoaderSession session) throws IOException {
         final TemplateLookupResult lookupResult = templateLookupStrategy.lookup(
-                new TemplateCacheTemplateLookupContext(name, locale, customLookupCondition));
+                new TemplateCacheTemplateLookupContext(
+                        name, locale, customLookupCondition,
+                        cachedResultSource, cachedResultVersion,
+                        session));
         if (lookupResult == null) {
             throw new NullPointerException("Lookup result shouldn't be null");
         }
         return lookupResult;
     }
 
-    private TemplateLookupResult lookupTemplateWithAcquisitionStrategy(String path) throws IOException {
-        int asterisk = path.indexOf(ASTERISK);
-        // Shortcut in case there is no acquisition
-        if (asterisk == -1) {
-            return TemplateLookupResult.from(path, findTemplateSource(path));
-        }
-        StringTokenizer tok = new StringTokenizer(path, "/");
-        int lastAsterisk = -1;
-        List tokpath = new ArrayList();
-        while (tok.hasMoreTokens()) {
-            String pathToken = tok.nextToken();
-            if (pathToken.equals(ASTERISKSTR)) {
-                if (lastAsterisk != -1) {
-                    tokpath.remove(lastAsterisk);
-                }
-                lastAsterisk = tokpath.size();
-            }
-            tokpath.add(pathToken);
-        }
-        if (lastAsterisk == -1) {  // if there was no real "*" step after all
-            return TemplateLookupResult.from(path, findTemplateSource(path));
-        }
-        String basePath = concatPath(tokpath, 0, lastAsterisk);
-        String resourcePath = concatPath(tokpath, lastAsterisk + 1, tokpath.size());
-        if (resourcePath.endsWith("/")) {
-            resourcePath = resourcePath.substring(0, resourcePath.length() - 1);
-        }
-        StringBuilder buf = new StringBuilder(path.length()).append(basePath);
-        int l = basePath.length();
-        for (; ; ) {
-            String fullPath = buf.append(resourcePath).toString();
-            Object templateSource = findTemplateSource(fullPath);
-            if (templateSource != null) {
-                return TemplateLookupResult.from(fullPath, templateSource);
-            }
-            if (l == 0) {
-                return TemplateLookupResult.createNegativeResult();
-            }
-            l = basePath.lastIndexOf(SLASH, l - 2) + 1;
-            buf.setLength(l);
-        }
-    }
-
-    private Object findTemplateSource(String path) throws IOException {
-        final Object result = templateLoader.findTemplateSource(path);
-        if (LOG.isDebugEnabled()) {
-            LOG.debug("TemplateLoader.findTemplateSource(" +  StringUtil.jQuote(path) + "): "
-                    + (result == null ? "Not found" : "Found"));
-        }
-        return modifyForConfIcI(result);
-    }
-
-    /**
-     * If IcI >= 2.3.21, sets {@link URLTemplateSource#setUseCaches(boolean)} to {@code false} for sources that come
-     * from a {@link TemplateLoader} where {@link URLConnection} cache usage wasn't set explicitly.  
-     */
-    private Object modifyForConfIcI(Object templateSource) {
-        if (templateSource == null) return null;
-        
-        if (config.getIncompatibleImprovements().intValue() < _TemplateAPI.VERSION_INT_2_3_21) {
-            return templateSource;
-        }
-        
-        if (templateSource instanceof URLTemplateSource) {
-            URLTemplateSource urlTemplateSource = (URLTemplateSource) templateSource;
-            if (urlTemplateSource.getUseCaches() == null) {  // It was left unset
-                urlTemplateSource.setUseCaches(false);
-            }
-        } else if (templateSource instanceof MultiSource) {
-            modifyForConfIcI(((MultiSource) templateSource).getWrappedSource());
-        }
-        return templateSource;
-    }
-
-    private String concatPath(List path, int from, int to) {
+    private String concatPath(List<String> pathSteps, int from, int to) {
         StringBuilder buf = new StringBuilder((to - from) * 16);
         for (int i = from; i < to; ++i) {
-            buf.append(path.get(i)).append('/');
+            buf.append(pathSteps.get(i));
+            if (i < pathSteps.size() - 1) {
+                buf.append('/');
+            }
         }
         return buf.toString();
     }
     
+    // Replace with Objects.equals in Java 7
+    private static boolean nullSafeEquals(Object o1, Object o2) {
+        if (o1 == o2) return true;
+        if (o1 == null || o2 == null) return false;
+        return o1.equals(o2);
+    }
+    
     /**
-     * This class holds a (name, locale) pair and is used as the key in
-     * the cached templates map.
+     * Used as cache key to look up a {@link CachedResult}. 
      */
-    private static final class TemplateKey {
+    @SuppressWarnings("serial")
+    private static final class CachedResultKey implements Serializable {
         private final String name;
         private final Locale locale;
         private final Object customLookupCondition;
         private final String encoding;
         private final boolean parse;
 
-        TemplateKey(String name, Locale locale, Object customLookupCondition, String encoding, boolean parse) {
+        CachedResultKey(String name, Locale locale, Object customLookupCondition, String encoding, boolean parse) {
             this.name = name;
             this.locale = locale;
             this.customLookupCondition = customLookupCondition;
@@ -848,8 +897,8 @@ public class TemplateCache {
 
         @Override
         public boolean equals(Object o) {
-            if (o instanceof TemplateKey) {
-                TemplateKey tk = (TemplateKey) o;
+            if (o instanceof CachedResultKey) {
+                CachedResultKey tk = (CachedResultKey) o;
                 return
                     parse == tk.parse &&
                     name.equals(tk.name) &&
@@ -860,12 +909,6 @@ public class TemplateCache {
             return false;
         }
 
-        private boolean nullSafeEquals(Object o1, Object o2) {
-            return o1 != null
-                ? (o2 != null ? o1.equals(o2) : false)
-                : o2 == null;
-        }
-
         @Override
         public int hashCode() {
             return
@@ -878,24 +921,27 @@ public class TemplateCache {
     }
 
     /**
-     * This class holds the cached template and associated information
-     * (the source object, and the last-checked and last-modified timestamps).
-     * It is used as the value in the cached templates map. Note: this class
-     * is Serializable to allow custom 3rd party CacheStorage implementations 
-     * to serialize/replicate them (see tracker issue #1926150); FreeMarker 
-     * code itself doesn't rely on its serializability.
+     * Hold the a cached {@link #getTemplate(String, Locale, Object, String, boolean)} result and the associated
+     * information needed to check if the cached value is up to date.
+     * 
+     * <p>
+     * Note: this class is Serializable to allow custom 3rd party CacheStorage implementations to serialize/replicate
+     * them; FreeMarker code itself doesn't rely on its serializability.
+     * 
+     * @see CachedResultKey
      */
-    private static final class CachedTemplate implements Cloneable, Serializable {
+    private static final class CachedResult implements Cloneable, Serializable {
         private static final long serialVersionUID = 1L;
 
         Object templateOrException;
-        Object source;
+        TemplateLoadingSource source;
+        Serializable version;
         long lastChecked;
-        long lastModified;
         
-        public CachedTemplate cloneCachedTemplate() {
+        @Override
+        public CachedResult clone() {
             try {
-                return (CachedTemplate) super.clone();
+                return (CachedResult) super.clone();
             } catch (CloneNotSupportedException e) {
                 throw new UndeclaredThrowableException(e);
             }
@@ -904,18 +950,65 @@ public class TemplateCache {
     
     private class TemplateCacheTemplateLookupContext extends TemplateLookupContext {
 
-        TemplateCacheTemplateLookupContext(String templateName, Locale templateLocale, Object customLookupCondition) {
-            super(templateName, localizedLookup ? templateLocale : null, customLookupCondition);
+        private final TemplateLoaderSession session; 
+        
+        TemplateCacheTemplateLookupContext(String templateName, Locale templateLocale, Object customLookupCondition,
+                TemplateLoadingSource cachedResultSource, Serializable cachedResultVersion,
+                TemplateLoaderSession session) {
+            super(templateName, localizedLookup ? templateLocale : null, customLookupCondition,
+                    cachedResultSource, cachedResultVersion);
+            this.session = session;
         }
 
         @Override
-        public TemplateLookupResult lookupWithAcquisitionStrategy(String name) throws IOException {
+        public TemplateLookupResult lookupWithAcquisitionStrategy(String path) throws IOException {
             // Only one of the possible ways of making a name non-normalized, but is the easiest mistake to do:
-            if (name.startsWith("/")) {
-                throw new IllegalArgumentException("Non-normalized name, starts with \"/\": " + name);
+            if (path.startsWith("/")) {
+                throw new IllegalArgumentException("Non-normalized name, starts with \"/\": " + path);
             }
             
-            return TemplateCache.this.lookupTemplateWithAcquisitionStrategy(name);
+            int asterisk = path.indexOf(ASTERISK);
+            // Shortcut in case there is no acquisition
+            if (asterisk == -1) {
+                return TemplateLookupResult.from(
+                        path,
+                        templateLoader.load(path, getCachedResultSource(), getCachedResultVersion(), session));
+            }
+            StringTokenizer pathTokenizer = new StringTokenizer(path, "/");
+            int lastAsterisk = -1;
+            List<String> pathSteps = new ArrayList<String>();
+            while (pathTokenizer.hasMoreTokens()) {
+                String pathStep = pathTokenizer.nextToken();
+                if (pathStep.equals(ASTERISKSTR)) {
+                    if (lastAsterisk != -1) {
+                        pathSteps.remove(lastAsterisk);
+                    }
+                    lastAsterisk = pathSteps.size();
+                }
+                pathSteps.add(pathStep);
+            }
+            if (lastAsterisk == -1) {  // if there was no real "*" step after all
+                return TemplateLookupResult.from(
+                        path,
+                        templateLoader.load(path, getCachedResultSource(), getCachedResultVersion(), session));
+            }
+            String basePath = concatPath(pathSteps, 0, lastAsterisk);
+            String postAsteriskPath = concatPath(pathSteps, lastAsterisk + 1, pathSteps.size());
+            StringBuilder buf = new StringBuilder(path.length()).append(basePath);
+            int basePathLen = basePath.length();
+            while (true) {
+                String fullPath = buf.append(postAsteriskPath).toString();
+                TemplateLoadingResult templateLoaderResult = templateLoader.load(
+                        fullPath, getCachedResultSource(), getCachedResultVersion(), session);
+                if (templateLoaderResult.getStatus() == TemplateLoadingResultStatus.OPENED) {
+                    return TemplateLookupResult.from(fullPath, templateLoaderResult);
+                }
+                if (basePathLen == 0) {
+                    return TemplateLookupResult.createNegativeResult();
+                }
+                basePathLen = basePath.lastIndexOf(SLASH, basePathLen - 2) + 1;
+                buf.setLength(basePathLen);
+            }
         }
 
         @Override

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateConfigurationFactory.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateConfigurationFactory.java b/src/main/java/freemarker/cache/TemplateConfigurationFactory.java
index ec8d2ae..b2561e9 100644
--- a/src/main/java/freemarker/cache/TemplateConfigurationFactory.java
+++ b/src/main/java/freemarker/cache/TemplateConfigurationFactory.java
@@ -37,10 +37,10 @@ public abstract class TemplateConfigurationFactory {
      * Returns (maybe creates) the {@link TemplateConfiguration} for the given template source.
      * 
      * @param sourceName
-     *            The name (path) that was used for {@link TemplateLoader#findTemplateSource(String)}. See
+     *            The name (path) that was used for {@link TemplateLoader#load}. See
      *            {@link Template#getSourceName()} for details.
-     * @param templateSource
-     *            The object returned by {@link TemplateLoader#findTemplateSource(String)}.
+     * @param templateLoadingSource
+     *            The object returned by {@link TemplateLoadingResult#getSource()}.
      * 
      * @return The {@link TemplateConfiguration} to apply, or {@code null} if the there's no {@link TemplateConfiguration} for
      *         this template source.
@@ -51,7 +51,7 @@ public abstract class TemplateConfigurationFactory {
      * @throws TemplateConfigurationFactoryException
      *             If there's a problem that's specific to the factory logic.
      */
-    public abstract TemplateConfiguration get(String sourceName, Object templateSource)
+    public abstract TemplateConfiguration get(String sourceName, TemplateLoadingSource templateLoadingSource)
             throws IOException, TemplateConfigurationFactoryException;
     
     /**

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateLoader.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateLoader.java b/src/main/java/freemarker/cache/TemplateLoader.java
index bab7cae..ae82c71 100644
--- a/src/main/java/freemarker/cache/TemplateLoader.java
+++ b/src/main/java/freemarker/cache/TemplateLoader.java
@@ -16,50 +16,56 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-
 package freemarker.cache;
 
 import java.io.IOException;
-import java.io.Reader;
+import java.io.Serializable;
 
 import freemarker.template.Configuration;
 import freemarker.template.TemplateNotFoundException;
 
 /**
- * FreeMarker loads template "files" through objects that implement this interface,
- * thus the templates need not be real files, and can come from any kind of data source
- * (like classpath, servlet context, database, etc). While FreeMarker provides a few
- * {@link TemplateLoader} implementations out-of-the-box, it's normal for embedding
- * frameworks to use their own implementations.
+ * FreeMarker loads template "files" through objects that implement this interface, thus the templates need not be real
+ * files, and can come from any kind of data source (like classpath, servlet context, database, etc). While FreeMarker
+ * provides a few template loader implementations out-of-the-box, it's normal for embedding frameworks to use their own
+ * implementations.
  * 
- * <p>To set the {@link TemplateLoader} used by FreeMaker, use
- * {@link Configuration#setTemplateLoader(TemplateLoader)}.
+ * <p>
+ * To set the {@link TemplateLoader} used by FreeMaker, use {@link Configuration#setTemplateLoader(TemplateLoader)}.
  * 
- * <p>Implementations of this interface should be thread-safe.
+ * <p>
+ * Implementations of this interface should be thread-safe.
  * 
- * <p>Implementations should override {@link Object#toString()} to show information about from where the
+ * <p>
+ * Implementations should override {@link Object#toString()} to show information about from where the
  * {@link TemplateLoader} loads the templates. For example, for a template loader that loads template from database
  * table {@code toString} could return something like
  * {@code "MyDatabaseTemplateLoader(user=\"cms\", table=\"mail_templates\")"}. This string will be shown in
  * {@link TemplateNotFoundException} exception messages, next to the template name.
  * 
- * <p>For those who has to dig deeper, note that the {@link TemplateLoader} is actually stored inside
- * the {@link TemplateCache} of the {@link Configuration}, and is normally only accessed directly
- * by the {@link TemplateCache}, and templates are get via the {@link TemplateCache} API-s.
+ * <p>
+ * For those who has to dig deeper, note that the {@link TemplateLoader} is actually stored inside the
+ * {@link TemplateCache} of the {@link Configuration}, and is normally only accessed directly by the
+ * {@link TemplateCache}, and templates are get via the {@link TemplateCache} API-s.
  */
 public interface TemplateLoader {
-	
+
+    /**
+     * Creates a new session, or returns {@code null} if the template loader implementation doesn't support sessions.
+     * See {@link TemplateLoaderSession} for more information about sessions.
+     */
+    TemplateLoaderSession createSession();
+    
     /**
-     * Finds the template in the backing storage and returns an object that identifies the storage location where the
-     * template can be loaded from. See the return value for more information.
-     *
+     * Loads the template content together with meta-data such as the version (usually the last modification time).
+     * 
      * @param name
-     *            The name of the template, already localized and normalized by the
-     *            {@link freemarker.cache.TemplateCache cache}. It is completely up to the loader implementation to
+     *            The name (template root directory relative path) of the template, already localized and normalized by
+     *            the {@link freemarker.cache.TemplateCache cache}. It is completely up to the loader implementation to
      *            interpret the name, however it should expect to receive hierarchical paths where path components are
      *            separated by a slash (not backslash). Backslashes (or any other OS specific separator character) are
      *            not considered as separators by FreeMarker, and thus they will not be replaced with slash before
-     *            passing to this method, so it's up to the template loader to handle them (say, be throwing and
+     *            passing to this method, so it's up to the template loader to handle them (say, by throwing an
      *            exception that tells the user that the path (s)he has entered is invalid, as (s)he must use slash --
      *            typical mistake of Windows users). The passed names are always considered relative to some
      *            loader-defined root location (often referred as the "template root directory"), and will never start
@@ -70,81 +76,27 @@ public interface TemplateLoader {
      *            uses backslash as path separator instead of slash as (the template loader should not accept that), the
      *            normalization will not properly happen, as FreeMarker (the cache) recognizes only the slashes as
      *            separators.
-     *
-     * @return An object representing the template source, which can be supplied in subsequent calls to
-     *         {@link #getLastModified(Object)} and {@link #getReader(Object, String)}, when those are called on the
-     *         same {@link TemplateLoader}. {@code null} must be returned if the source for the template doesn't exist;
-     *         don't throw exception then! The exact type of this object is up to the {@link TemplateLoader}
-     *         implementation. As this object is possibly used as hash key in caches, and is surly compared with another
-     *         template source for equality, <b>it must have a proper {@link Object#equals(Object)} and
-     *         {@link Object#hashCode()}) implementation</b>. Especially, template sources that refer to the same
-     *         physical source must be equivalent, otherwise template caching can become inefficient. This is only
-     *         expected from {@link Object#equals(Object)} when the compared template sources came from the same
-     *         {@link TemplateLoader} instance. Also, it must not influence the equality if the source is open or
-     *         closed ({@link #closeTemplateSource(Object)}). 
-     * 
-     * @throws IOException
-     *             When an error occurs that makes it impossible to find out if the template exists, or to access the
-     *             existing template. Don't throw exception if the template doesn't exist, instead return with
-     *             {@code null} then!
-     */
-    public Object findTemplateSource(String name)
-    throws IOException;
-        
-    /**
-     * Returns the time of last modification of the specified template source. This method is called after
-     * <code>findTemplateSource()</code>.
+     * @param ifSourceDiffersFrom
+     *            If we only want to load the template if its source differs from this. {@code null} if you want the
+     *            template to be loaded unconditionally. If this is {@code null} then the
+     *            {@code ifVersionDiffersFrom} parameter must be {@code null} too. See
+     *            {@link TemplateLoadingResult#getSource()} for more about sources.
+     * @param ifVersionDiffersFrom
+     *            If we only want to load the template if its version (which is usually the last modification time)
+     *            differs from this. {@code null} if {@code ifSourceDiffersFrom} is {@code null}, or if the backing
+     *            storage from which the {@code ifSourceDiffersFrom} template source comes from doesn't store a version.
+     *            See {@link TemplateLoadingResult#getVersion()} for more about versions.
      * 
-     * @param templateSource
-     *            an object representing a template source, obtained through a prior call to
-     *            {@link #findTemplateSource(String)}. This must be an object on which
-     *            {@link TemplateLoader#closeTemplateSource(Object)} wasn't applied yet.
-     * @return the time of last modification of the specified template source, or -1 if the time is not known.
+     * @return Not {@code null}.
      */
-    public long getLastModified(Object templateSource);
+    TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom, Serializable ifVersionDiffersFrom,
+            TemplateLoaderSession session) throws IOException;
     
     /**
-     * Returns the character stream of a template represented by the specified template source. This method is possibly
-     * called for multiple times for the same template source object, and it must always return a {@link Reader} that
-     * reads the template from its beginning. Before this method is called for the second time (or later), its caller
-     * must close the previously returned {@link Reader}, and it must not use it anymore. That is, this method is not
-     * required to support multiple concurrent readers for the same source {@code templateSource} object.
-     * 
-     * <p>
-     * Typically, this method is called if the template is missing from the cache, or if after calling
-     * {@link #findTemplateSource(String)} and {@link #getLastModified(Object)} it was determined that the cached copy
-     * of the template is stale. Then, if it turns out that the {@code encoding} parameter used doesn't match the actual
-     * template content (based on the {@code #ftl encoding=...} header), this method will be called for a second time
-     * with the correct {@code encoding} parameter value.
-     * 
-     * @param templateSource
-     *            an object representing a template source, obtained through a prior call to
-     *            {@link #findTemplateSource(String)}. This must be an object on which
-     *            {@link TemplateLoader#closeTemplateSource(Object)} wasn't applied yet.
-     * @param encoding
-     *            the character encoding used to translate source bytes to characters. Some loaders may not have access
-     *            to the byte representation of the template stream, and instead directly obtain a character stream.
-     *            These loaders should ignore the encoding parameter.
-     * 
-     * @return A {@link Reader} representing the template character stream. It's the responsibility of the caller (which
-     *         is {@link TemplateCache} usually) to {@code close()} it. The {@link Reader} is not required to work after
-     *         the {@code templateSource} was closed ({@link #closeTemplateSource(Object)}).
-     * 
-     * @throws IOException
-     *             if an I/O error occurs while accessing the stream.
+     * Invoked by {@link Configuration#clearTemplateCache()} to instruct this template loader to throw away its current
+     * state (some kind of cache usually) and start afresh. For most {@link TemplateLoader} implementations this does
+     * nothing.
      */
-    public Reader getReader(Object templateSource, String encoding)
-    throws IOException;
-    
-    /**
-     * Closes the template source, releasing any resources held that are only required for reading the template and/or
-     * its metadata. This is the last method that is called by the {@link TemplateCache} for a template source, except
-     * that {@link Object#equals(Object)} is might called later too. {@link TemplateCache} ensures that this method will
-     * be called on every object that is returned from {@link #findTemplateSource(String)}.
-     * 
-     * @param templateSource
-     *            the template source that should be closed.
-     */
-    public void closeTemplateSource(Object templateSource)
-    throws IOException;
+    void resetState();
+
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateLoaderSession.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateLoaderSession.java b/src/main/java/freemarker/cache/TemplateLoaderSession.java
new file mode 100644
index 0000000..318fe11
--- /dev/null
+++ b/src/main/java/freemarker/cache/TemplateLoaderSession.java
@@ -0,0 +1,73 @@
+/*
+ * 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.cache;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.Reader;
+
+/**
+ * Stores shared state between {@link TemplateLoader} operations that are executed close to each other in the same
+ * thread. For example, a {@link TemplateLoader} that reads from a database might wants to store the database
+ * connection in it for reuse. The goal of sessions is mostly to increase performance. However, because a
+ * {@link TemplateCache#getTemplate(String, java.util.Locale, Object, String, boolean)} call is executed inside a single
+ * session, sessions can be also be utilized to ensure that the template lookup (see {@link TemplateLookupStrategy})
+ * happens on a consistent view (a snapshot) of the backing storage, if the backing storage mechanism supports such
+ * thing.
+ * 
+ * <p>
+ * The {@link TemplateLoaderSession} implementation is (usually) specific to the {@link TemplateLoader}
+ * implementation. If your {@link TemplateLoader} implementation can't take advantage of sessions, you don't have to
+ * implement this interface, just return {@code null} for {@link TemplateLoader#createSession()}.
+ * 
+ * <p>
+ * {@link TemplateLoaderSession}-s should be lazy, that is, creating an instance should be very fast and should not
+ * cause I/O. Only when (and if ever) the shared resource stored in the session is needed for the first time should the
+ * shared resource be initialized.
+ *
+ * <p>
+ * {@link TemplateLoaderSession}-s need not be thread safe.
+ */
+public interface TemplateLoaderSession {
+
+    /**
+     * Closes this session, freeing any resources it holds. Further operations involving this session should fail, with
+     * the exception of {@link #close()} itself, which should be silently ignored.
+     * 
+     * <p>
+     * The {@link Reader} or {@link InputStream} contained in the {@link TemplateLoadingResult} must be closed before
+     * {@link #close()} is called on the session in which the {@link TemplateLoadingResult} was created. Except, if
+     * closing the {@link Reader} or {@link InputStream} has thrown an exception, the caller should just proceed with
+     * closing the session regardless. After {@link #close()} was called on the session, the methods of the
+     * {@link Reader} or {@link InputStream} is allowed to throw an exception, or behave in any other erratic way.
+     * (Because the caller of this interface is usually FreeMarker (the {@link TemplateCache}), normally you don't have
+     * to deal with these rules, but it's useful to know the expectations if you implement
+     * {@link TemplateLoaderSession}.)
+     * 
+     * <p>The caller of {@link TemplateLoader#createSession()} has to guarantee that {@link #close()} will be called on
+     * the created session.
+     */
+    public void close() throws IOException;
+    
+    /**
+     * Tells if this session is closed.
+     */
+    public boolean isClosed();
+
+}

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateLoaderUtils.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateLoaderUtils.java b/src/main/java/freemarker/cache/TemplateLoaderUtils.java
index e229e76..2c98053 100644
--- a/src/main/java/freemarker/cache/TemplateLoaderUtils.java
+++ b/src/main/java/freemarker/cache/TemplateLoaderUtils.java
@@ -28,11 +28,10 @@ final class TemplateLoaderUtils {
     }
 
     public static String getClassNameForToString(TemplateLoader templateLoader) {
-        final Class tlClass = templateLoader.getClass();
+        final Class<? extends TemplateLoader> tlClass = templateLoader.getClass();
         final Package tlPackage = tlClass.getPackage();
         return tlPackage == Configuration.class.getPackage() || tlPackage == TemplateLoader.class.getPackage()
                 ? tlClass.getSimpleName() : tlClass.getName();
     }
-
     
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateLoadingResult.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateLoadingResult.java b/src/main/java/freemarker/cache/TemplateLoadingResult.java
new file mode 100644
index 0000000..87dcac9
--- /dev/null
+++ b/src/main/java/freemarker/cache/TemplateLoadingResult.java
@@ -0,0 +1,199 @@
+/*
+ * 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.cache;
+
+import java.io.InputStream;
+import java.io.Reader;
+import java.io.Serializable;
+import java.util.Date;
+
+import freemarker.core.TemplateConfiguration;
+import freemarker.template.Configuration;
+import freemarker.template.utility.NullArgumentException;
+
+/**
+ * Return value of {@link TemplateLoader#load(String, TemplateLoadingSource, Serializable, TemplateLoaderSession)}
+ */
+public final class TemplateLoadingResult {
+    private final TemplateLoadingResultStatus status;
+    private final TemplateLoadingSource source;
+    private final Serializable version;
+    private final Reader reader;
+    private final InputStream inputStream;
+    private final TemplateConfiguration templateConfiguration; 
+
+    public static final TemplateLoadingResult NOT_FOUND = new TemplateLoadingResult(
+            TemplateLoadingResultStatus.NOT_FOUND);
+    public static final TemplateLoadingResult NOT_MODIFIED = new TemplateLoadingResult(
+            TemplateLoadingResultStatus.NOT_MODIFIED);
+
+    /**
+     * Creates an instance with status {@link TemplateLoadingResultStatus#OPENED}, for a storage mechanism that
+     * naturally returns the template content as sequence of {@code char}-s as opposed to a sequence of {@code byte}-s.
+     * This is the case for example when you store the template in a database in a varchar or CLOB. Do <em>not</em> use
+     * this constructor for stores that naturally return binary data instead (like files, class loader resources,
+     * BLOB-s, etc.), because using this constructor will disable FreeMarker's charset selection mechanism.
+     * 
+     * @param source
+     *            See {@link #getSource()}
+     * @param version
+     *            See {@link #getVersion()} for the meaning of this. Can be {@code null}, but use that only if the
+     *            backing storage mechanism doesn't know this information.
+     * @param reader
+     *            Gives the content of the template
+     * @param templateConfiguration
+     *            Usually {@code null}, as usually the backing storage mechanism doesn't store such information;
+     *            see {@link #getTemplateConfiguration()}.
+     */
+    public TemplateLoadingResult(TemplateLoadingSource source, Serializable version, Reader reader,
+            TemplateConfiguration templateConfiguration) {
+        NullArgumentException.check("templateSource", source);
+        NullArgumentException.check("reader", reader);
+        this.status = TemplateLoadingResultStatus.OPENED;
+        this.source = source;
+        this.version = version;
+        this.reader = reader;
+        this.inputStream = null;
+        this.templateConfiguration = templateConfiguration; 
+    }
+
+    /**
+     * Creates an instance with status {@link TemplateLoadingResultStatus#OPENED}, for a storage mechanism that
+     * naturally returns the template content as sequence of {@code byte}-s as opposed to a sequence of {@code char}-s.
+     * This is the case for example when you store the template in a file, classpath resource, or BLOB. Do <em>not</em>
+     * use this constructor for stores that naturally return text instead (like database varchar and CLOB columns).
+     * 
+     * @param source
+     *            See {@link #getSource()}
+     * @param version
+     *            See {@link #getVersion()} for the meaning of this. Can be {@code null}, but use that only if the
+     *            backing storage mechanism doesn't know this information.
+     * @param inputStream
+     *            Gives the content of the template
+     * @param templateConfiguration
+     *            Usually {@code null}, as usually the backing storage mechanism doesn't store such information; see
+     *            {@link #getTemplateConfiguration()}. The most probable application is supplying the charset (encoding)
+     *            used by the {@link InputStream} (via {@link TemplateConfiguration#setEncoding(String)}), but only
+     *            do that if the storage mechanism really knows what the charset is.
+     */
+    public TemplateLoadingResult(TemplateLoadingSource source, Serializable version, InputStream inputStream,
+            TemplateConfiguration templateConfiguration) {
+        NullArgumentException.check("templateSource", source);
+        NullArgumentException.check("inputStream", inputStream);
+        this.status = TemplateLoadingResultStatus.OPENED;
+        this.source = source;
+        this.version = version;
+        this.reader = null;
+        this.inputStream = inputStream;
+        this.templateConfiguration = templateConfiguration; 
+    }
+
+    /**
+     * Used internally for creating the singleton instances which has a state where all other fields are {@code null}.
+     */
+    private TemplateLoadingResult(TemplateLoadingResultStatus status) {
+        this.status = status;
+        this.source = null;
+        this.version = null;
+        this.reader = null;
+        this.inputStream = null;
+        this.templateConfiguration = null;
+    }
+
+    /**
+     * Returns non-{@code null} exactly if {@link #getStatus()} is {@link TemplateLoadingResultStatus#OPENED} and the
+     * backing store mechanism returns content as {@code byte}-s, as opposed to as {@code chars}-s. See also
+     * {@link #TemplateLoadingResult(TemplateLoadingSource, Serializable, InputStream, TemplateConfiguration)}. It's the
+     * responsibility of the caller (which is {@link TemplateCache} usually) to {@code close()} the {@link InputStream}.
+     * The return value is always the same instance, no mater when and how many times this method is called.
+     * 
+     * <p>
+     * The return {@code InputStream} should use buffering if that's useful considering the backing storage mechanism.
+     * TODO Is it really needed?
+     * 
+     * @return {@code null} or a {@code InputStream} to read the template content; see method description for more.
+     */
+    public InputStream getInputStream() {
+        return inputStream;
+    }
+
+    /**
+     * Tells what kind of result this is; see the documentation of {@link TemplateLoadingResultStatus}.
+     */
+    public TemplateLoadingResultStatus getStatus() {
+        return status;
+    }
+
+    /**
+     * Identifies the source on the level of the storage mechanism; stored in the cache together with the version
+     * ({@link #getVersion()}). When checking if a cache entry is up to date, the sources are compared, and only if they
+     * are equal are the versions compared. See more at {@link TemplateLoadingSource}.
+     */
+    public TemplateLoadingSource getSource() {
+        return source;
+    }
+
+    /**
+     * If the result status is {@link TemplateLoadingResultStatus#OPENED} and the backing storage stores such
+     * information, the version (usually the last modification time) of the loaded template, otherwise {@code null}. The
+     * version is some kind of value which changes when the template in the backing storage is updated. Usually, it's
+     * the last modification time (a {@link Date} or {@link Long}), though that can be problematic if the template can
+     * change twice within the granularity of the clock used by the storage. Thus some storages may use a revision
+     * number instead that's always increased when the template is updated, or the cryptographic hash of the template
+     * content as the version. Version objects are compared with each other with their {@link Object#equals(Object)}
+     * method, to see if a cache entry is outdated (though only when the source objects ({@link #getSource()}) are
+     * equal). Thus, the version object must have proper {@link Object#equals(Object)} and {@link Object#hashCode()}
+     * methods.
+     */
+    public Serializable getVersion() {
+        return version;
+    }
+
+    /**
+     * Returns non-{@code null} exactly if {@link #getStatus()} is {@link TemplateLoadingResultStatus#OPENED} and the
+     * backing store mechanism returns content as {@code char}-s, as opposed to as {@code byte}-s. See also
+     * {@link #TemplateLoadingResult(TemplateLoadingSource, Serializable, Reader, TemplateConfiguration)}. It's the
+     * responsibility of the caller (which is {@link TemplateCache} usually) to {@code close()} the {@link Reader}. The
+     * return value is always the same instance, no mater when and how many times this method is called.
+     * 
+     * @return {@code null} or a {@code Reader} to read the template content; see method description for more.
+     */
+    public Reader getReader() {
+        return reader;
+    }
+
+    /**
+     * If {@link #getStatus()} is {@link TemplateLoadingResultStatus#OPENED}, and the template loader stores such
+     * information (which is rare) then it returns the {@link TemplateConfiguration} applicable to the template,
+     * otherwise it returns {@code null}. If {@link #getStatus()} is not {@link TemplateLoadingResultStatus#OPENED},
+     * then this should always return {@code null}. If there are {@link TemplateConfiguration}-s coming from other
+     * sources, such as from {@link Configuration#getTemplateConfigurations()}, this won't replace them, but will be
+     * merged with them, with properties coming from the returned {@link TemplateConfiguration} having the highest
+     * priority.
+     * 
+     * @return {@code null}, or a {@link TemplateConfiguration}. The parent configuration of the
+     *         {@link TemplateConfiguration} need not be set. The returned {@link TemplateConfiguration} won't be
+     *         modified. (If the caller needs to modify it, such as to call
+     *         {@link TemplateConfiguration#setParentConfiguration(Configuration)}, it has to copy it first.)
+     */
+    public TemplateConfiguration getTemplateConfiguration() {
+        return templateConfiguration;
+    }
+    
+}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateLoadingResultStatus.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateLoadingResultStatus.java b/src/main/java/freemarker/cache/TemplateLoadingResultStatus.java
new file mode 100644
index 0000000..6ea5e50
--- /dev/null
+++ b/src/main/java/freemarker/cache/TemplateLoadingResultStatus.java
@@ -0,0 +1,49 @@
+/*
+ * 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.cache;
+
+import java.io.Serializable;
+
+/**
+ * Used for the value of {@link TemplateLoadingResult#getStatus()}.
+ */
+public enum TemplateLoadingResultStatus {
+
+    /**
+     * The template with the requested name doesn't exist (not to be confused with "wasn't accessible due to error"). If
+     * there was and error because of which we can't know for sure if the template is there or not (for example we
+     * couldn't access the backing store due to a network connection error or other unexpected I/O error or
+     * authorization problem), this value must not be used, instead an exception should be thrown by
+     * {@link TemplateLoader#load(String, TemplateLoadingSource, Serializable, TemplateLoaderSession)}.
+     */
+    NOT_FOUND,
+
+    /**
+     * If the template was found, but its source and version is the same as that which was provided to
+     * {@link TemplateLoader#load(String, TemplateLoadingSource, Serializable, TemplateLoaderSession)} (from a cache
+     * presumably), so its content wasn't opened for reading.
+     */
+    NOT_MODIFIED,
+
+    /**
+     * If the template was found and its content is ready for reading.
+     */
+    OPENED
+    
+}
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/java/freemarker/cache/TemplateLoadingSource.java
----------------------------------------------------------------------
diff --git a/src/main/java/freemarker/cache/TemplateLoadingSource.java b/src/main/java/freemarker/cache/TemplateLoadingSource.java
new file mode 100644
index 0000000..ce84d24
--- /dev/null
+++ b/src/main/java/freemarker/cache/TemplateLoadingSource.java
@@ -0,0 +1,66 @@
+/*
+ * 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.cache;
+
+import java.io.Serializable;
+import java.util.HashMap;
+
+/**
+ * The point of {@link TemplateLoadingSource} is that with their {@link Object#equals(Object)} method we can tell if two
+ * cache entries were generated from the same physical resource or not. Comparing the template names isn't enough,
+ * because a {@link TemplateLoader} may uses some kind of fallback mechanism, such as delegating to other
+ * {@link TemplateLoader}-s until the template is found. Like if we have two {@link FileTemplateLoader}-s with different
+ * physical root directories, both can contain {@code "foo/bar.ftl"}, but obviously the two files aren't the same.
+ * 
+ * <p>
+ * When implementing this interface, check these:
+ * 
+ * <ul>
+ * <li>{@link Object#equals(Object)} must not be based on object identity, because two instances of
+ * {@link TemplateLoadingSource} that describe the same resource must be equivalent.
+ * 
+ * <li>Each {@link TemplateLoader} implementation should have its own {@link TemplateLoadingSource} implementation, so
+ * that {@link TemplateLoadingSource}-s coming from different {@link TemplateLoader} implementations can't be
+ * accidentally equal (according to {@link Object#equals(Object)}).
+ * 
+ * <li>{@link Object#equals(Object)} must still work properly if there are multiple instances of the same
+ * {@link TemplateLoader} implementation. Like if you have an implementation that loads from a database table, the
+ * {@link TemplateLoadingSource} should certain contain the JDBC connection string, the table name and the row ID, not
+ * just the row ID.
+ * 
+ * <li>Together with {@link Object#equals(Object)}, {@link Object#hashCode()} must be also overridden. The template
+ * source may be used as a {@link HashMap} key.
+ * 
+ * <li>Because {@link TemplateLoadingSource}-s are {@link Serializable}, they can't contain non-{@link Serializable}
+ * fields. Most notably, a reference to the creator {@link TemplateLoader}, so if it's an inner class of the
+ * {@link TemplateLoader}, it should be static.
+ * 
+ * <li>Consider that cache entries, in which the source is stored, may move between JVM-s (because of clustering with a
+ * distributed cache). Thus they should remain meaningful for the purpose of {@link Object#equals(Object)} even in
+ * another JVM.
+ * 
+ * <li>A {@link TemplateLoader} may chose not to support distributed caches, like {@link ByteArrayTemplateLoader}
+ * doesn't support that for example. In that case the serialization related points above can be ignored, but the
+ * {@link TemplateLoadingSource} implementation should define the {@code writeObject} method (a Java serialization
+ * feature) and throw an exception there to block serialization attempts.
+ * </ul>
+ */
+public interface TemplateLoadingSource extends Serializable {
+    // Empty
+}


[2/5] incubator-freemarker git commit: - Totally redesigned TemplateLoader interface. The FM2 TemplateLoader can't be adapted (wrapped) to it, but usually

Posted by dd...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/main/javacc/FTL.jj
----------------------------------------------------------------------
diff --git a/src/main/javacc/FTL.jj b/src/main/javacc/FTL.jj
index 2d40054..e200ddc 100644
--- a/src/main/javacc/FTL.jj
+++ b/src/main/javacc/FTL.jj
@@ -76,6 +76,8 @@ public class FMParser {
     private int autoEscapingPolicy;
     private boolean autoEscaping;
     private ParserConfiguration pCfg;
+    private TemplateSpecifiedEncodingHandler templateSpecifiedEncodingHandler;
+    private boolean templateSpecifiedEncodingHandlerInvoked;
 
     /** Keeps track of #list and #foreach nesting. */
     private List/*<ParserIteratorBlockContext>*/ iteratorBlockContexts;
@@ -94,8 +96,9 @@ public class FMParser {
     private LinkedList escapes = new LinkedList();
     private int mixedContentNesting; // for stripText
 
-    FMParser(Template template, Reader reader, ParserConfiguration pCfg) {
-        this(template, true, readerToTokenManager(reader, pCfg), pCfg);
+    FMParser(Template template, Reader reader, ParserConfiguration pCfg,
+    		TemplateSpecifiedEncodingHandler templateSpecifiedEncodingHandler) {
+        this(template, true, readerToTokenManager(reader, pCfg), pCfg, templateSpecifiedEncodingHandler);
     }
 
     private static FMParserTokenManager readerToTokenManager(Reader reader, ParserConfiguration pCfg) {
@@ -104,11 +107,15 @@ public class FMParser {
         return new FMParserTokenManager(simpleCharStream);
     }
 
-    FMParser(Template template, boolean newTemplate, FMParserTokenManager tkMan, ParserConfiguration pCfg) {
+    FMParser(Template template, boolean newTemplate, FMParserTokenManager tkMan, ParserConfiguration pCfg,
+    		TemplateSpecifiedEncodingHandler templateSpecifiedEncodingHandler) {
         this(tkMan);
 
         NullArgumentException.check(pCfg);
         this.pCfg = pCfg;
+        
+        NullArgumentException.check(templateSpecifiedEncodingHandler);
+        this.templateSpecifiedEncodingHandler = templateSpecifiedEncodingHandler;
 
         NullArgumentException.check(template);
         this.template = template;
@@ -4049,10 +4056,8 @@ void HeaderElement() :
                             if (vs == null) {
                                 throw new ParseException("Expected a string constant for \"" + ks + "\".", exp);
                             }
-                            String encoding = template.getEncoding();
-                            if (encoding != null && !encoding.equalsIgnoreCase(vs)) {
-                                throw new Template.WrongEncodingException(vs, encoding);
-                            }
+                            templateSpecifiedEncodingHandlerInvoked = true;
+                            templateSpecifiedEncodingHandler.handle(vs, template.getEncoding());
                         } else if (ks.equalsIgnoreCase("STRIP_WHITESPACE") || ks.equals("stripWhitespace")) {
                             this.stripWhitespace = getBoolean(exp, true);
                         } else if (ks.equalsIgnoreCase("STRIP_TEXT") || ks.equals("stripText")) {
@@ -4241,6 +4246,13 @@ TemplateElement Root() :
         LOOKAHEAD([<STATIC_TEXT_WS>](<TRIVIAL_FTL_HEADER>|<FTL_HEADER>))
         HeaderElement()
     ]
+    {
+        if (!templateSpecifiedEncodingHandlerInvoked) {
+	        templateSpecifiedEncodingHandlerInvoked = true;
+	        templateSpecifiedEncodingHandler.handle(null, template.getEncoding());
+        }
+    }
+    
     children = MixedContentElements()
     <EOF>
     {

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/manual/en_US/FM3-CHANGE-LOG.txt
----------------------------------------------------------------------
diff --git a/src/manual/en_US/FM3-CHANGE-LOG.txt b/src/manual/en_US/FM3-CHANGE-LOG.txt
index 4ba48fb..c860692 100644
--- a/src/manual/en_US/FM3-CHANGE-LOG.txt
+++ b/src/manual/en_US/FM3-CHANGE-LOG.txt
@@ -1,3 +1,22 @@
+/*
+ * 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.
+ */
+ 
 Because the Manual won't be updated for a good while, I will lead
 the FreeMarer 3 changelog here:
 
@@ -17,4 +36,28 @@ the FreeMarer 3 changelog here:
 - Removed the strict_syntax setting, and so also the support for FTL tags without #. This was a FreeMarker 1.x
   compatibility option.
 - Removed deprecated FMParser contstructors.
-- Minimum Java version increased to 7, but without try-with-resource as that's unavailable before Android 4.4 KitKat.
\ No newline at end of file
+- Minimum Java version increased to 7, but without try-with-resource as that's unavailable before Android 4.4 KitKat.
+- Totally redesigned TemplateLoader interface. The FM2 TemplateLoader can't be adapted (wrapped) to it, but usually
+  it's fairly trivial to "rearrange" an old custom TemplateLoader for the new interface. The new TemplateLoader comes
+  with several advantages, such as:
+  - It can work more efficiently with sophisticated storage mechanisms like a database, as it's now possible to pack
+    together the existence check, the last modification change check, and reading operations into less storage level
+    operations (like you can do all of them with a single SQL statement).
+  - The new TemplateLoader allows returning the template content either as an InputStream or as a Reader. Almost all
+    TemplateLoader-s should return InputStream, and FreeMarker takes care of charset issues transparently (as a result,
+    TemplateLoader-s don't have to support re-reading a template anymore, as we solve charset detection misses in
+    memory). TemplateLoader-s that are inherently backed by text (String-s), such as templates stored in a varchar or
+    CLOB column, should return a Reader. Note that templates created from a Reader will have template.getEncoding()
+    null (logically, as no charset was involved), which was impossible in FreeMarker 2.
+  - The change detection of the template doesn't have to rely on a millisecond resolution timestamp anymore; you can
+    use what's most appropriate for the storage mechanism, such as a cryptographic hash or a revision number.
+  - Template lookups (where you try multiple names until you find the best template) can now be transactional and/or
+    atomic if the backing storage mechanism supports that, by utilizing the TemplateLoaderSession interface.
+  - TemplateLoader can now return template-level settings like the output format (MIME type basically) of the loaded
+    template, in case the backing storage stores such extra information. This mechanism can be used together with
+    the TemplateConfiguration mechanism (already familiar from FreeMarker 2), and overrides the individual settings
+    coming from there.
+- Template constructors won't close the Reader passed in as agrument anymore (because a Reader should be closed
+  by who has created it). This avoids some surprises from the past, such as the unablility to reset a Reader to a mark
+  after parsing. If you call those constructors, be sure that you close the Reader yourself. (Obviously, it doesn't
+  mater for StringReader-s.)

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/cache/MultiTemplateLoaderTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/cache/MultiTemplateLoaderTest.java b/src/test/java/freemarker/cache/MultiTemplateLoaderTest.java
index e4b14f3..8878a48 100644
--- a/src/test/java/freemarker/cache/MultiTemplateLoaderTest.java
+++ b/src/test/java/freemarker/cache/MultiTemplateLoaderTest.java
@@ -18,9 +18,13 @@
  */
 package freemarker.cache;
 
-import static org.junit.Assert.*;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
 
 import java.io.IOException;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
 
 import org.apache.commons.io.IOUtils;
 import org.junit.Test;
@@ -38,10 +42,10 @@ public class MultiTemplateLoaderTest {
         stl2.putTemplate("both.ftl", "both 2");
         
         MultiTemplateLoader mtl = new MultiTemplateLoader(new TemplateLoader[] { stl1, stl2 });
-        assertEquals("1", getTemplate(mtl, "1.ftl"));
-        assertEquals("2", getTemplate(mtl, "2.ftl"));
-        assertEquals("both 1", getTemplate(mtl, "both.ftl"));
-        assertNull(getTemplate(mtl, "neither.ftl"));
+        assertEquals("1", getTemplateContent(mtl, "1.ftl"));
+        assertEquals("2", getTemplateContent(mtl, "2.ftl"));
+        assertEquals("both 1", getTemplateContent(mtl, "both.ftl"));
+        assertNull(getTemplateContent(mtl, "neither.ftl"));
     }
 
     @Test
@@ -58,28 +62,37 @@ public class MultiTemplateLoaderTest {
         StringTemplateLoader stl1 = new StringTemplateLoader();
         stl1.putTemplate("both.ftl", "both 1");
         
-        StringTemplateLoader stl2 = new StringTemplateLoader();
-        stl2.putTemplate("both.ftl", "both 2");
+        ByteArrayTemplateLoader stl2 = new ByteArrayTemplateLoader();
+        stl2.putTemplate("both.ftl", "both 2".getBytes(StandardCharsets.UTF_8));
 
         MultiTemplateLoader mtl = new MultiTemplateLoader(new TemplateLoader[] { stl1, stl2 });
         mtl.setSticky(sticky);
         
-        assertEquals("both 1", getTemplate(mtl, "both.ftl"));
+        assertEquals("both 1", getTemplateContent(mtl, "both.ftl"));
         assertTrue(stl1.removeTemplate("both.ftl"));
-        assertEquals("both 2", getTemplate(mtl, "both.ftl"));
+        assertEquals("both 2", getTemplateContent(mtl, "both.ftl"));
         stl1.putTemplate("both.ftl", "both 1");
-        assertEquals(sticky ? "both 2" : "both 1", getTemplate(mtl, "both.ftl"));
+        assertEquals(sticky ? "both 2" : "both 1", getTemplateContent(mtl, "both.ftl"));
         assertTrue(stl2.removeTemplate("both.ftl"));
-        assertEquals("both 1", getTemplate(mtl, "both.ftl"));
+        assertEquals("both 1", getTemplateContent(mtl, "both.ftl"));
     }
     
-    private String getTemplate(TemplateLoader tl, String name) throws IOException {
-        Object tSrc = tl.findTemplateSource(name);
-        if (tSrc == null) {
-            return null;
+    private String getTemplateContent(TemplateLoader tl, String name) throws IOException {
+        TemplateLoaderSession ses = tl.createSession();
+        try {
+            TemplateLoadingResult res = tl.load(name, null, null, ses);
+            if (res.getStatus() == TemplateLoadingResultStatus.NOT_FOUND) {
+                return null;
+            }
+            return IOUtils.toString(
+                    res.getReader() != null
+                            ? res.getReader()
+                            : new InputStreamReader(res.getInputStream(), StandardCharsets.UTF_8));
+        } finally {
+            if (ses != null) {
+                ses.close();
+            }
         }
-        
-        return IOUtils.toString(tl.getReader(tSrc, "UTF-8"));
     }
     
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/cache/TemplateCacheTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/cache/TemplateCacheTest.java b/src/test/java/freemarker/cache/TemplateCacheTest.java
index b1988b2..53763ca 100644
--- a/src/test/java/freemarker/cache/TemplateCacheTest.java
+++ b/src/test/java/freemarker/cache/TemplateCacheTest.java
@@ -19,29 +19,40 @@
 
 package freemarker.cache;
 
-import static org.junit.Assert.*;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertThat;
+import static org.junit.Assert.fail;
 
 import java.io.IOException;
-import java.io.Reader;
-import java.net.URL;
+import java.io.Serializable;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
 import java.util.Locale;
 
 import org.hamcrest.Matchers;
 import org.junit.Test;
 
+import com.google.common.collect.ImmutableList;
+
 import freemarker.core.ParseException;
 import freemarker.template.Configuration;
 import freemarker.template.MalformedTemplateNameException;
 import freemarker.template.Template;
 import freemarker.template.TemplateNotFoundException;
-import freemarker.template.Version;
+import freemarker.test.MonitoredTemplateLoader;
+import freemarker.test.MonitoredTemplateLoader.CloseSessionEvent;
+import freemarker.test.MonitoredTemplateLoader.CreateSessionEvent;
+import freemarker.test.MonitoredTemplateLoader.LoadEvent;
 
 public class TemplateCacheTest {
 
     @Test
     public void testCachedException() throws Exception {
         MockTemplateLoader loader = new MockTemplateLoader();
-        TemplateCache cache = new TemplateCache(loader, new StrongCacheStorage());
+        TemplateCache cache = new TemplateCache(
+                loader, new StrongCacheStorage(), new Configuration(Configuration.VERSION_3_0_0));
         cache.setDelay(1000L);
         loader.setThrowException(true);
         try {
@@ -49,7 +60,7 @@ public class TemplateCacheTest {
             fail();
         } catch (IOException e) {
             assertEquals("mock IO exception", e.getMessage());
-            assertEquals(1, loader.getFindCount());
+            assertEquals(1, loader.getLoadAttemptCount());
             try {
                 cache.getTemplate("t", Locale.getDefault(), "", true);
                 fail();
@@ -59,7 +70,7 @@ public class TemplateCacheTest {
                         Matchers.allOf(Matchers.containsString("There was an error loading the template on an " +
                         "earlier attempt")));
                 assertSame(e, e2.getCause());
-                assertEquals(1, loader.getFindCount());
+                assertEquals(1, loader.getLoadAttemptCount());
                 try {
                     Thread.sleep(1100L);
                     cache.getTemplate("t", Locale.getDefault(), "", true);
@@ -67,7 +78,7 @@ public class TemplateCacheTest {
                 } catch (IOException e3) {
                     // Cache had to retest
                     assertEquals("mock IO exception", e.getMessage());
-                    assertEquals(2, loader.getFindCount());
+                    assertEquals(2, loader.getLoadAttemptCount());
                 }
             }
         }
@@ -80,47 +91,46 @@ public class TemplateCacheTest {
         cache.setDelay(1000L);
         cache.setLocalizedLookup(false);
         assertNull(cache.getTemplate("t", Locale.getDefault(), "", true));
-        assertEquals(1, loader.getFindCount());
+        assertEquals(1, loader.getLoadAttemptCount());
         assertNull(cache.getTemplate("t", Locale.getDefault(), "", true));
         // Still 1 - returned cached exception
-        assertEquals(1, loader.getFindCount());
+        assertEquals(1, loader.getLoadAttemptCount());
         Thread.sleep(1100L);
         assertNull(cache.getTemplate("t", Locale.getDefault(), "", true));
         // Cache had to retest
-        assertEquals(2, loader.getFindCount());
+        assertEquals(2, loader.getLoadAttemptCount());
     }
 
     private static class MockTemplateLoader implements TemplateLoader {
         private boolean throwException;
-        private int findCount; 
+        private int loadAttemptCount; 
         
         public void setThrowException(boolean throwException) {
            this.throwException = throwException;
         }
         
-        public int getFindCount() {
-            return findCount;
+        public int getLoadAttemptCount() {
+            return loadAttemptCount;
         }
         
-        public void closeTemplateSource(Object templateSource)
-                throws IOException {
+        @Override
+        public TemplateLoaderSession createSession() {
+            return null;
         }
 
-        public Object findTemplateSource(String name) throws IOException {
-            ++findCount;
+        @Override
+        public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom,
+                Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws IOException {
+            ++loadAttemptCount;
             if (throwException) {
                 throw new IOException("mock IO exception");
             }
-            return null;
+            return TemplateLoadingResult.NOT_FOUND;
         }
 
-        public long getLastModified(Object templateSource) {
-            return 0;
-        }
-
-        public Reader getReader(Object templateSource, String encoding)
-                throws IOException {
-            return null;
+        @Override
+        public void resetState() {
+            //
         }
         
     }
@@ -194,103 +204,180 @@ public class TemplateCacheTest {
     }
 
     @Test
-    public void testZeroUpdateDelay() throws IOException {
-        Configuration cfg = new Configuration();
+    public void testZeroUpdateDelay() throws IOException, InterruptedException {
+        Configuration cfg = new Configuration(Configuration.VERSION_3_0_0);
         cfg.setLocale(Locale.US);
         cfg.setCacheStorage(new StrongCacheStorage());
-        StringTemplateLoader loader = new StringTemplateLoader();
+        MonitoredTemplateLoader loader = new MonitoredTemplateLoader();
         cfg.setTemplateLoader(loader);
-        cfg.setTemplateUpdateDelay(0);
+        cfg.setTemplateUpdateDelayMilliseconds(0);
         for (int i = 1; i <= 3; i++) {
-            loader.putTemplate("t.ftl", "v" + i, i);
+            loader.putTextTemplate("t.ftl", "v" + i);
             assertEquals("v" + i, cfg.getTemplate("t.ftl").toString());
         }
+
+        loader.clearEvents();
+        loader.putTextTemplate("t.ftl", "v8");
+        assertEquals("v8", cfg.getTemplate("t.ftl").toString());
+        assertEquals("v8", cfg.getTemplate("t.ftl").toString());
+        loader.putTextTemplate("t.ftl", "v9");
+        assertEquals("v9", cfg.getTemplate("t.ftl").toString());
+        assertEquals("v9", cfg.getTemplate("t.ftl").toString());
+        assertEquals(
+                ImmutableList.of(
+                        new LoadEvent("t_en_US.ftl", TemplateLoadingResultStatus.NOT_FOUND), // v8
+                        new LoadEvent("t_en.ftl", TemplateLoadingResultStatus.NOT_FOUND),
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.OPENED),
+
+                        new LoadEvent("t_en_US.ftl", TemplateLoadingResultStatus.NOT_FOUND), // v8
+                        new LoadEvent("t_en.ftl", TemplateLoadingResultStatus.NOT_FOUND),
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.NOT_MODIFIED),
+                        
+                        new LoadEvent("t_en_US.ftl", TemplateLoadingResultStatus.NOT_FOUND), // v9
+                        new LoadEvent("t_en.ftl", TemplateLoadingResultStatus.NOT_FOUND),
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.OPENED),
+
+                        new LoadEvent("t_en_US.ftl", TemplateLoadingResultStatus.NOT_FOUND), // v9
+                        new LoadEvent("t_en.ftl", TemplateLoadingResultStatus.NOT_FOUND),
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.NOT_MODIFIED)
+                ),
+                loader.getEvents(LoadEvent.class));
         
-        loader.putTemplate("t.ftl", "v10", 10);
+        cfg.setLocalizedLookup(false);
+        loader.clearEvents();
+        loader.putTextTemplate("t.ftl", "v10");
         assertEquals("v10", cfg.getTemplate("t.ftl").toString());
-        loader.putTemplate("t.ftl", "v11", 10); // same time stamp, different content
-        assertEquals("v10", cfg.getTemplate("t.ftl").toString()); // still v10
-        assertEquals("v10", cfg.getTemplate("t.ftl").toString()); // still v10
+        loader.putTextTemplate("t.ftl", "v11"); // same time stamp, different content
+        assertEquals("v11", cfg.getTemplate("t.ftl").toString());
+        assertEquals("v11", cfg.getTemplate("t.ftl").toString());
+        assertEquals("v11", cfg.getTemplate("t.ftl").toString());
+        Thread.sleep(17L);
+        assertEquals("v11", cfg.getTemplate("t.ftl").toString());
+        loader.putTextTemplate("t.ftl", "v12");
+        assertEquals("v12", cfg.getTemplate("t.ftl").toString());
+        assertEquals("v12", cfg.getTemplate("t.ftl").toString());
+        assertEquals(
+                ImmutableList.of(
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.OPENED), // v10
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.OPENED), // v11
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.NOT_MODIFIED),
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.NOT_MODIFIED),
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.NOT_MODIFIED),
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.OPENED), // v12
+                        new LoadEvent("t.ftl", TemplateLoadingResultStatus.NOT_MODIFIED)
+                ),
+                loader.getEvents(LoadEvent.class));
     }
     
     @Test
-    public void testIncompatibleImprovementsChangesURLConCaching() throws IOException {
-        Version newVersion = Configuration.VERSION_2_3_21;
-        Version oldVersion = Configuration.VERSION_2_3_20;
+    public void testWrongEncodingReload() throws IOException {
+        Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
+        cfg.setLocale(Locale.US);
+        
+        MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
+        tl.putBinaryTemplate("utf-8_en.ftl", "<#ftl encoding='utf-8'>B�ka");
+        tl.putBinaryTemplate("utf-8.ftl", "Bar");
+        tl.putBinaryTemplate("iso-8859-1_en_US.ftl", "<#ftl encoding='ISO-8859-1'>B�ka", StandardCharsets.ISO_8859_1,
+                "v1");
+        cfg.setTemplateLoader(tl);
         
         {
-            Configuration cfg = new Configuration(oldVersion);
-            cfg.setTemplateUpdateDelay(0);
-            final MonitoredClassTemplateLoader templateLoader = new MonitoredClassTemplateLoader();
-            assertNull(templateLoader.getURLConnectionUsesCaches());
-            cfg.setTemplateLoader(templateLoader);
-            
-            assertNull(templateLoader.getLastTemplateSourceModification());
-            cfg.getTemplate("test.ftl");
-            assertNull(templateLoader.getLastTemplateSourceModification());
+            Template t = cfg.getTemplate("utf-8.ftl", "Utf-8");
+            assertEquals("utf-8.ftl", t.getName());
+            assertEquals("utf-8_en.ftl", t.getSourceName());
+            assertEquals("Utf-8", t.getEncoding());
+            assertEquals("B�ka", t.toString());
             
-            cfg.setIncompatibleImprovements(newVersion);
-            assertNull(templateLoader.getLastTemplateSourceModification());
-            cfg.getTemplate("test.ftl");
-            assertEquals(Boolean.FALSE, templateLoader.getLastTemplateSourceModification());
+            assertEquals(
+                    ImmutableList.of(
+                            CreateSessionEvent.INSTANCE,
+                            new LoadEvent("utf-8_en_US.ftl", TemplateLoadingResultStatus.NOT_FOUND),
+                            new LoadEvent("utf-8_en.ftl", TemplateLoadingResultStatus.OPENED),
+                            CloseSessionEvent.INSTANCE),
+                    tl.getEvents());
+        }
+        
+        {
+            tl.clearEvents();
             
-            templateLoader.setURLConnectionUsesCaches(Boolean.valueOf(true));
-            templateLoader.setLastTemplateSourceModification(null);
-            cfg.getTemplate("test.ftl");
-            assertNull(templateLoader.getLastTemplateSourceModification());
+            Template t = cfg.getTemplate("utf-8.ftl", "ISO-8859-5");
+            assertEquals("utf-8.ftl", t.getName());
+            assertEquals("utf-8_en.ftl", t.getSourceName());
+            assertEquals("utf-8", t.getEncoding());
+            assertEquals("B�ka", t.toString());
             
-            templateLoader.setURLConnectionUsesCaches(Boolean.valueOf(false));
-            templateLoader.setLastTemplateSourceModification(null);
-            cfg.getTemplate("test.ftl");
-            assertNull(templateLoader.getLastTemplateSourceModification());
-
-            templateLoader.setURLConnectionUsesCaches(null);
-            templateLoader.setLastTemplateSourceModification(null);
-            cfg.getTemplate("test.ftl");
-            assertEquals(Boolean.FALSE, templateLoader.getLastTemplateSourceModification());
+            assertEquals(
+                    ImmutableList.of(
+                            CreateSessionEvent.INSTANCE,
+                            new LoadEvent("utf-8_en_US.ftl", TemplateLoadingResultStatus.NOT_FOUND),
+                            new LoadEvent("utf-8_en.ftl", TemplateLoadingResultStatus.OPENED),
+                            CloseSessionEvent.INSTANCE),
+                    tl.getEvents());
+        }
+        
+        {
+            tl.clearEvents();
             
-            templateLoader.setURLConnectionUsesCaches(null);
-            cfg.setIncompatibleImprovements(oldVersion);
-            templateLoader.setLastTemplateSourceModification(null);
-            cfg.getTemplate("test.ftl");
-            assertNull(templateLoader.getLastTemplateSourceModification());
+            Template t = cfg.getTemplate("iso-8859-1.ftl", "utf-8");
+            assertEquals("iso-8859-1.ftl", t.getName());
+            assertEquals("iso-8859-1_en_US.ftl", t.getSourceName());
+            assertEquals("ISO-8859-1", t.getEncoding());
+            assertEquals("B�ka", t.toString());
             
-            cfg.setTemplateLoader(new MultiTemplateLoader(
-                    new TemplateLoader[] { new MultiTemplateLoader(
-                                    new TemplateLoader[] { templateLoader }) }));
-            cfg.setIncompatibleImprovements(newVersion);
-            cfg.getTemplate("test.ftl");
-            assertEquals(Boolean.FALSE, templateLoader.getLastTemplateSourceModification());
+            assertEquals(
+                    ImmutableList.of(
+                            CreateSessionEvent.INSTANCE,
+                            new LoadEvent("iso-8859-1_en_US.ftl", TemplateLoadingResultStatus.OPENED),
+                            CloseSessionEvent.INSTANCE),
+                    tl.getEvents());
         }
     }
-    
+
     @Test
-    public void testWrongEncodingReload() throws IOException {
+    public void testNoWrongEncodingForTemplateLoader2WithReader() throws IOException {
         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
         cfg.setLocale(Locale.US);
         
-        StringTemplateLoader tl = new StringTemplateLoader();
-        tl.putTemplate("utf-8_en.ftl", "<#ftl encoding='utf-8'>Foo");
-        tl.putTemplate("utf-8.ftl", "Bar");
+        MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
+        tl.putTextTemplate("foo_en.ftl", "<#ftl encoding='utf-8'>\u0151");
+        tl.putTextTemplate("foo.ftl", "B");
         cfg.setTemplateLoader(tl);
         
         {
-            Template t = cfg.getTemplate("utf-8.ftl", "Utf-8");
-            assertEquals("utf-8.ftl", t.getName());
-            assertEquals("utf-8_en.ftl", t.getSourceName());
-            assertEquals("Utf-8", t.getEncoding());
-            assertEquals("Foo", t.toString());
+            Template t = cfg.getTemplate("foo.ftl", "Utf-8");
+            assertEquals("foo.ftl", t.getName());
+            assertEquals("foo_en.ftl", t.getSourceName());
+            assertNull(t.getEncoding());
+            assertEquals("\u0151", t.toString());
+            
+            assertEquals(
+                    ImmutableList.of(
+                            CreateSessionEvent.INSTANCE,
+                            new LoadEvent("foo_en_US.ftl", TemplateLoadingResultStatus.NOT_FOUND),
+                            new LoadEvent("foo_en.ftl", TemplateLoadingResultStatus.OPENED),
+                            CloseSessionEvent.INSTANCE),                
+                    tl.getEvents());
         }
         
         {
-            Template t = cfg.getTemplate("utf-8.ftl", "Utf-16");
-            assertEquals("utf-8.ftl", t.getName());
-            assertEquals("utf-8_en.ftl", t.getSourceName());
-            assertEquals("utf-8", t.getEncoding());
-            assertEquals("Foo", t.toString());
+            tl.clearEvents();
+            
+            Template t = cfg.getTemplate("foo.ftl", "iso-8859-1");
+            assertEquals("foo.ftl", t.getName());
+            assertEquals("foo_en.ftl", t.getSourceName());
+            assertNull(t.getEncoding());
+            assertEquals("\u0151", t.toString());
+            
+            assertEquals(
+                    ImmutableList.of(
+                            CreateSessionEvent.INSTANCE,
+                            new LoadEvent("foo_en_US.ftl", TemplateLoadingResultStatus.NOT_FOUND),
+                            new LoadEvent("foo_en.ftl", TemplateLoadingResultStatus.OPENED),
+                            CloseSessionEvent.INSTANCE),                
+                    tl.getEvents());
         }
     }
-
+    
     @Test
     public void testEncodingSelection() throws IOException {
         Locale hungary = new Locale("hu", "HU"); 
@@ -298,11 +385,11 @@ public class TemplateCacheTest {
         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
         cfg.setDefaultEncoding("utf-8");
         
-        StringTemplateLoader tl = new StringTemplateLoader();
-        tl.putTemplate("t.ftl", "Foo");
-        tl.putTemplate("t_de.ftl", "Vuu");
-        tl.putTemplate("t2.ftl", "<#ftl encoding='UTF-16LE'>Foo");
-        tl.putTemplate("t2_de.ftl", "<#ftl encoding='UTF-16BE'>Vuu");
+        MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
+        tl.putBinaryTemplate("t.ftl", "Foo");
+        tl.putBinaryTemplate("t_de.ftl", "Vuu");
+        tl.putBinaryTemplate("t2.ftl", "<#ftl encoding='ISO-8859-5'>\u043f\u0440\u0438\u043c\u0435\u0440", Charset.forName("ISO-8859-5"), "v1");
+        tl.putBinaryTemplate("t2_de.ftl", "<#ftl encoding='ISO-8859-5'>\u043f\u0440\u0438\u043c\u0435\u0440", Charset.forName("ISO-8859-5"), "v1");
         cfg.setTemplateLoader(tl);
 
         // No locale-to-encoding mapping exists yet:
@@ -343,22 +430,22 @@ public class TemplateCacheTest {
             Template t = cfg.getTemplate("t2.ftl", Locale.CHINESE);
             assertEquals("t2.ftl", t.getName());
             assertEquals("t2.ftl", t.getSourceName());
-            assertEquals("UTF-16LE", t.getEncoding());
-            assertEquals("Foo", t.toString());
+            assertEquals("ISO-8859-5", t.getEncoding());
+            assertEquals("\u043f\u0440\u0438\u043c\u0435\u0440", t.toString());
         }
         {
             Template t = cfg.getTemplate("t2.ftl", Locale.GERMANY);
             assertEquals("t2.ftl", t.getName());
             assertEquals("t2_de.ftl", t.getSourceName());
-            assertEquals("UTF-16BE", t.getEncoding());
-            assertEquals("Vuu", t.toString());
+            assertEquals("ISO-8859-5", t.getEncoding());
+            assertEquals("\u043f\u0440\u0438\u043c\u0435\u0440", t.toString());
         }
         {
             Template t = cfg.getTemplate("t2.ftl", hungary);
             assertEquals("t2.ftl", t.getName());
             assertEquals("t2.ftl", t.getSourceName());
-            assertEquals("UTF-16LE", t.getEncoding());
-            assertEquals("Foo", t.toString());
+            assertEquals("ISO-8859-5", t.getEncoding());
+            assertEquals("\u043f\u0440\u0438\u043c\u0435\u0440", t.toString());
         }
     }
     
@@ -390,44 +477,5 @@ public class TemplateCacheTest {
             // expected
         }
     }
-    
-    private static class MonitoredClassTemplateLoader extends ClassTemplateLoader {
-        
-        private Boolean lastTemplateSourceModification;
-
-        public MonitoredClassTemplateLoader() {
-            super(TemplateCacheTest.class, "");
-        }
-
-        @Override
-        public Object findTemplateSource(String name) throws IOException {
-            final URL url = getURL(name);
-            if (url == null) return null;
-            return new SpyingURLTemplateSource(url, getURLConnectionUsesCaches());
-        }
-
-        Boolean getLastTemplateSourceModification() {
-            return lastTemplateSourceModification;
-        }
-
-        void setLastTemplateSourceModification(Boolean lastTemplateSourceModification) {
-            this.lastTemplateSourceModification = lastTemplateSourceModification;
-        }
-        
-        private class SpyingURLTemplateSource extends URLTemplateSource {
-            
-            SpyingURLTemplateSource(URL url, Boolean useCaches) throws IOException {
-                super(url, useCaches);
-            }
-
-            @Override
-            void setUseCaches(boolean useCaches) {
-                setLastTemplateSourceModification(Boolean.valueOf(useCaches));
-                super.setUseCaches(useCaches);
-            }
-            
-        }
-        
-    }
 
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/cache/TemplateConfigurationFactoryTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/cache/TemplateConfigurationFactoryTest.java b/src/test/java/freemarker/cache/TemplateConfigurationFactoryTest.java
index 663eed2..af54e0a 100644
--- a/src/test/java/freemarker/cache/TemplateConfigurationFactoryTest.java
+++ b/src/test/java/freemarker/cache/TemplateConfigurationFactoryTest.java
@@ -18,8 +18,12 @@
  */
 package freemarker.cache;
 
-import static org.hamcrest.Matchers.*;
-import static org.junit.Assert.*;
+import static org.hamcrest.Matchers.containsString;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertThat;
+import static org.junit.Assert.fail;
 
 import java.io.IOException;
 import java.util.Arrays;
@@ -173,7 +177,7 @@ public class TemplateConfigurationFactoryTest {
         tcf.setConfiguration(cfg);
         
         try {
-            tcf.setConfiguration(Configuration.getDefaultConfiguration());
+            tcf.setConfiguration(new Configuration(Configuration.VERSION_3_0_0));
             fail();
         } catch (IllegalStateException e) {
             assertThat(e.getMessage(), containsString("TemplateConfigurationFactory"));
@@ -190,12 +194,12 @@ public class TemplateConfigurationFactoryTest {
 
     private void assertNotApplicable(TemplateConfigurationFactory tcf, String sourceName)
             throws IOException, TemplateConfigurationFactoryException {
-        assertNull(tcf.get(sourceName, "dummy"));
+        assertNull(tcf.get(sourceName, DummyTemplateLoadingSource.INSTANCE));
     }
 
     private void assertApplicable(TemplateConfigurationFactory tcf, String sourceName, TemplateConfiguration... expectedTCs)
             throws IOException, TemplateConfigurationFactoryException {
-        TemplateConfiguration mergedTC = tcf.get(sourceName, "dummy");
+        TemplateConfiguration mergedTC = tcf.get(sourceName, DummyTemplateLoadingSource.INSTANCE);
         assertNotNull("TC should have its parents Configuration set", mergedTC.getParentConfiguration());
         List<String> mergedTCAttNames = Arrays.asList(mergedTC.getCustomAttributeNames());
 
@@ -227,4 +231,9 @@ public class TemplateConfigurationFactoryTest {
         return false;
     }
     
+    @SuppressWarnings("serial")
+    private static class DummyTemplateLoadingSource implements TemplateLoadingSource {
+        private static DummyTemplateLoadingSource INSTANCE = new DummyTemplateLoadingSource();
+    }
+    
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/cache/TemplateNameFormatTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/cache/TemplateNameFormatTest.java b/src/test/java/freemarker/cache/TemplateNameFormatTest.java
index 499e751..ff9013e 100644
--- a/src/test/java/freemarker/cache/TemplateNameFormatTest.java
+++ b/src/test/java/freemarker/cache/TemplateNameFormatTest.java
@@ -19,9 +19,11 @@
 
 package freemarker.cache;
 
-import static freemarker.test.hamcerst.Matchers.*;
-import static org.hamcrest.Matchers.*;
-import static org.junit.Assert.*;
+import static freemarker.test.hamcerst.Matchers.containsStringIgnoringCase;
+import static org.hamcrest.Matchers.containsString;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThat;
+import static org.junit.Assert.fail;
 
 import java.io.IOException;
 import java.util.Locale;
@@ -227,7 +229,7 @@ public class TemplateNameFormatTest {
         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
 
         MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
-        tl.putTemplate("foo\\bar.ftl", "");
+        tl.putTextTemplate("foo\\bar.ftl", "");
         cfg.setTemplateLoader(tl);
 
         {
@@ -241,8 +243,8 @@ public class TemplateNameFormatTest {
                             "foo\\bar_en_US.ftl",
                             "foo\\bar_en.ftl",
                             name),
-                    tl.getTemplatesTried());
-            tl.clear();
+                    tl.getLoadNames());
+            tl.clearEvents();
         }
 
         try {
@@ -255,8 +257,8 @@ public class TemplateNameFormatTest {
                             "foo\\missing_en_US.ftl",
                             "foo\\missing_en.ftl",
                             "foo\\missing.ftl"),
-                    tl.getTemplatesTried());
-            tl.clear();
+                    tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/core/IncludeAndImportConfigurableLayersTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/core/IncludeAndImportConfigurableLayersTest.java b/src/test/java/freemarker/core/IncludeAndImportConfigurableLayersTest.java
index 96259d3..8ec5ede 100644
--- a/src/test/java/freemarker/core/IncludeAndImportConfigurableLayersTest.java
+++ b/src/test/java/freemarker/core/IncludeAndImportConfigurableLayersTest.java
@@ -26,7 +26,6 @@ import org.junit.Test;
 
 import freemarker.cache.ConditionalTemplateConfigurationFactory;
 import freemarker.cache.FileNameGlobMatcher;
-import freemarker.cache.StringTemplateLoader;
 import freemarker.template.Configuration;
 import freemarker.template.Template;
 import freemarker.test.TemplateTest;
@@ -317,9 +316,7 @@ public class IncludeAndImportConfigurableLayersTest extends TemplateTest {
     
     @Override
     protected Configuration createConfiguration() throws Exception {
-        Configuration cfg = new Configuration(Configuration.VERSION_2_3_24);
-        cfg.setTemplateLoader(new StringTemplateLoader());
-        return cfg;
+        return new Configuration(Configuration.VERSION_2_3_24);
     }
 
     @Override

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/core/IncludeAndImportTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/core/IncludeAndImportTest.java b/src/test/java/freemarker/core/IncludeAndImportTest.java
index 28161e5..8edbcf2 100644
--- a/src/test/java/freemarker/core/IncludeAndImportTest.java
+++ b/src/test/java/freemarker/core/IncludeAndImportTest.java
@@ -18,8 +18,11 @@
  */
 package freemarker.core;
 
-import static org.hamcrest.Matchers.*;
-import static org.junit.Assert.*;
+import static org.hamcrest.Matchers.allOf;
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.instanceOf;
+import static org.junit.Assert.assertThat;
+import static org.junit.Assert.fail;
 
 import java.io.IOException;
 import java.lang.reflect.Method;
@@ -28,7 +31,6 @@ import java.lang.reflect.Modifier;
 import org.junit.Before;
 import org.junit.Test;
 
-import freemarker.cache.StringTemplateLoader;
 import freemarker.core.Environment.LazilyInitializedNamespace;
 import freemarker.core.Environment.Namespace;
 import freemarker.template.Configuration;
@@ -40,13 +42,6 @@ import freemarker.test.TemplateTest;
 @SuppressWarnings("boxing")
 public class IncludeAndImportTest extends TemplateTest {
 
-    @Override
-    protected Configuration createConfiguration() throws Exception {
-        Configuration cfg = super.createConfiguration();
-        cfg.setTemplateLoader(new StringTemplateLoader());
-        return cfg;
-    }
-
     @Before
     public void setup() {
         addTemplate("inc1.ftl", "[inc1]<#global inc1Cnt = (inc1Cnt!0) + 1><#global history = (history!) + 'I'>");

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/core/ObjectBuilderSettingsTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/core/ObjectBuilderSettingsTest.java b/src/test/java/freemarker/core/ObjectBuilderSettingsTest.java
index a77777c..976cb79 100644
--- a/src/test/java/freemarker/core/ObjectBuilderSettingsTest.java
+++ b/src/test/java/freemarker/core/ObjectBuilderSettingsTest.java
@@ -32,7 +32,7 @@ import static org.junit.Assert.assertTrue;
 import static org.junit.Assert.fail;
 
 import java.io.IOException;
-import java.io.Reader;
+import java.io.Serializable;
 import java.io.Writer;
 import java.math.BigDecimal;
 import java.math.BigInteger;
@@ -54,6 +54,9 @@ import com.google.common.collect.ImmutableMap;
 import freemarker.cache.CacheStorage;
 import freemarker.cache.MruCacheStorage;
 import freemarker.cache.TemplateLoader;
+import freemarker.cache.TemplateLoaderSession;
+import freemarker.cache.TemplateLoadingResult;
+import freemarker.cache.TemplateLoadingSource;
 import freemarker.core.subpkg.PublicWithMixedConstructors;
 import freemarker.ext.beans.BeansWrapper;
 import freemarker.template.Configuration;
@@ -1504,22 +1507,19 @@ public class ObjectBuilderSettingsTest {
     public static class DummyTemplateLoader implements TemplateLoader {
 
         @Override
-        public Object findTemplateSource(String name) throws IOException {
+        public TemplateLoaderSession createSession() {
             return null;
         }
 
         @Override
-        public long getLastModified(Object templateSource) {
-            return 0;
-        }
-
-        @Override
-        public Reader getReader(Object templateSource, String encoding) throws IOException {
-            return null;
+        public TemplateLoadingResult load(String name, TemplateLoadingSource ifSourceDiffersFrom,
+                Serializable ifVersionDiffersFrom, TemplateLoaderSession session) throws IOException {
+            return TemplateLoadingResult.NOT_FOUND;
         }
 
         @Override
-        public void closeTemplateSource(Object templateSource) throws IOException {
+        public void resetState() {
+            // Do nothing
         }
         
     }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/core/TemplatGetEncodingTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/core/TemplatGetEncodingTest.java b/src/test/java/freemarker/core/TemplatGetEncodingTest.java
index a8ca84d..eb6578f 100644
--- a/src/test/java/freemarker/core/TemplatGetEncodingTest.java
+++ b/src/test/java/freemarker/core/TemplatGetEncodingTest.java
@@ -18,13 +18,17 @@
  */
 package freemarker.core;
 
-import static org.junit.Assert.*;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotSame;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
 
 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
 
 import org.junit.Test;
 
-import freemarker.cache.StringTemplateLoader;
+import freemarker.cache.ByteArrayTemplateLoader;
 import freemarker.cache.StrongCacheStorage;
 import freemarker.template.Configuration;
 import freemarker.template.MalformedTemplateNameException;
@@ -38,9 +42,9 @@ public class TemplatGetEncodingTest {
         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
         {
             cfg.setDefaultEncoding("ISO-8859-2");
-            StringTemplateLoader tl = new StringTemplateLoader();
-            tl.putTemplate("t", "test");
-            tl.putTemplate("tnp", "<#test>");
+            ByteArrayTemplateLoader tl = new ByteArrayTemplateLoader();
+            tl.putTemplate("t", "test".getBytes(StandardCharsets.UTF_8));
+            tl.putTemplate("tnp", "<#test>".getBytes(StandardCharsets.UTF_8));
             cfg.setTemplateLoader(tl);
             cfg.setCacheStorage(new StrongCacheStorage());
         }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/ext/jsp/RealServletContainertTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/ext/jsp/RealServletContainertTest.java b/src/test/java/freemarker/ext/jsp/RealServletContainertTest.java
index f3ef4cf..685a6e5 100644
--- a/src/test/java/freemarker/ext/jsp/RealServletContainertTest.java
+++ b/src/test/java/freemarker/ext/jsp/RealServletContainertTest.java
@@ -47,7 +47,7 @@ import com.google.common.collect.ImmutableSet;
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
 import freemarker.cache.ClassTemplateLoader;
 import freemarker.cache.TemplateLoader;
-import freemarker.cache.WebappTemplateLoader;
+import freemarker.cache.WebAppTemplateLoader;
 import freemarker.ext.beans.BeansWrapper;
 import freemarker.ext.beans.BeansWrapperBuilder;
 import freemarker.ext.servlet.FreemarkerServlet;
@@ -432,7 +432,7 @@ public class RealServletContainertTest extends WebAppTestCase {
             cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER);
             cfg.setLogTemplateExceptions(true);
             cfg.setObjectWrapper(new BeansWrapperBuilder(Configuration.VERSION_2_3_21).build());
-            cfg.setTemplateLoader(new WebappTemplateLoader(getServletContext()));
+            cfg.setTemplateLoader(new WebAppTemplateLoader(getServletContext()));
             return cfg;
         }
 
@@ -452,7 +452,7 @@ public class RealServletContainertTest extends WebAppTestCase {
             
             {
                 TemplateLoader tl = cfg.getTemplateLoader();
-                assertTrue(tl instanceof WebappTemplateLoader);
+                assertTrue(tl instanceof WebAppTemplateLoader);
             }
             
         }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java b/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java
index 396e4ca..e97e7e2 100644
--- a/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java
+++ b/src/test/java/freemarker/ext/servlet/FreemarkerServletTest.java
@@ -18,11 +18,22 @@
  */
 package freemarker.ext.servlet;
 
-import static freemarker.ext.servlet.FreemarkerServlet.*;
-import static org.hamcrest.Matchers.*;
-import static org.junit.Assert.*;
+import static freemarker.ext.servlet.FreemarkerServlet.INIT_PARAM_CONTENT_TYPE;
+import static freemarker.ext.servlet.FreemarkerServlet.INIT_PARAM_OVERRIDE_RESPONSE_CONTENT_TYPE;
+import static freemarker.ext.servlet.FreemarkerServlet.INIT_PARAM_OVERRIDE_RESPONSE_LOCALE;
+import static freemarker.ext.servlet.FreemarkerServlet.INIT_PARAM_RESPONSE_CHARACTER_ENCODING;
+import static freemarker.ext.servlet.FreemarkerServlet.INIT_PARAM_VALUE_ALWAYS;
+import static freemarker.ext.servlet.FreemarkerServlet.INIT_PARAM_VALUE_NEVER;
+import static freemarker.ext.servlet.FreemarkerServlet.INIT_PARAM_VALUE_WHEN_TEMPLATE_HAS_MIME_TYPE;
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.instanceOf;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertThat;
+import static org.junit.Assert.fail;
 
 import java.io.IOException;
+import java.nio.charset.StandardCharsets;
 import java.nio.charset.UnsupportedCharsetException;
 import java.util.Locale;
 
@@ -38,10 +49,10 @@ import org.springframework.mock.web.MockHttpServletResponse;
 import org.springframework.mock.web.MockServletConfig;
 import org.springframework.mock.web.MockServletContext;
 
+import freemarker.cache.ByteArrayTemplateLoader;
 import freemarker.cache.ConditionalTemplateConfigurationFactory;
 import freemarker.cache.FileNameGlobMatcher;
 import freemarker.cache.FirstMatchTemplateConfigurationFactory;
-import freemarker.cache.StringTemplateLoader;
 import freemarker.cache.TemplateLoader;
 import freemarker.core.Environment;
 import freemarker.core.TemplateConfiguration;
@@ -567,23 +578,38 @@ public class FreemarkerServletTest {
         protected TemplateLoader createTemplateLoader(String templatePath) throws IOException {
             // Override default template loader
             if (templatePath.equals("class://")) {
-                StringTemplateLoader tl = new StringTemplateLoader();
+                ByteArrayTemplateLoader tl = new ByteArrayTemplateLoader();
                 
-                tl.putTemplate(FOO_FTL, "foo");
-                tl.putTemplate(FOO_SRC_UTF8_FTL, "foo");
-                tl.putTemplate(FOO_OUT_UTF8_FTL, "foo");
-                tl.putTemplate(CONTENT_TYPE_ATTR_FTL, "<#ftl attributes={ 'content_type': 'text/plain' }>foo");
-                tl.putTemplate(CONTENT_TYPE_ATTR_WITH_CHARSET_FTL, "<#ftl attributes={ 'content_type': 'text/plain; charset=UTF-8' }>foo");
-                tl.putTemplate(OUTPUT_FORMAT_HEADER_FTL, "<#ftl outputFormat='plainText'>foo");
+                tl.putTemplate(FOO_FTL, "foo"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(FOO_SRC_UTF8_FTL, "foo"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(FOO_OUT_UTF8_FTL, "foo"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(CONTENT_TYPE_ATTR_FTL, "<#ftl attributes={ 'content_type': 'text/plain' }>foo"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(CONTENT_TYPE_ATTR_WITH_CHARSET_FTL,
+                        "<#ftl attributes={ 'content_type': 'text/plain; charset=UTF-8' }>foo"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(OUTPUT_FORMAT_HEADER_FTL, "<#ftl outputFormat='plainText'>foo"
+                        .getBytes(StandardCharsets.UTF_8));
                 
-                tl.putTemplate(STD_OUTPUT_FORMAT_HTML_FTL, "<#ftl outputFormat='HTML'>");
-                tl.putTemplate(STD_OUTPUT_FORMAT_XHTML_FTL, "<#ftl outputFormat='XHTML'>");
-                tl.putTemplate(STD_OUTPUT_FORMAT_XML_FTL, "<#ftl outputFormat='XML'>");
-                tl.putTemplate(STD_OUTPUT_FORMAT_JAVA_SCRIPT_FTL, "<#ftl outputFormat='JavaScript'>");
-                tl.putTemplate(STD_OUTPUT_FORMAT_JSON_FTL, "<#ftl outputFormat='JSON'>");
-                tl.putTemplate(STD_OUTPUT_FORMAT_CSS_FTL, "<#ftl outputFormat='CSS'>");
-                tl.putTemplate(STD_OUTPUT_FORMAT_PLAIN_TEXT_FTL, "<#ftl outputFormat='plainText'>");
-                tl.putTemplate(STD_OUTPUT_FORMAT_RTF_FTL, "<#ftl outputFormat='RTF'>");
+                tl.putTemplate(STD_OUTPUT_FORMAT_HTML_FTL, "<#ftl outputFormat='HTML'>"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(STD_OUTPUT_FORMAT_XHTML_FTL, "<#ftl outputFormat='XHTML'>"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(STD_OUTPUT_FORMAT_XML_FTL, "<#ftl outputFormat='XML'>"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(STD_OUTPUT_FORMAT_JAVA_SCRIPT_FTL, "<#ftl outputFormat='JavaScript'>"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(STD_OUTPUT_FORMAT_JSON_FTL, "<#ftl outputFormat='JSON'>"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(STD_OUTPUT_FORMAT_CSS_FTL, "<#ftl outputFormat='CSS'>"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(STD_OUTPUT_FORMAT_PLAIN_TEXT_FTL, "<#ftl outputFormat='plainText'>"
+                        .getBytes(StandardCharsets.UTF_8));
+                tl.putTemplate(STD_OUTPUT_FORMAT_RTF_FTL, "<#ftl outputFormat='RTF'>"
+                        .getBytes(StandardCharsets.UTF_8));
                 
                 return tl;
             } else {

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/ext/servlet/InitParamParserTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/ext/servlet/InitParamParserTest.java b/src/test/java/freemarker/ext/servlet/InitParamParserTest.java
index 4408d0d..1970035 100644
--- a/src/test/java/freemarker/ext/servlet/InitParamParserTest.java
+++ b/src/test/java/freemarker/ext/servlet/InitParamParserTest.java
@@ -18,8 +18,13 @@
  */
 package freemarker.ext.servlet;
 
-import static org.hamcrest.Matchers.*;
-import static org.junit.Assert.*;
+import static org.hamcrest.Matchers.containsString;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertThat;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
 
 import java.io.IOException;
 import java.util.Collections;
@@ -30,7 +35,7 @@ import com.google.common.collect.ImmutableList;
 
 import freemarker.cache.ClassTemplateLoader;
 import freemarker.cache.MultiTemplateLoader;
-import freemarker.cache.WebappTemplateLoader;
+import freemarker.cache.WebAppTemplateLoader;
 import freemarker.template.Configuration;
 import freemarker.template.MockServletContext;
 
@@ -64,28 +69,28 @@ public class InitParamParserTest {
 
     @Test
     public void testCreateTemplateLoader() throws IOException {
-        Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
+        Configuration cfg = new Configuration(Configuration.VERSION_3_0_0);
 
         {
             ClassTemplateLoader ctl = (ClassTemplateLoader) InitParamParser.createTemplateLoader(
                     "classpath:templates",
                     cfg, this.getClass(), null);
             assertEquals("templates/", ctl.getBasePackagePath());
-            assertNull(ctl.getURLConnectionUsesCaches());
+            assertEquals(Boolean.FALSE, ctl.getURLConnectionUsesCaches());
         }
 
         {
             ClassTemplateLoader ctl = (ClassTemplateLoader) InitParamParser.createTemplateLoader(
-                    "classpath:templates?settings(URLConnectionUsesCaches=false)",
+                    "classpath:templates?settings(URLConnectionUsesCaches=true)",
                     cfg, this.getClass(), null);
             assertEquals("templates/", ctl.getBasePackagePath());
-            assertEquals(Boolean.FALSE, ctl.getURLConnectionUsesCaches());
+            assertEquals(Boolean.TRUE, ctl.getURLConnectionUsesCaches());
         }
 
         {
             MultiTemplateLoader mtl = (MultiTemplateLoader) InitParamParser.createTemplateLoader(
                     "["
-                    + "templates?settings(URLConnectionUsesCaches=false, attemptFileAccess=false), "
+                    + "templates?settings(URLConnectionUsesCaches=null, attemptFileAccess=false), "
                     + "foo/templates?settings(URLConnectionUsesCaches=true), "
                     + "classpath:templates, "
                     + "classpath:foo/templates?settings(URLConnectionUsesCaches=true)"
@@ -94,16 +99,16 @@ public class InitParamParserTest {
 
             assertEquals(4, mtl.getTemplateLoaderCount());
             
-            final WebappTemplateLoader tl1 = (WebappTemplateLoader) mtl.getTemplateLoader(0);
-            assertEquals(Boolean.FALSE, tl1.getURLConnectionUsesCaches());
+            final WebAppTemplateLoader tl1 = (WebAppTemplateLoader) mtl.getTemplateLoader(0);
+            assertNull(tl1.getURLConnectionUsesCaches());
             assertFalse(tl1.getAttemptFileAccess());
             
-            final WebappTemplateLoader tl2 = (WebappTemplateLoader) mtl.getTemplateLoader(1);
+            final WebAppTemplateLoader tl2 = (WebAppTemplateLoader) mtl.getTemplateLoader(1);
             assertEquals(Boolean.TRUE, tl2.getURLConnectionUsesCaches());
             assertTrue(tl2.getAttemptFileAccess());
             
             final ClassTemplateLoader tl3 = (ClassTemplateLoader) mtl.getTemplateLoader(2);
-            assertNull(tl3.getURLConnectionUsesCaches());
+            assertEquals(Boolean.FALSE, tl3.getURLConnectionUsesCaches());
             
             final ClassTemplateLoader tl4 = (ClassTemplateLoader) mtl.getTemplateLoader(3);
             assertEquals(Boolean.TRUE, tl4.getURLConnectionUsesCaches());

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/manual/ExamplesTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/manual/ExamplesTest.java b/src/test/java/freemarker/manual/ExamplesTest.java
index 6ea8254..2ffcb55 100644
--- a/src/test/java/freemarker/manual/ExamplesTest.java
+++ b/src/test/java/freemarker/manual/ExamplesTest.java
@@ -24,9 +24,9 @@ import java.util.Properties;
 
 import org.junit.Ignore;
 
+import freemarker.cache.ByteArrayTemplateLoader;
 import freemarker.cache.ClassTemplateLoader;
 import freemarker.cache.MultiTemplateLoader;
-import freemarker.cache.StringTemplateLoader;
 import freemarker.cache.TemplateLoader;
 import freemarker.template.Configuration;
 import freemarker.test.TemplateTest;
@@ -54,7 +54,7 @@ public abstract class ExamplesTest extends TemplateTest {
 
     protected void setupTemplateLoaders(Configuration cfg) {
         cfg.setTemplateLoader(new MultiTemplateLoader(
-                new TemplateLoader[] { new StringTemplateLoader(), new ClassTemplateLoader(this.getClass(), "") }));
+                new TemplateLoader[] { new ByteArrayTemplateLoader(), new ClassTemplateLoader(this.getClass(), "") }));
     }
     
 }

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/template/ConfigurationTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/template/ConfigurationTest.java b/src/test/java/freemarker/template/ConfigurationTest.java
index 58b8724..31e8e53 100644
--- a/src/test/java/freemarker/template/ConfigurationTest.java
+++ b/src/test/java/freemarker/template/ConfigurationTest.java
@@ -33,6 +33,7 @@ import static org.junit.Assert.assertThat;
 import java.io.IOException;
 import java.io.StringWriter;
 import java.lang.reflect.Field;
+import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
@@ -49,8 +50,8 @@ import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ImmutableMap;
 
 import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
+import freemarker.cache.ByteArrayTemplateLoader;
 import freemarker.cache.CacheStorageWithGetSize;
-import freemarker.cache.FileTemplateLoader;
 import freemarker.cache.NullCacheStorage;
 import freemarker.cache.SoftCacheStorage;
 import freemarker.cache.StringTemplateLoader;
@@ -102,7 +103,6 @@ public class ConfigurationTest extends TestCase {
         
         Configuration cfg = new Configuration();
         assertUsesLegacyObjectWrapper(cfg);
-        assertUsesLegacyTemplateLoader(cfg);
         assertEquals(cfg.getIncompatibleImprovements(), Configuration.VERSION_2_3_0);
         
         cfg.setIncompatibleImprovements(newVersion);
@@ -111,10 +111,8 @@ public class ConfigurationTest extends TestCase {
         
         cfg.setIncompatibleImprovements(oldVersion);
         assertUsesLegacyObjectWrapper(cfg);
-        assertUsesLegacyTemplateLoader(cfg);
         cfg.setIncompatibleImprovements(oldVersion);
         assertUsesLegacyObjectWrapper(cfg);
-        assertUsesLegacyTemplateLoader(cfg);
         
         cfg.setIncompatibleImprovements(newVersion);
         assertUsesNewObjectWrapper(cfg);
@@ -126,7 +124,6 @@ public class ConfigurationTest extends TestCase {
         cfg.setObjectWrapper(new SimpleObjectWrapper());
         cfg.setIncompatibleImprovements(oldVersion);
         assertSame(SimpleObjectWrapper.class, cfg.getObjectWrapper().getClass());
-        assertUsesLegacyTemplateLoader(cfg);
         
         cfg.setTemplateLoader(new StringTemplateLoader());
         cfg.setIncompatibleImprovements(newVersion);
@@ -149,7 +146,6 @@ public class ConfigurationTest extends TestCase {
 
         cfg.setIncompatibleImprovements(oldVersion);
         assertUsesLegacyObjectWrapper(cfg);
-        assertUsesLegacyTemplateLoader(cfg);
 
         cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_22);
         assertUses2322ObjectWrapper(cfg);
@@ -163,7 +159,6 @@ public class ConfigurationTest extends TestCase {
         
         cfg.setIncompatibleImprovements(oldVersion);
         assertUsesLegacyObjectWrapper(cfg);
-        assertUsesLegacyTemplateLoader(cfg);
         
         // ---
         
@@ -222,7 +217,7 @@ public class ConfigurationTest extends TestCase {
         }
         
         assertFalse(cfg.isTemplateLoaderExplicitlySet());
-        assertTrue(cfg.getTemplateLoader() instanceof FileTemplateLoader);
+        assertNull(cfg.getTemplateLoader());
         //
         cfg.setTemplateLoader(null);
         assertTrue(cfg.isTemplateLoaderExplicitlySet());
@@ -230,11 +225,11 @@ public class ConfigurationTest extends TestCase {
         //
         for (int i = 0; i < 3; i++) {
             if (i == 2) {
-                cfg.setTemplateLoader(cfg.getTemplateLoader());
+                cfg.setTemplateLoader(new StringTemplateLoader());
             }
             cfg.unsetTemplateLoader();
             assertFalse(cfg.isTemplateLoaderExplicitlySet());
-            assertTrue(cfg.getTemplateLoader() instanceof FileTemplateLoader);
+            assertNull(cfg.getTemplateLoader());
         }
         
         assertFalse(cfg.isTemplateLookupStrategyExplicitlySet());
@@ -279,22 +274,7 @@ public class ConfigurationTest extends TestCase {
     }
     
     public void testTemplateLoadingErrors() throws Exception {
-        Configuration cfg = new Configuration();
-        try {
-            cfg.getTemplate("missing.ftl");
-            fail();
-        } catch (TemplateNotFoundException e) {
-            assertThat(e.getMessage(), allOf(containsString("wasn't set"), containsString("default")));
-        }
-        
-        cfg = new Configuration(Configuration.VERSION_2_3_21);
-        try {
-            cfg.getTemplate("missing.ftl");
-            fail();
-        } catch (TemplateNotFoundException e) {
-            assertThat(e.getMessage(), allOf(containsString("wasn't set"), not(containsString("default"))));
-        }
-        
+        Configuration cfg = new Configuration(Configuration.VERSION_3_0_0);
         cfg.setClassForTemplateLoading(this.getClass(), "nosuchpackage");
         try {
             cfg.getTemplate("missing.ftl");
@@ -318,10 +298,6 @@ public class ConfigurationTest extends TestCase {
         assertNull(cfg.getTemplateLoader());
     }
     
-    private void assertUsesLegacyTemplateLoader(Configuration cfg) {
-        assertTrue(cfg.getTemplateLoader() instanceof FileTemplateLoader);
-    }
-    
     public void testVersion() {
         Version v = Configuration.getVersion();
         assertTrue(v.intValue() > _TemplateAPI.VERSION_INT_2_3_20);
@@ -375,10 +351,10 @@ public class ConfigurationTest extends TestCase {
         cfg.setDefaultEncoding(latin1);
         cfg.setEncoding(hu, latin2);
         
-        StringTemplateLoader tl = new StringTemplateLoader();
-        tl.putTemplate(tFtl, "${1}");
-        tl.putTemplate(tEnFtl, "${1}");
-        tl.putTemplate(tUtf8Ftl, "<#ftl encoding='utf-8'>");
+        ByteArrayTemplateLoader tl = new ByteArrayTemplateLoader();
+        tl.putTemplate(tFtl, "${1}".getBytes(StandardCharsets.UTF_8));
+        tl.putTemplate(tEnFtl, "${1}".getBytes(StandardCharsets.UTF_8));
+        tl.putTemplate(tUtf8Ftl, "<#ftl encoding='utf-8'>".getBytes(StandardCharsets.UTF_8));
         cfg.setTemplateLoader(tl);
         
         // 1 args:

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/template/TemplateLookupStrategyTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/template/TemplateLookupStrategyTest.java b/src/test/java/freemarker/template/TemplateLookupStrategyTest.java
index 2a40c62..e0e4af4 100644
--- a/src/test/java/freemarker/template/TemplateLookupStrategyTest.java
+++ b/src/test/java/freemarker/template/TemplateLookupStrategyTest.java
@@ -19,7 +19,11 @@
 
 package freemarker.template;
 
-import static org.junit.Assert.*;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertSame;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
 
 import java.io.IOException;
 import java.io.StringWriter;
@@ -54,8 +58,8 @@ public class TemplateLookupStrategyTest {
         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
         
         MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
-        tl.putTemplate("test.ftl", "");
-        tl.putTemplate("aa/test.ftl", "");
+        tl.putTextTemplate("test.ftl", "");
+        tl.putTextTemplate("aa/test.ftl", "");
         cfg.setTemplateLoader(tl);
         
         cfg.setTemplateLookupStrategy(MyTemplateLookupStrategy.INSTANCE);
@@ -67,8 +71,8 @@ public class TemplateLookupStrategyTest {
             fail();
         } catch (TemplateNotFoundException e) {
             assertEquals("missing.ftl", e.getTemplateName());
-            assertEquals(ImmutableList.of("aa/missing.ftl", "missing.ftl"), tl.getTemplatesTried());
-            tl.clear();
+            assertEquals(ImmutableList.of("aa/missing.ftl", "missing.ftl"), tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -78,8 +82,8 @@ public class TemplateLookupStrategyTest {
             assertEquals("aa/test.ftl", t.getSourceName());
             assertEquals(locale, t.getLocale());
             assertNull(t.getCustomLookupCondition());
-            assertEquals(ImmutableList.of("aa/test.ftl"), tl.getTemplatesTried());
-            tl.clear();
+            assertEquals(ImmutableList.of("aa/test.ftl"), tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
     }
@@ -89,11 +93,11 @@ public class TemplateLookupStrategyTest {
         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
         
         MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
-        tl.putTemplate("test.ftl", "");
-        tl.putTemplate("test_aa.ftl", "");
-        tl.putTemplate("test_aa_BB.ftl", "");
-        tl.putTemplate("test_aa_BB_CC.ftl", "");
-        tl.putTemplate("test_aa_BB_CC_DD.ftl", "");
+        tl.putTextTemplate("test.ftl", "");
+        tl.putTextTemplate("test_aa.ftl", "");
+        tl.putTextTemplate("test_aa_BB.ftl", "");
+        tl.putTextTemplate("test_aa_BB_CC.ftl", "");
+        tl.putTextTemplate("test_aa_BB_CC_DD.ftl", "");
         cfg.setTemplateLoader(tl);
         
         try {
@@ -108,8 +112,8 @@ public class TemplateLookupStrategyTest {
                             "missing_aa_BB.ftl",
                             "missing_aa.ftl",
                             "missing.ftl"),
-                    tl.getTemplatesTried());
-            tl.clear();
+                    tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -121,8 +125,8 @@ public class TemplateLookupStrategyTest {
             assertEquals("missing.ftl", e.getTemplateName());
             assertEquals(
                     ImmutableList.of("missing_xx.ftl", "missing.ftl"),
-                    tl.getTemplatesTried());
-            tl.clear();
+                    tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -134,8 +138,8 @@ public class TemplateLookupStrategyTest {
             assertEquals("missing.ftl", e.getTemplateName());
             assertEquals(
                     ImmutableList.of("missing.ftl"),
-                    tl.getTemplatesTried());
-            tl.clear();
+                    tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         cfg.setLocalizedLookup(true);
@@ -147,8 +151,8 @@ public class TemplateLookupStrategyTest {
             assertEquals("_a_b_.ftl", e.getTemplateName());
             assertEquals(
                     ImmutableList.of("_a_b__xx_YY.ftl", "_a_b__xx.ftl", "_a_b_.ftl"),
-                    tl.getTemplatesTried());
-            tl.clear();
+                    tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
 
@@ -160,9 +164,9 @@ public class TemplateLookupStrategyTest {
                 assertEquals("test_aa_BB_CC_DD.ftl", t.getSourceName());
                 assertEquals(locale, t.getLocale());
                 assertNull(t.getCustomLookupCondition());
-                assertEquals(ImmutableList.of("test_aa_BB_CC_DD.ftl"), tl.getTemplatesTried());
+                assertEquals(ImmutableList.of("test_aa_BB_CC_DD.ftl"), tl.getLoadNames());
                 assertNull(t.getCustomLookupCondition());
-                tl.clear();
+                tl.clearEvents();
                 cfg.clearTemplateCache();
             }
             
@@ -173,8 +177,8 @@ public class TemplateLookupStrategyTest {
                 assertEquals("test_aa_BB_CC.ftl", t.getSourceName());
                 assertEquals(locale, t.getLocale());
                 assertNull(t.getCustomLookupCondition());
-                assertEquals(ImmutableList.of("test_aa_BB_CC_XX.ftl", "test_aa_BB_CC.ftl"), tl.getTemplatesTried());
-                tl.clear();
+                assertEquals(ImmutableList.of("test_aa_BB_CC_XX.ftl", "test_aa_BB_CC.ftl"), tl.getLoadNames());
+                tl.clearEvents();
                 cfg.clearTemplateCache();
             }
             
@@ -187,8 +191,8 @@ public class TemplateLookupStrategyTest {
                 assertNull(t.getCustomLookupCondition());
                 assertEquals(
                         ImmutableList.of("test_aa_BB_XX_XX.ftl", "test_aa_BB_XX.ftl", "test_aa_BB.ftl"),
-                        tl.getTemplatesTried());
-                tl.clear();
+                        tl.getLoadNames());
+                tl.clearEvents();
                 cfg.clearTemplateCache();
             }
     
@@ -202,8 +206,8 @@ public class TemplateLookupStrategyTest {
                 assertNull(t.getCustomLookupCondition());
                 assertEquals(
                         ImmutableList.of("test.ftl"),
-                        tl.getTemplatesTried());
-                tl.clear();
+                        tl.getLoadNames());
+                tl.clearEvents();
                 cfg.clearTemplateCache();
                 cfg.setLocalizedLookup(true);
             }
@@ -217,8 +221,8 @@ public class TemplateLookupStrategyTest {
                 assertNull(t.getCustomLookupCondition());
                 assertEquals(
                         ImmutableList.of("test_aa_XX_XX_XX.ftl", "test_aa_XX_XX.ftl", "test_aa_XX.ftl", "test_aa.ftl"),
-                        tl.getTemplatesTried());
-                tl.clear();
+                        tl.getLoadNames());
+                tl.clearEvents();
                 cfg.clearTemplateCache();
             }
             
@@ -232,8 +236,8 @@ public class TemplateLookupStrategyTest {
                 assertEquals(
                         ImmutableList.of(
                                 "test_xx_XX_XX_XX.ftl", "test_xx_XX_XX.ftl", "test_xx_XX.ftl", "test_xx.ftl", "test.ftl"),
-                        tl.getTemplatesTried());
-                tl.clear();
+                        tl.getLoadNames());
+                tl.clearEvents();
                 cfg.clearTemplateCache();
             }
             
@@ -247,8 +251,8 @@ public class TemplateLookupStrategyTest {
                 assertEquals(
                         ImmutableList.of(
                             "test_xx_BB_CC_DD.ftl", "test_xx_BB_CC.ftl", "test_xx_BB.ftl", "test_xx.ftl", "test.ftl"),
-                        tl.getTemplatesTried());
-                tl.clear();
+                        tl.getLoadNames());
+                tl.clearEvents();
                 cfg.clearTemplateCache();
             }
         }
@@ -259,9 +263,9 @@ public class TemplateLookupStrategyTest {
         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
         
         MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
-        tl.putTemplate("t.ftl", "");
-        tl.putTemplate("sub/i.ftl", "");
-        tl.putTemplate("x/sub/i.ftl", "");
+        tl.putTextTemplate("t.ftl", "");
+        tl.putTextTemplate("sub/i.ftl", "");
+        tl.putTextTemplate("x/sub/i.ftl", "");
         cfg.setTemplateLoader(tl);
 
         final Locale locale = new Locale("xx");
@@ -276,8 +280,8 @@ public class TemplateLookupStrategyTest {
                     ImmutableList.of(
                         "x/y/sub/i_xx.ftl", "x/sub/i_xx.ftl", "sub/i_xx.ftl",
                         "x/y/sub/i.ftl", "x/sub/i.ftl"),
-                    tl.getTemplatesTried());
-            tl.clear();
+                    tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
 
@@ -291,8 +295,8 @@ public class TemplateLookupStrategyTest {
                     ImmutableList.of(
                         "a/b/sub/i_xx.ftl", "a/sub/i_xx.ftl", "sub/i_xx.ftl",
                         "a/b/sub/i.ftl", "a/sub/i.ftl", "sub/i.ftl"),
-                    tl.getTemplatesTried());
-            tl.clear();
+                    tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
     }
@@ -318,17 +322,17 @@ public class TemplateLookupStrategyTest {
         final String t2OtherLocaleExpectedOutput = "i3 at foo.com";
         
         MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
-        tl.putTemplate("@foo.com/t.ftl", tAtFooComContent);
-        tl.putTemplate("@bar.com/t.ftl", tAtBarComContent);
-        tl.putTemplate("@default/t.ftl", tAtDefaultContent);
-        tl.putTemplate("@foo.com/i.ftl", iAtFooComContent);
-        tl.putTemplate("@baaz.com/i.ftl", iAtBaazComContent);
-        tl.putTemplate("@default/i_xx.ftl", iXxAtDefaultContent);
-        tl.putTemplate("@default/i.ftl", iAtDefaultContent);
-        tl.putTemplate("@foo.com/t2.ftl", "<#import 'i2.ftl' as i2 />${proof}");
-        tl.putTemplate("@default/i2.ftl", "<#import 'i3.ftl' as i3 />");
-        tl.putTemplate("@foo.com/i3.ftl", "<#global proof = '" + t2OtherLocaleExpectedOutput + "'>");
-        tl.putTemplate("@foo.com/i3_xx.ftl", "<#global proof = '" + t2XxLocaleExpectedOutput + "'>");
+        tl.putTextTemplate("@foo.com/t.ftl", tAtFooComContent);
+        tl.putTextTemplate("@bar.com/t.ftl", tAtBarComContent);
+        tl.putTextTemplate("@default/t.ftl", tAtDefaultContent);
+        tl.putTextTemplate("@foo.com/i.ftl", iAtFooComContent);
+        tl.putTextTemplate("@baaz.com/i.ftl", iAtBaazComContent);
+        tl.putTextTemplate("@default/i_xx.ftl", iXxAtDefaultContent);
+        tl.putTextTemplate("@default/i.ftl", iAtDefaultContent);
+        tl.putTextTemplate("@foo.com/t2.ftl", "<#import 'i2.ftl' as i2 />${proof}");
+        tl.putTextTemplate("@default/i2.ftl", "<#import 'i3.ftl' as i3 />");
+        tl.putTextTemplate("@foo.com/i3.ftl", "<#global proof = '" + t2OtherLocaleExpectedOutput + "'>");
+        tl.putTextTemplate("@foo.com/i3_xx.ftl", "<#global proof = '" + t2XxLocaleExpectedOutput + "'>");
         cfg.setTemplateLoader(tl);
         
         cfg.setTemplateLookupStrategy(new DomainTemplateLookupStrategy());
@@ -344,15 +348,15 @@ public class TemplateLookupStrategyTest {
             assertEquals(tAtFooComContent, t.toString());
             assertEquals(
                     ImmutableList.of("@foo.com/t_xx.ftl", "@foo.com/t.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             assertOutputEquals(tAtFooComWithoutIncludeContent + iAtFooComContent, t);
             assertEquals(
                     ImmutableList.of("@foo.com/i_xx.ftl", "@foo.com/i.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
 
@@ -367,17 +371,17 @@ public class TemplateLookupStrategyTest {
             assertEquals(tAtBarComContent, t.toString());
             assertEquals(
                     ImmutableList.of("@bar.com/t_xx.ftl", "@bar.com/t.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             assertOutputEquals(tAtBarComWithoutIncludeContent + iXxAtDefaultContent, t);
             assertEquals(
                     ImmutableList.of(
                             "@bar.com/i_xx.ftl", "@bar.com/i.ftl",
                             "@default/i_xx.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -394,15 +398,15 @@ public class TemplateLookupStrategyTest {
                     ImmutableList.of(
                             "@baaz.com/t_xx_YY.ftl", "@baaz.com/t_xx.ftl", "@baaz.com/t.ftl",
                             "@default/t_xx_YY.ftl", "@default/t_xx.ftl", "@default/t.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             assertOutputEquals(tAtDefaultWithoutIncludeContent + iAtBaazComContent, t);
             assertEquals(
                     ImmutableList.of("@baaz.com/i_xx_YY.ftl", "@baaz.com/i_xx.ftl", "@baaz.com/i.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -419,9 +423,9 @@ public class TemplateLookupStrategyTest {
                     ImmutableList.of(
                             "@nosuch.com/i_xx_YY.ftl", "@nosuch.com/i_xx.ftl", "@nosuch.com/i.ftl",
                             "@default/i_xx_YY.ftl", "@default/i_xx.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
 
@@ -437,9 +441,9 @@ public class TemplateLookupStrategyTest {
             assertEquals(iAtDefaultContent, t.toString());
             assertEquals(
                     ImmutableList.of("@nosuch.com/i.ftl", "@default/i.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.setLocalizedLookup(true);
             cfg.clearTemplateCache();
         }
@@ -454,9 +458,9 @@ public class TemplateLookupStrategyTest {
                             "@foo.com/t2_xx.ftl", "@foo.com/t2.ftl",
                             "@foo.com/i2_xx.ftl", "@foo.com/i2.ftl", "@default/i2_xx.ftl", "@default/i2.ftl",
                             "@foo.com/i3_xx.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -470,9 +474,9 @@ public class TemplateLookupStrategyTest {
                             "@foo.com/t2_yy.ftl", "@foo.com/t2.ftl",
                             "@foo.com/i2_yy.ftl", "@foo.com/i2.ftl", "@default/i2_yy.ftl", "@default/i2.ftl",
                             "@foo.com/i3_yy.ftl", "@foo.com/i3.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -487,9 +491,9 @@ public class TemplateLookupStrategyTest {
                             "@foo.com/t2.ftl",
                             "@foo.com/i2.ftl", "@default/i2.ftl",
                             "@foo.com/i3.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.setLocalizedLookup(true);
             cfg.clearTemplateCache();
         }
@@ -500,9 +504,9 @@ public class TemplateLookupStrategyTest {
             cfg.getTemplate("i3.ftl", locale, domain, "utf-8", true, false); 
             assertEquals(
                     ImmutableList.of("@foo.com/i3_xx.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -519,9 +523,9 @@ public class TemplateLookupStrategyTest {
                     ImmutableList.of(
                             "@bar.com/i3_xx.ftl", "@bar.com/i3.ftl",
                             "@default/i3_xx.ftl", "@default/i3.ftl"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
             
-            tl.clear();
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -532,8 +536,8 @@ public class TemplateLookupStrategyTest {
         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
         
         MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
-        tl.putTemplate("test.txt", "");
-        tl.putTemplate("test_aa.txt", "");
+        tl.putTextTemplate("test.txt", "");
+        tl.putTextTemplate("test_aa.txt", "");
         cfg.setTemplateLoader(tl);
         
         try {
@@ -546,8 +550,8 @@ public class TemplateLookupStrategyTest {
                             "missing_aa_BB.txt",
                             "missing_aa.txt",
                             "missing.txt"),
-                    tl.getTemplatesTried());
-            tl.clear();
+                    tl.getLoadNames());
+            tl.clearEvents();
             cfg.clearTemplateCache();
         }
         
@@ -559,7 +563,7 @@ public class TemplateLookupStrategyTest {
                     ImmutableList.of(
                             "test_aa_BB.txt",
                             "test_aa.txt"),
-                    tl.getTemplatesTried());
+                    tl.getLoadNames());
         }
     }
 
@@ -568,8 +572,8 @@ public class TemplateLookupStrategyTest {
         Configuration cfg = new Configuration(Configuration.VERSION_2_3_22);
         
         MonitoredTemplateLoader tl = new MonitoredTemplateLoader();
-        tl.putTemplate("test.ftl", "");
-        tl.putTemplate("test_aa.ftl", "<#wrong>");
+        tl.putTextTemplate("test.ftl", "");
+        tl.putTextTemplate("test_aa.ftl", "<#wrong>");
         cfg.setTemplateLoader(tl);
         
         try {

http://git-wip-us.apache.org/repos/asf/incubator-freemarker/blob/3d0fdc8c/src/test/java/freemarker/template/TemplateNotFoundMessageTest.java
----------------------------------------------------------------------
diff --git a/src/test/java/freemarker/template/TemplateNotFoundMessageTest.java b/src/test/java/freemarker/template/TemplateNotFoundMessageTest.java
index c96015c..e2ea960 100644
--- a/src/test/java/freemarker/template/TemplateNotFoundMessageTest.java
+++ b/src/test/java/freemarker/template/TemplateNotFoundMessageTest.java
@@ -19,9 +19,12 @@
 
 package freemarker.template;
 
-import static freemarker.test.hamcerst.Matchers.*;
-import static org.hamcrest.Matchers.*;
-import static org.junit.Assert.*;
+import static freemarker.test.hamcerst.Matchers.containsStringIgnoringCase;
+import static org.hamcrest.Matchers.allOf;
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.not;
+import static org.junit.Assert.assertThat;
+import static org.junit.Assert.fail;
 
 import java.io.File;
 import java.io.IOException;
@@ -36,7 +39,7 @@ import freemarker.cache.TemplateLoader;
 import freemarker.cache.TemplateLookupContext;
 import freemarker.cache.TemplateLookupResult;
 import freemarker.cache.TemplateLookupStrategy;
-import freemarker.cache.WebappTemplateLoader;
+import freemarker.cache.WebAppTemplateLoader;
 
 public class TemplateNotFoundMessageTest {
 
@@ -59,9 +62,9 @@ public class TemplateNotFoundMessageTest {
 
     @Test
     public void testWebappTemplateLoader() throws IOException {
-        final String errMsg = failWith(new WebappTemplateLoader(new MockServletContext(), "WEB-INF/templates"));
+        final String errMsg = failWith(new WebAppTemplateLoader(new MockServletContext(), "WEB-INF/templates"));
         showErrorMessage(errMsg);
-        assertThat(errMsg, containsString("WebappTemplateLoader"));
+        assertThat(errMsg, containsString("WebAppTemplateLoader"));
         assertThat(errMsg, containsString("MyApp"));
         assertThat(errMsg, containsString("WEB-INF/templates"));
     }
@@ -83,12 +86,12 @@ public class TemplateNotFoundMessageTest {
     @Test
     public void testMultiTemplateLoader() throws IOException {
         final String errMsg = failWith(new MultiTemplateLoader(new TemplateLoader[] {
-                new WebappTemplateLoader(new MockServletContext(), "WEB-INF/templates"),
+                new WebAppTemplateLoader(new MockServletContext(), "WEB-INF/templates"),
                 new ClassTemplateLoader(this.getClass(), "foo/bar")
         }));
         showErrorMessage(errMsg);
         assertThat(errMsg, containsString("MultiTemplateLoader"));
-        assertThat(errMsg, containsString("WebappTemplateLoader"));
+        assertThat(errMsg, containsString("WebAppTemplateLoader"));
         assertThat(errMsg, containsString("MyApp"));
         assertThat(errMsg, containsString("WEB-INF/templates"));
         assertThat(errMsg, containsString("ClassTemplateLoader"));
@@ -97,18 +100,10 @@ public class TemplateNotFoundMessageTest {
 
     @Test
     public void testDefaultTemplateLoader() throws IOException {
-        Configuration cfg = new Configuration(Configuration.VERSION_2_3_0);
-        {
-            String errMsg = failWith(cfg);
-            showErrorMessage(errMsg);
-            assertThat(errMsg, allOf(containsString("setTemplateLoader"), containsString("dangerous")));
-        }
-        {
-            cfg.setIncompatibleImprovements(Configuration.VERSION_2_3_21);
-            String errMsg = failWith(cfg);
-            showErrorMessage(errMsg);
-            assertThat(errMsg, allOf(containsString("setTemplateLoader"), containsString("null")));
-        }
+        Configuration cfg = new Configuration(Configuration.VERSION_3_0_0);
+        String errMsg = failWith(cfg);
+        showErrorMessage(errMsg);
+        assertThat(errMsg, allOf(containsString("setTemplateLoader"), containsString("null")));
     }
     
     @Test