# Deprecated API

## Contents

- Deprecated Interfaces
- Deprecated Classes
- Deprecated Fields
- Deprecated Methods
- Deprecated Constructors

Deprecated Interfaces
Interface and Description
freemarker.template.TemplateMethodModel Use `TemplateMethodModelEx` instead. This interface is from the old times when the only kind of value you could pass in was string.

Deprecated Classes
Class and Description
freemarker.template.utility.CaptureOutput Use block-assignments instead, like `<assign x>...</assign>`.
freemarker.template.utility.Collections12 Not needed anymore, as FreeMarker now requires higher than Java 1.3
freemarker.core.CommandLine Will be removed (main method in a library, often classified as CWE-489 "Leftover Debug Code").
freemarker.core.FreeMarkerTree Will be removed, as Swing classes aren't accessible on Google App Engine.
freemarker.ext.ant.FreemarkerXmlTask FMPP is a more complete solution.
freemarker.ext.jdom.NodeListModel Use `NodeModel` instead.
freemarker.ext.xml.NodeListModel Use `NodeModel` instead.
freemarker.template.SimpleList Use SimpleSequence instead.
freemarker.template.utility.ToCanonical Will be removed (main method in a library, often classified as CWE-489 "Leftover Debug Code").
freemarker.ext.dom.Transform Will be removed (main method in a library, often classified as CWE-489 "Leftover Debug Code").

Deprecated Fields
Field and Description
freemarker.template.Configuration.AUTO_IMPORT_KEY Use `Configurable.AUTO_IMPORT_KEY_SNAKE_CASE` instead.
freemarker.template.Configuration.AUTO_IMPORT_KEY_CAMEL_CASE Use `Configurable.AUTO_IMPORT_KEY_CAMEL_CASE` instead.
freemarker.template.Configuration.AUTO_IMPORT_KEY_SNAKE_CASE Use `Configurable.AUTO_IMPORT_KEY_SNAKE_CASE` instead.
freemarker.template.ObjectWrapper.BEANS_WRAPPER Use `BeansWrapperBuilder.build()` instead; this instance isn't read-only and thus can't be trusted.
freemarker.ext.servlet.FreemarkerServlet.debug Not used anymore; to enable/disable debug logging, just set the logging level of the logging library used by `Logger`.
freemarker.template.Configuration.DEFAULT_INCOMPATIBLE_ENHANCEMENTS Use `Configuration.DEFAULT_INCOMPATIBLE_IMPROVEMENTS` instead.
freemarker.template.ObjectWrapper.DEFAULT_WRAPPER Use `DefaultObjectWrapperBuilder.build()` instead; this instance isn't read-only and thus can't be trusted.
freemarker.template.Configuration.INCOMPATIBLE_ENHANCEMENTS Use `Configuration.INCOMPATIBLE_IMPROVEMENTS_KEY` instead.
freemarker.template.Configuration.INCOMPATIBLE_IMPROVEMENTS Use `Configuration.INCOMPATIBLE_IMPROVEMENTS_KEY` instead.
freemarker.log.Logger.LIBRARY_AVALON Avalon LogKit support will be removed sometimes in the future.
freemarker.log.Logger.LIBRARY_NAME_AVALON Avalon LogKit support will be removed sometimes in the future.
freemarker.template.Configuration.PARSED_DEFAULT_INCOMPATIBLE_ENHANCEMENTS Use `Configuration.DEFAULT_INCOMPATIBLE_IMPROVEMENTS` instead.
freemarker.template.ObjectWrapper.SIMPLE_WRAPPER No replacement as it was seldom if ever used by anyone; this instance isn't read-only and thus can't be trusted.
freemarker.core.ParseException.specialConstructor Will be remove without replacement in 2.4.
freemarker.template.Template.WrongEncodingException.specifiedEncoding Use `Template.WrongEncodingException.getTemplateSpecifiedEncoding()` instead.
freemarker.core.Configurable.STRICT_BEAN_MODELS Use `Configurable.STRICT_BEAN_MODELS_KEY` instead.

