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 asTemplateException(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 asTemplateException(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
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description String
getBlamedExpressionString()
If there was a blamed expression attached to this exception, it returns its canonical form, otherwise it returnsnull
.Exception
getCauseException()
Deprecated.Java 1.4 has introducedThrowable.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, ornull
if the information is not available.Integer
getEndColumnNumber()
1-based column number of the last character of the failing template section, ornull
if the information is not available.Integer
getEndLineNumber()
1-based line number of the last line that contains the failing section, ornull
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, ornull
if the information is not available.String
getMessage()
String
getMessageWithoutStackTop()
Similar togetMessage()
, but it doesn't contain the position of the failing instruction at then end of the text.String
getTemplateName()
Deprecated.UsegetTemplateSourceName()
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, ornull
if the information isn't available.void
printStackTrace(PrintStream out)
OverridesThrowable.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)
OverridesThrowable.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 byTemplateException
.void
printStandardStackTrace(PrintWriter pw)
Prints the stack trace as if wasn't overridden byTemplateException
.-
Methods inherited from class java.lang.Throwable
addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, setStackTrace, toString
-
-
-
-
Constructor Detail
-
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 asTemplateException(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 underlyingException
that caused this exception to be raised- Since:
- 2.3.20
-
TemplateException
public TemplateException(String description, Exception cause, Environment env)
The same asTemplateException(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 occurredcause
- the underlyingException
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
- Maybenull
. The FTL stack in theEnvironment
only specifies the error location with "template element" granularity, and this can be used to point to the expression inside the template element.
-
-
Method Detail
-
getCauseException
public Exception getCauseException()
Deprecated.Java 1.4 has introducedThrowable.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)
OverridesThrowable.printStackTrace(PrintStream)
so that it will include the FTL stack trace.- Overrides:
printStackTrace
in classThrowable
-
printStackTrace
public void printStackTrace(PrintWriter out)
OverridesThrowable.printStackTrace(PrintWriter)
so that it will include the FTL stack trace.- Overrides:
printStackTrace
in classThrowable
-
printStackTrace
public void printStackTrace(PrintWriter out, boolean heading, boolean ftlStackTrace, boolean javaStackTrace)
- Parameters:
heading
- should the heading at the top be printedftlStackTrace
- should the FTL stack trace be printedjavaStackTrace
- 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 printedftlStackTrace
- should the FTL stack trace be printedjavaStackTrace
- 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 byTemplateException
.- Since:
- 2.3.20
-
printStandardStackTrace
public void printStandardStackTrace(PrintWriter pw)
Prints the stack trace as if wasn't overridden byTemplateException
.- Since:
- 2.3.20
-
getMessage
public String getMessage()
- Overrides:
getMessage
in classThrowable
-
getMessageWithoutStackTop
public String getMessageWithoutStackTop()
Similar togetMessage()
, 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, ornull
if the information is not available.- Since:
- 2.3.21
-
getTemplateName
public String getTemplateName()
Deprecated.UsegetTemplateSourceName()
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, ornull
if the information isn't available. This shouldn't be used for showing the error position; usegetTemplateSourceName()
instead.- Since:
- 2.3.21
-
getTemplateSourceName
public String getTemplateSourceName()
Returns the source name (Template.getSourceName()
) of the template where the error has occurred, ornull
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, ornull
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, ornull
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, ornull
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 returnsnull
. 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
-
-