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
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 ClassesNested classes/interfaces inherited from interface hudson.ExtensionPoint
ExtensionPoint.LegacyInstancesAreScopedToHudson
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionabstract String
evaluate
(AbstractBuild<?, ?> context, TaskListener listener, String macroName) 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.evaluate
(Run<?, ?> run, FilePath workspace, TaskListener listener, String macroName) evaluate
(Run<?, ?> run, FilePath workspace, TaskListener listener, String macroName, Map<String, String> arguments, com.google.common.collect.ListMultimap<String, String> argumentMultimap) boolean
Indicates whether this macro handlesescapeHtml
on its own inside theevaluate
methods.boolean
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
-
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, throws MacroEvaluationException, IOException, InterruptedExceptionString> arguments, com.google.common.collect.ListMultimap<String, String> argumentMultimap) 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 — seeFunctions.getCurrentLocale()
.- Specified by:
evaluate
in classTokenMacro
- 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 acceptedarguments
- Arguments as a map. If multiple values are specified for one key, this will only retain the last one. This is passed in separately fromargumentMultimap
becauseargumentMultimap
- 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 thanarguments
, 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 fatalIOException
s 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 anInterruptedException
. Don't catch it, just propagate.
-
evaluate
public String evaluate(Run<?, ?> run, FilePath workspace, TaskListener listener, String macroName, Map<String, throws MacroEvaluationException, IOException, InterruptedExceptionString> arguments, com.google.common.collect.ListMultimap<String, String> argumentMultimap) - Overrides:
evaluate
in classTokenMacro
- Throws:
MacroEvaluationException
IOException
InterruptedException
-
handlesHtmlEscapeInternally
public boolean handlesHtmlEscapeInternally()Indicates whether this macro handlesescapeHtml
on its own inside theevaluate
methods. If this method returnsfalse
andescapeHtml
istrue
then the returned value fromevaluate(AbstractBuild, TaskListener, String)
andevaluate(Run, FilePath, TaskListener, String)
will be escaped. If this method returnstrue
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 thehelp.jelly
file for that class mentions theescapeHtml
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 -
evaluate
public String evaluate(Run<?, ?> run, FilePath workspace, TaskListener listener, String macroName) 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 classTokenMacro
- Returns:
- true
... to have the replaced text passed again to
TokenMacro.expand(AbstractBuild, TaskListener, String)
for additional expansion.
-