TemplateException (FreeMarker 2.3.35 API)
Description: declaration: package: freemarker.template, class: TemplateException

Package freemarker.template

# Class TemplateException

java.lang.Object
java.lang.Throwable
java.lang.Exception
freemarker.template.TemplateException

All Implemented Interfaces:
  `Serializable`

Direct Known Subclasses:
  `freemarker.core._MiscTemplateException`, `InvalidReferenceException`, `StopException`, `TemplateModelException`, `UnexpectedTypeException`

public class TemplateException extends Exception
Runtime exception in a template (as opposed to a parsing-time exception: `ParseException`). It prints a special stack trace that contains the template-language stack trace along the usual Java stack trace.

See Also:
  Serialized Form

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `TemplateException​(Environment env)`
  Constructs a TemplateException with no specified detail message or underlying cause.
  ``
  `TemplateException​(Exception cause, Environment env)`
  The same as `TemplateException(Throwable, Environment)`; it's exists only for binary backward-compatibility.
  ``
  `TemplateException​(String description, Environment env)`
  Constructs a TemplateException with the given detail message, but no underlying cause exception.
  ``
  `TemplateException​(String description, Exception cause, Environment env)`
  The same as `TemplateException(String, Throwable, Environment)`; it's exists only for binary backward-compatibility.
  ``
  `TemplateException​(String description, Throwable cause, Environment env)`
  Constructs a TemplateException with both a description of the error that occurred and the underlying Exception that caused this exception to be raised.
  ``
  `TemplateException​(Throwable cause, Environment env)`
  Constructs a TemplateException with the given underlying Exception, but no detail message.
  `protected`
  `TemplateException​(Throwable cause, Environment env, freemarker.core.Expression blamedExpr, freemarker.core._ErrorDescriptionBuilder descriptionBuilder)`
  Don't use this; this is to be used internally by FreeMarker.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `String`
  `getBlamedExpressionString()`
  If there was a blamed expression attached to this exception, it returns its canonical form, otherwise it returns `null`.
  `Exception`
  `getCauseException()`
  Deprecated.
  Java 1.4 has introduced `Throwable.getCause()` - use that instead, especially as this can't return runtime exceptions and errors as is.
  `Integer`
  `getColumnNumber()`
  1-based column number of the failing section, or `null` if the information is not available.
  `Integer`
  `getEndColumnNumber()`
  1-based column number of the last character of the failing template section, or `null` if the information is not available.
  `Integer`
  `getEndLineNumber()`
  1-based line number of the last line that contains the failing section, or `null` if the information is not available.
  `Environment`
  `getEnvironment()`
  `String`
  `getFTLInstructionStack()`
  Returns the snapshot of the FTL stack trace at the time this exception was created.
  `Integer`
  `getLineNumber()`
  1-based line number of the failing section, or `null` if the information is not available.
  `String`
  `getMessage()`
  `String`
  `getMessageWithoutStackTop()`
  Similar to `getMessage()`, but it doesn't contain the position of the failing instruction at then end of the text.
  `String`
  `getTemplateName()`
  Deprecated.
  Use `getTemplateSourceName()` instead, unless you are really sure that this is what you want.
  `String`
  `getTemplateSourceName()`
  Returns the source name (`Template.getSourceName()`) of the template where the error has occurred, or `null` if the information isn't available.
  `void`
  `printStackTrace​(PrintStream out)`
  Overrides `Throwable.printStackTrace(PrintStream)` so that it will include the FTL stack trace.
  `void`
  `printStackTrace​(PrintStream out, boolean heading, boolean ftlStackTrace, boolean javaStackTrace)`
  `void`
  `printStackTrace​(PrintWriter out)`
  Overrides `Throwable.printStackTrace(PrintWriter)` so that it will include the FTL stack trace.
  `void`
  `printStackTrace​(PrintWriter out, boolean heading, boolean ftlStackTrace, boolean javaStackTrace)`
  `void`
  `printStandardStackTrace​(PrintStream ps)`
  Prints the stack trace as if wasn't overridden by `TemplateException`.
  `void`
  `printStandardStackTrace​(PrintWriter pw)`
  Prints the stack trace as if wasn't overridden by `TemplateException`.

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

  `addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, setStackTrace, toString`

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

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

