ClassTemplateLoader (FreeMarker 2.3.35 API)
Description: declaration: package: freemarker.cache, class: ClassTemplateLoader

Package freemarker.cache

# Class ClassTemplateLoader

java.lang.Object
freemarker.cache.URLTemplateLoader
freemarker.cache.ClassTemplateLoader

All Implemented Interfaces:
  `TemplateLoader`

public class ClassTemplateLoader extends URLTemplateLoader
A `TemplateLoader` that can load templates from the "classpath". Naturally, it can load from jar files, or from anywhere where Java can load classes from. Internally, it uses `Class.getResource(String)` or `ClassLoader.getResource(String)` to load templates.

Since FreeMarker 2.3.35 this checks if the provided template name backs out from the base package, and if so will throw `MalformedTemplateNameException`. This check is normally done by the `TemplateCache`, but see in the description of `TemplateLoader` why it's better to also check it here.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ClassTemplateLoader()`
  Deprecated.
  It's a confusing constructor, and seldom useful; use `ClassTemplateLoader(Class, String)` instead.
  `ClassTemplateLoader​(Class<?> resourceLoaderClass)`
  Deprecated.
  It's confusing that the base path is `""`; use `ClassTemplateLoader(Class, String)` instead.
  `ClassTemplateLoader​(Class<?> resourceLoaderClass, String basePackagePath)`
  Creates a template loader that will use the `Class.getResource(String)` method of the specified class to load the resources, and the specified base package path (absolute or relative).
  `ClassTemplateLoader​(ClassLoader classLoader, String basePackagePath)`
  Similar to `ClassTemplateLoader(Class, String)`, but instead of `Class.getResource(String)` it uses `ClassLoader.getResource(String)`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getBasePackagePath()`
  See the similar parameter of `ClassTemplateLoader(ClassLoader, String)`; note that this is a normalized version of what was actually passed to the constructor.
  `ClassLoader`
  `getClassLoader()`
  See the similar parameter of `ClassTemplateLoader(ClassLoader, String)`; `null` when other mechanism is used to load the resources.
  `Class`
  `getResourceLoaderClass()`
  See the similar parameter of `ClassTemplateLoader(Class, String)`; `null` when other mechanism is used to load the resources.
  `protected URL`
  `getURL​(String name)`
  Given a template name (plus potential locale decorations) retrieves an URL that points the template source.
  `String`
  `toString()`
  Show class name and some details that are useful in template-not-found errors.

  ### Methods inherited from class freemarker.cache.URLTemplateLoader

  `canonicalizePrefix, closeTemplateSource, findTemplateSource, getLastModified, getReader, getURLConnectionUsesCaches, setURLConnectionUsesCaches`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### ClassTemplateLoader

    @Deprecated public ClassTemplateLoader()
    Deprecated.
    It's a confusing constructor, and seldom useful; use `ClassTemplateLoader(Class, String)` instead.
    Creates a template loader that will use the `Class.getResource(String)` method of its own class to load the resources, and `"/"` 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:
    `new ClassTemplateLoader(com.example.myapplication.SomeClass.class, "templates")`

    If you extend this class, then the extending class will be used to load the resources.

  - ### ClassTemplateLoader

    @Deprecated public ClassTemplateLoader​(Class<?> resourceLoaderClass)
    Deprecated.
    It's confusing that the base path is `""`; use `ClassTemplateLoader(Class, String)` instead.
    Creates a template loader that will use the `Class.getResource(String)` method of the specified class to load the resources, and `""` 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.
    Parameters:
      `resourceLoaderClass` - the class whose `Class.getResource(String)` will be used to load the templates.

  - ### ClassTemplateLoader

    public ClassTemplateLoader​(Class<?> resourceLoaderClass, String basePackagePath)
    Creates a template loader that will use the `Class.getResource(String)` method of the specified class to load the resources, and the specified base package path (absolute or relative).

    Examples:

    - Relative base path (will load from the `com.example.myapplication.templates` package):
      `new ClassTemplateLoader(com.example.myapplication.SomeClass.class, "templates")`
    - Absolute base path:
      `new ClassTemplateLoader(somepackage.SomeClass.class, "/com/example/myapplication/templates")`
    Parameters:
      `resourceLoaderClass` - The class whose `Class.getResource(String)` method will be used to load the templates. Be sure that you chose a class whose defining class-loader sees the templates. This parameter can't be `null`.
      `basePackagePath` - The package that contains the templates, in path (`/`-separated) format. If it doesn't start with a `/` then it's relative to the path (package) of the `resourceLoaderClass` class. If it starts with `/` then it's relative to the root of the package hierarchy. Note that path components should be separated by forward slashes independently of the separator character used by the underlying operating system. This parameter can't be `null`.
    See Also:
      `ClassTemplateLoader(ClassLoader, String)`

  - ### ClassTemplateLoader

    public ClassTemplateLoader​(ClassLoader classLoader, String basePackagePath)
    Similar to `ClassTemplateLoader(Class, String)`, but instead of `Class.getResource(String)` it uses `ClassLoader.getResource(String)`. Because a `ClassLoader` isn't bound to any Java package, it doesn't matter if the `basePackagePath` starts with `/` or not, it will be always relative to the root of the package hierarchy
    Since:
      2.3.22

- ## Method Details

  - ### getURL

    protected URL getURL​(String name)
    Description copied from class: `URLTemplateLoader`
    Given a template name (plus potential locale decorations) retrieves an URL that points the template source.
    Specified by:
      `getURL` in class `URLTemplateLoader`
    Parameters:
      `name` - the name of the sought template, including the locale decorations; same as the parameter to `TemplateLoader.findTemplateSource(String)`; see rules there.
    Returns:
      an URL that points to the template source, or `null` if the template does not exist.

  - ### toString

    public String toString()
    Show class name and some details that are useful in template-not-found errors.
    Overrides:
      `toString` in class `Object`
    Since:
      2.3.21

  - ### getResourceLoaderClass

    public Class getResourceLoaderClass()
    See the similar parameter of `ClassTemplateLoader(Class, String)`; `null` when other mechanism is used to load the resources.
    Since:
      2.3.22

  - ### getClassLoader

    public ClassLoader getClassLoader()
    See the similar parameter of `ClassTemplateLoader(ClassLoader, String)`; `null` when other mechanism is used to load the resources.
    Since:
      2.3.22

  - ### getBasePackagePath

    public String getBasePackagePath()
    See the similar parameter of `ClassTemplateLoader(ClassLoader, String)`; note that this is a normalized version of what was actually passed to the constructor.
    Since:
      2.3.22