Deprecated Methods
Method and Description
freemarker.template.SimpleSequence.add(boolean) Use `SimpleSequence.add(Object)` instead, as this bypasses the `ObjectWrapper`.
freemarker.template.Template.addImport(LibraryLoad) Should only be used internally, and might will be removed later.
freemarker.template.Template.addMacro(Macro) Should only be used internally, and might will be removed later.
freemarker.template.Template.addPrefixNSMapping(String, String) Should only be used internally, and might will be removed later.
freemarker.template.Template.containingElements(int, int) Should only be used internally, and might will be removed later.
freemarker.cache.TemplateCache.createLegacyDefaultTemplateLoader() The `TemplateLoader` should be always specified by the constructor caller.

freemarker.ext.beans.BeansWrapper.finetuneMethodAppearance(Class, Method, BeansWrapper.MethodAppearanceDecision)
Use `BeansWrapper.setMethodAppearanceFineTuner(MethodAppearanceFineTuner)`; no need to extend this class anymore. Soon this method will be final, so trying to override it will break your app. Note that if the `methodAppearanceFineTuner` property is set to non-`null`, this method is not called anymore.

freemarker.template.TemplateException.getCauseException() Java 1.4 has introduced `Throwable.getCause()` - use that instead, especially as this can't return runtime exceptions and errors as is.

freemarker.template.Configuration.getDefaultConfiguration()
The usage of the static singleton (the "default") `Configuration` instance can easily cause erroneous, unpredictable behavior. This is because multiple independent software components may use FreeMarker internally inside the same application, so they will interfere because of the common `Configuration` instance. Each such component should use its own private `Configuration` object instead, that it typically creates with `new Configuration()` when the component is initialized.

