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 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