- ## Constructor Details

  - ### TemplateException

    public TemplateException​(Environment env)
    Constructs a TemplateException with no specified detail message or underlying cause.

  - ### TemplateException

    public TemplateException​(String description, Environment env)
    Constructs a TemplateException with the given detail message, but no underlying cause exception.
    Parameters:
      `description` - the description of the error that occurred

  - ### TemplateException

    public TemplateException​(Exception cause, Environment env)
    The same as `TemplateException(Throwable, Environment)`; it's exists only for binary backward-compatibility.

  - ### TemplateException

    public TemplateException​(Throwable cause, Environment env)
    Constructs a TemplateException with the given underlying Exception, but no detail message.
    Parameters:
      `cause` - the underlying `Exception` that caused this exception to be raised
    Since:
      2.3.20

  - ### TemplateException

    public TemplateException​(String description, Exception cause, Environment env)
    The same as `TemplateException(String, Throwable, Environment)`; it's exists only for binary backward-compatibility.

  - ### TemplateException

    public TemplateException​(String description, Throwable cause, Environment env)
    Constructs a TemplateException with both a description of the error that occurred and the underlying Exception that caused this exception to be raised.
    Parameters:
      `description` - the description of the error that occurred
      `cause` - the underlying `Exception` that caused this exception to be raised
    Since:
      2.3.20

  - ### TemplateException

    protected TemplateException​(Throwable cause, Environment env, freemarker.core.Expression blamedExpr, freemarker.core._ErrorDescriptionBuilder descriptionBuilder)
    Don't use this; this is to be used internally by FreeMarker. No backward compatibility guarantees.
    Parameters:
      `blamedExpr` - Maybe `null`. The FTL stack in the `Environment` only specifies the error location with "template element" granularity, and this can be used to point to the expression inside the template element.

- ## Method Details

  - ### getCauseException

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

  - ### getFTLInstructionStack

    public String getFTLInstructionStack()
    Returns the snapshot of the FTL stack trace at the time this exception was created.

  - ### getEnvironment

    public Environment getEnvironment()
    Returns:
      the execution environment in which the exception occurred. `null` if the exception was deserialized.

  - ### printStackTrace

    public void printStackTrace​(PrintStream out)
    Overrides `Throwable.printStackTrace(PrintStream)` so that it will include the FTL stack trace.
    Overrides:
      `printStackTrace` in class `Throwable`

  - ### printStackTrace

    public void printStackTrace​(PrintWriter out)
    Overrides `Throwable.printStackTrace(PrintWriter)` so that it will include the FTL stack trace.
    Overrides:
      `printStackTrace` in class `Throwable`

  - ### printStackTrace

    public void printStackTrace​(PrintWriter out, boolean heading, boolean ftlStackTrace, boolean javaStackTrace)
    Parameters:
      `heading` - should the heading at the top be printed
      `ftlStackTrace` - should the FTL stack trace be printed
      `javaStackTrace` - should the Java stack trace be printed
    Since:
      2.3.20

  - ### printStackTrace

    public void printStackTrace​(PrintStream out, boolean heading, boolean ftlStackTrace, boolean javaStackTrace)
    Parameters:
      `heading` - should the heading at the top be printed
      `ftlStackTrace` - should the FTL stack trace be printed
      `javaStackTrace` - should the Java stack trace be printed
    Since:
      2.3.20

  - ### printStandardStackTrace

    public void printStandardStackTrace​(PrintStream ps)
    Prints the stack trace as if wasn't overridden by `TemplateException`.
    Since:
      2.3.20

  - ### printStandardStackTrace

    public void printStandardStackTrace​(PrintWriter pw)
    Prints the stack trace as if wasn't overridden by `TemplateException`.
    Since:
      2.3.20

  - ### getMessage

    public String getMessage()
    Overrides:
      `getMessage` in class `Throwable`

  - ### getMessageWithoutStackTop

    public String getMessageWithoutStackTop()
    Similar to `getMessage()`, but it doesn't contain the position of the failing instruction at then end of the text. It might contains the position of the failing expression though as part of the expression quotation, as that's the part of the description.

  - ### getLineNumber

    public Integer getLineNumber()
    1-based line number of the failing section, or `null` if the information is not available.
    Since:
      2.3.21

  - ### getTemplateName

    @Deprecated public String getTemplateName()
    Deprecated.
    Use `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.
    Returns the name (`Template.getName()`) of the template where the error has occurred, or `null` if the information isn't available. This shouldn't be used for showing the error position; use `getTemplateSourceName()` instead.
    Since:
      2.3.21

  - ### getTemplateSourceName

    public String getTemplateSourceName()
    Returns the source name (`Template.getSourceName()`) of the template where the error has occurred, or `null` if the information isn't available. This is what should be used for showing the error position.
    Since:
      2.3.22

  - ### getColumnNumber

    public Integer getColumnNumber()
    1-based column number of the failing section, or `null` if the information is not available.
    Since:
      2.3.21

  - ### getEndLineNumber

    public Integer getEndLineNumber()
    1-based line number of the last line that contains the failing section, or `null` if the information is not available.
    Since:
      2.3.21

  - ### getEndColumnNumber

    public Integer getEndColumnNumber()
    1-based column number of the last character of the failing template section, or `null` if the information is not available. Note that unlike with Java string API-s, this column number is inclusive.
    Since:
      2.3.21

  - ### getBlamedExpressionString

    public String getBlamedExpressionString()
    If there was a blamed expression attached to this exception, it returns its canonical form, otherwise it returns `null`. This expression should always be inside the failing FTL instruction.

    The typical application of this is getting the undefined expression from `InvalidReferenceException`-s.

    Since:
      2.3.21