freemarker.ext.beans.BeansWrapper.getDefaultInstance() Use `BeansWrapperBuilder` instead. The instance returned here is not read-only, so it's dangerous to use.
freemarker.template.WrappingTemplateModel.getDefaultObjectWrapper() Don't depend on this object, as it can be replace by anybody in the same JVM.
freemarker.cache.TemplateCache.getFullTemplatePath(Environment, String, String) Use `Environment.toFullTemplateName(String, String)` instead, as that can throw `MalformedTemplateNameException`, and is on a more logical place anyway.
freemarker.template.Template.getImports() Should only be used internally, and might will be removed later.
freemarker.template.Configuration.getIncompatibleEnhancements() Use `Configuration.getIncompatibleImprovements()` instead.
freemarker.ext.beans.BeansWrapper.getInstance(Object, ModelFactory) override `BeansWrapper.getModelFactory(Class)` instead. Using this method will now bypass wrapper caching (if it's enabled) and always result in creation of a new wrapper. This method will be removed in 2.4
freemarker.template.Template.getMacros() Should only be used internally, and might will be removed later.
freemarker.template.Configuration.getParsedIncompatibleEnhancements() Use `Configuration.getIncompatibleImprovements()` instead.
freemarker.template.Template.getRootTreeNode() Should only be used internally, and might will be removed later.
freemarker.core.Configurable.getSetting(String) It's not possible in general to convert setting values to string, and thus it's impossible to ensure that `Configurable.setSetting(String, String)` will work with the returned value correctly.
freemarker.core.Configurable.getSettings() This method was always defective, and certainly it always will be. Don't use it. (Simply, it's hardly possible in general to convert setting values to text in a way that ensures that `Configurable.setSettings(Properties)` will work with them correctly.)
freemarker.core.Environment.getTemplate() Use `Environment.getMainTemplate()` instead (or `Environment.getCurrentNamespace()` and then `Environment.Namespace.getTemplate()`); the value returned by this method is often not what you expect when it comes to macro/function invocations.
freemarker.cache.TemplateCache.getTemplate(String, Locale, String, boolean) Use `TemplateCache.getTemplate(String, Locale, Object, String, boolean)`, which can return more detailed result when the template is missing.
freemarker.template.TemplateException.getTemplateName() Use `TemplateException.getTemplateSourceName()` instead, unless you are really sure that this is what you want. This method isn't really deprecated, it's just marked so to warn users about this.
freemarker.ext.servlet.FreemarkerServlet.getTemplatePath() Not called by FreeMarker code, and there's no point to override this (unless to cause confusion).
freemarker.template.Configuration.getVersionNumber() Use `Configuration.getVersion()` instead.
freemarker.template.utility.StringUtil.HTMLEnc(String) Use `StringUtil.XHTMLEnc(String)` instead, because it escapes apostrophe-quote too.
freemarker.template.utility.StringUtil.isXMLID(String) Don't use this outside FreeMarker; it's name if misleading, and it doesn't follow the XML specs.
freemarker.ext.dom.Transform.main(String[]) Will be removed (main method in a library, often classified as CWE-489 "Leftover Debug Code").
freemarker.ext.jdom.NodeListModel.main(String[]) Will be removed (main method in a library, often classified as CWE-489 "Leftover Debug Code").
freemarker.template.utility.ToCanonical.main(String[]) Will be removed (main method in a library, often classified as CWE-489 "Leftover Debug Code").
freemarker.template.utility.DeepUnwrap.premissiveUnwrap(TemplateModel) the name of this method is mistyped. Use `DeepUnwrap.permissiveUnwrap(TemplateModel)` instead.
freemarker.log.Logger.selectLoggerLibrary(int) This method isn't reliable, unless you can somehow ensure that you access the FreeMarker classes first; use the "org.freemarker.loggerLibrary" Java system property instead, like `java ... -Dorg.freemarker.loggerLibrary=slf4j`. See `Logger.SYSTEM_PROPERTY_NAME_LOGGER_LIBRARY` for more.
freemarker.log.Logger.setCategoryPrefix(String) This wasn't reliable, unless you can somehow ensure that you access the FreeMarker classes first. As it's not known to be useful for users, consider it removed.
freemarker.cache.TemplateCache.setConfiguration(Configuration) Use the `TemplateCache.TemplateCache(TemplateLoader, CacheStorage, Configuration)` constructor.
freemarker.template.Configuration.setDefaultConfiguration(Configuration) Using the "default" `Configuration` instance can easily lead to erroneous, unpredictable behaviour. See more `here...`.
freemarker.template.WrappingTemplateModel.setDefaultObjectWrapper(ObjectWrapper) This method has VM-wide effect, which makes it unsuitable for application where multiple components might use FreeMarker internally.
freemarker.template.Template.setEncoding(String) Should only be used internally, and might will be removed later.
freemarker.template.Configuration.setIncompatibleEnhancements(String) Use `Configuration.Configuration(Version)`, or as last chance, `Configuration.setIncompatibleImprovements(Version)` instead.
freemarker.ext.beans.BeansWrapper.setNullModel(TemplateModel) Changing the `null` model can cause a lot of confusion; don't do it.
freemarker.core.Configurable.setStrictBeanModels(boolean) Set this on the `ObjectWrapper` itself.
freemarker.template.Configuration.setStrictSyntaxMode(boolean) Only `true` (the default) value will be supported sometimes in the future.
freemarker.template.Configuration.setTemplateUpdateDelay(int) Use `Configuration.setTemplateUpdateDelayMilliseconds(long)` instead, because the time granularity of this method is often misunderstood to be milliseconds.
freemarker.template.SimpleSequence.toList() No replacement exists; not a reliable way of getting back the original list elemnts.
freemarker.core.Environment.visit(TemplateElement, TemplateDirectiveModel, Map, List) Should be internal API

