Package org.jenkinsci.plugins.tokenmacro

Class DataBoundTokenMacro

java.lang.Object

org.jenkinsci.plugins.tokenmacro.TokenMacro

org.jenkinsci.plugins.tokenmacro.DataBoundTokenMacro

All Implemented Interfaces:

ExtensionPoint

Direct Known Subclasses:

AbstractChangesSinceMacro, BuildCauseMacro, BuildLogExcerptMacro, BuildLogMacro, BuildLogMultilineRegexMacro, BuildLogRegexMacro, BuildStatusMacro, ChangesSinceLastBuildMacro, EnvironmentVariableMacro, JenkinsUrlMacro, JobDescriptionMacro, LogRegExMacro, ProjectNameMacro, ProjectUrlMacro, UpstreamRunNameMacro, WorkspaceDependentMacro

public abstract class DataBoundTokenMacro
extends TokenMacro

Convenient base class for implementing TokenMacro that does parameter databinding to fields.

When you define your token macro as a subtype of this class, a fresh instance is created for each evaluation, and fields or setters with the DataBoundTokenMacro.Parameter annotation will receive the corresponding parameter values, then the evaluate(AbstractBuild, TaskListener, String) method gets invoked.

In this way, you simplify the parameter parsing and type conversion overhead.

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static @interface	DataBoundTokenMacro.Parameter

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field	Description
boolean	escapeHtml

Constructor Summary

Constructors

Constructor	Description
DataBoundTokenMacro()

Method Summary

Modifier and Type	Method	Description
abstract String	evaluate(AbstractBuild<?,?> context, TaskListener listener, String macroName)
String	evaluate(AbstractBuild<?,?> build, TaskListener listener, String macroName, Map<String,String> arguments, com.google.common.collect.ListMultimap<String,String> argumentMultimap)	Evaluates the macro and produces the token.
String	evaluate(Run<?,?> run, FilePath workspace, TaskListener listener, String macroName)
String	evaluate(Run<?,?> run, FilePath workspace, TaskListener listener, String macroName, Map<String,String> arguments, com.google.common.collect.ListMultimap<String,String> argumentMultimap)
boolean	handlesHtmlEscapeInternally()	Indicates whether this macro handles escapeHtml on its own inside the evaluate methods.
boolean	hasNestedContent()	Returns true if this object allows for nested content replacements.

Methods inherited from class org.jenkinsci.plugins.tokenmacro.TokenMacro

acceptsMacroName, all, expand, expand, expand, expand, expandAll, expandAll, expandAll, expandAll, getAcceptedMacroNames, getAutoCompleteList, getPreviousRun, getWorkspace

Methods inherited from class java.lang.Object

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

Field Details

escapeHtml

public boolean escapeHtml

Constructor Details

DataBoundTokenMacro

public DataBoundTokenMacro()

Method Details

evaluate

public String evaluate(AbstractBuild<?,?> build,
 TaskListener listener,
 String macroName,
 Map<String,String> arguments,
 com.google.common.collect.ListMultimap<String,String> argumentMultimap)
                throws MacroEvaluationException,
IOException,
InterruptedException

Description copied from class: TokenMacro

Evaluates the macro and produces the token. If the token is to produce a human readable text, it should do so by using the implicit locale associated with the calling thread — see Functions.getCurrentLocale().

Specified by:

evaluate in class TokenMacro

Parameters:

build - The build object for which this macro is evaluated.

listener - If the progress/status needs to be reported to the build console output, this object can be used.

macroName - The macro name that you accepted

arguments - Arguments as a map. If multiple values are specified for one key, this will only retain the last one. This is passed in separately from argumentMultimap because

argumentMultimap - The same arguments, but in a multi-map. If multiple values are specified for one key, all of them are retained here in the order of appearance. For those macros that support multiple values for the same key this is more accurate than arguments, but it's bit more tedious to use.

Returns:

The result of the evaluation. Must not be null.

Throws:

MacroEvaluationException - If the evaluation failed, for example because of the parameter error, and that the error message should be presented.

IOException - Other fatal IOExceptions that should leave the stack trace in the console.

InterruptedException - If the evaluation involves some remoting operation, user might cancel the build, which results in an InterruptedException. Don't catch it, just propagate.

evaluate

public String evaluate(Run<?,?> run,
 FilePath workspace,
 TaskListener listener,
 String macroName,
 Map<String,String> arguments,
 com.google.common.collect.ListMultimap<String,String> argumentMultimap)
                throws MacroEvaluationException,
IOException,
InterruptedException

Overrides:

evaluate in class TokenMacro

Throws:

MacroEvaluationException

IOException

InterruptedException

handlesHtmlEscapeInternally

public boolean handlesHtmlEscapeInternally()

Indicates whether this macro handles escapeHtml on its own inside the evaluate methods. If this method returns false and escapeHtml is true then the returned value from evaluate(AbstractBuild, TaskListener, String) and evaluate(Run, FilePath, TaskListener, String) will be escaped. If this method returns true no escaping will be performed, and it is assumed the escaping will be handled internally by the implementing class. It is then also assumed that the help.jelly file for that class mentions the escapeHtml parameter.

Returns:

true if the implementing class handles its own html escaping.

evaluate

public abstract String evaluate(AbstractBuild<?,?> context,
 TaskListener listener,
 String macroName)
                         throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

evaluate

public String evaluate(Run<?,?> run,
 FilePath workspace,
 TaskListener listener,
 String macroName)
                throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

hasNestedContent

public boolean hasNestedContent()

Description copied from class: TokenMacro

Returns true if this object allows for nested content replacements.

Overrides:

hasNestedContent in class TokenMacro

Returns:

true ... to have the replaced text passed again to TokenMacro.expand(AbstractBuild, TaskListener, String) for additional expansion.