Deprecated Constructors
Constructor and Description
freemarker.ext.beans.BeansWrapper() Use `BeansWrapperBuilder` or, in rare cases, `BeansWrapper.BeansWrapper(Version)` instead.
freemarker.cache.ClassTemplateLoader() It's a confusing constructor, and seldom useful; use `ClassTemplateLoader.ClassTemplateLoader(Class, String)` instead.
freemarker.cache.ClassTemplateLoader(Class) It's confusing that the base path is `""`; use `ClassTemplateLoader.ClassTemplateLoader(Class, String)` instead.
freemarker.core.Configurable() This shouldn't even be public; don't use it.
freemarker.template.Configuration() Use `Configuration.Configuration(Version)` instead. Note that the version can be still modified later with `Configuration.setIncompatibleImprovements(Version)` (or `Configurable.setSettings(Properties)`).
freemarker.template.DefaultObjectWrapper() Use `DefaultObjectWrapperBuilder`, or in rare cases, `DefaultObjectWrapper.DefaultObjectWrapper(Version)` instead.
freemarker.cache.FileTemplateLoader() Relying on what the current directory is is a bad practice; use `FileTemplateLoader.FileTemplateLoader(File)` instead.
freemarker.core.ParseException() Use a constructor to which you pass description, template, and positions.
freemarker.core.ParseException(String, int, int) Use a constructor to which you can also pass the template, and the end positions.
freemarker.core.ParseException(String, Template, int, int) Use `ParseException.ParseException(String, Template, int, int, int, int)` instead, as IDE-s need the end position of the error too.
freemarker.core.ParseException(String, Template, int, int, Throwable) Use `ParseException.ParseException(String, Template, int, int, int, int, Throwable)` instead, as IDE-s need the end position of the error too.
freemarker.ext.servlet.ServletContextHashModel(ServletContext, ObjectWrapper) use `ServletContextHashModel.ServletContextHashModel(GenericServlet, ObjectWrapper)` instead.
freemarker.template.SimpleCollection(Collection) Use `SimpleCollection.SimpleCollection(Collection, ObjectWrapper)`
freemarker.template.SimpleCollection(Iterator) Use `SimpleCollection.SimpleCollection(Iterator, ObjectWrapper)`
freemarker.template.SimpleHash() Use `SimpleHash.SimpleHash(ObjectWrapper)`
freemarker.template.SimpleHash(Map) Use `SimpleHash.SimpleHash(Map, ObjectWrapper)`
freemarker.template.SimpleObjectWrapper() Use `SimpleObjectWrapper.SimpleObjectWrapper(Version)` instead.
freemarker.template.SimpleSequence() Use `SimpleSequence.SimpleSequence(ObjectWrapper)` instead.
freemarker.template.SimpleSequence(Collection) Use `SimpleSequence.SimpleSequence(Collection, ObjectWrapper)`.
freemarker.template.SimpleSequence(int) Use `SimpleSequence.SimpleSequence(Collection, ObjectWrapper)`.
freemarker.template.Template(String, Reader) This constructor uses the "default" `Configuration` instance, which can easily lead to erroneous, unpredictable behavior. See more `here...`.
freemarker.template.Template(String, Reader, Configuration, String) In most applications, use `Template.Template(String, Reader, Configuration)` instead, which doesn't specify the encoding.
freemarker.template.Template(String, String, Reader, Configuration, String) In most applications, use `Template.Template(String, String, Reader, Configuration)` instead, which doesn't specify the encoding.
freemarker.cache.TemplateCache() Use `TemplateCache.TemplateCache(TemplateLoader)` instead. The default loader is useless in most applications, also it can mean a security risk.
freemarker.cache.TemplateCache(TemplateLoader) Use `TemplateCache.TemplateCache(TemplateLoader, CacheStorage, Configuration)` instead.
freemarker.cache.TemplateCache(TemplateLoader, CacheStorage) Use `TemplateCache.TemplateCache(TemplateLoader, CacheStorage, Configuration)` instead.
freemarker.template.WrappingTemplateModel() Use `WrappingTemplateModel.WrappingTemplateModel(ObjectWrapper)` instead; this method uses the deprecated.
freemarker.template.Template.WrongEncodingException(String) Use `#WrongEncodingException(String, String)`.