public abstract class TokenMacro extends Object implements hudson.ExtensionPoint
AbstractBuild
.
Various plugins, such as email-ext and description-setter, has this concept of producing some textual value out of a build (to become the e-mail content/subject, to be come the build description, etc), and the user is allowed to configure how those strings look like.
In such situation, it is useful to have a notion of "macro tokens", one that look like like ${foobar}, and expands to some string value when evaluated. This is exactly such an abstraction, and it is placed in its own plugin in the hope that it's reusable by other plugins.
In more general form, the macro would have the following syntax structure:
${MACRONAME [, ARG, ARG, ...]} ARG := NAME [ = 'value' ]
Implementation should have help.jelly that renders a DT tag that shows the syntax of the macro, followed by a DD tag that shows the details. See existing use of this extension point for the general guide line of the syntax.
Plugins interested in using the list of tags can use the "/lib/token-macro" taglib like the following, which expands to the HTML that lists all the tags and their usages:
<help xmlons="/lib/token-macro"/>
Constructor and Description |
---|
TokenMacro() |
Modifier and Type | Method and Description |
---|---|
abstract boolean |
acceptsMacroName(String macroName)
Returns true if this object can evaluate the macro of the given name.
|
static hudson.ExtensionList<TokenMacro> |
all()
All registered extension points.
|
abstract String |
evaluate(hudson.model.AbstractBuild<?,?> context,
hudson.model.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(hudson.model.Run<?,?> run,
hudson.FilePath workspace,
hudson.model.TaskListener listener,
String macroName,
Map<String,String> arguments,
com.google.common.collect.ListMultimap<String,String> argumentMultimap) |
static String |
expand(hudson.model.AbstractBuild<?,?> context,
hudson.model.TaskListener listener,
String stringWithMacro) |
static String |
expand(hudson.model.AbstractBuild<?,?> context,
hudson.model.TaskListener listener,
String stringWithMacro,
boolean throwException,
List<TokenMacro> privateTokens) |
static String |
expand(hudson.model.Run<?,?> run,
hudson.FilePath workspace,
hudson.model.TaskListener listener,
String stringWithMacro) |
static String |
expand(hudson.model.Run<?,?> run,
hudson.FilePath workspace,
hudson.model.TaskListener listener,
String stringWithMacro,
boolean throwException,
List<TokenMacro> privateTokens) |
static String |
expandAll(hudson.model.AbstractBuild<?,?> context,
hudson.model.TaskListener listener,
String stringWithMacro) |
static String |
expandAll(hudson.model.AbstractBuild<?,?> context,
hudson.model.TaskListener listener,
String stringWithMacro,
boolean throwException,
List<TokenMacro> privateTokens) |
static String |
expandAll(hudson.model.Run<?,?> run,
hudson.FilePath workspace,
hudson.model.TaskListener listener,
String stringWithMacro) |
static String |
expandAll(hudson.model.Run<?,?> run,
hudson.FilePath workspace,
hudson.model.TaskListener listener,
String stringWithMacro,
boolean throwException,
List<TokenMacro> privateTokens) |
List<String> |
getAcceptedMacroNames() |
static List<String> |
getAutoCompleteList(String input) |
static hudson.model.Run<?,?> |
getPreviousRun(hudson.model.Run<?,?> run,
hudson.model.TaskListener listener)
Looks for a previous build, so long as that is in fact completed.
|
protected static hudson.FilePath |
getWorkspace(hudson.model.AbstractBuild<?,?> context)
Gets a workspace of the build in the macro.
|
boolean |
hasNestedContent()
Returns true if this object allows for nested content replacements.
|
public abstract boolean acceptsMacroName(String macroName)
macroName
- By convention we encourage all caps name.evaluate(AbstractBuild, TaskListener, String, Map, ListMultimap)
called.public abstract String evaluate(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, String macroName, Map<String,String> arguments, com.google.common.collect.ListMultimap<String,String> argumentMultimap) throws MacroEvaluationException, IOException, InterruptedException
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()
.
context
- 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 from argumentMultimap
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 than arguments
, but it's bit more tedious to use.MacroEvaluationException
- If the evaluation failed, for example because of the parameter error, and that the error message
should be presented.IOException
- Other fatal IOException
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 an InterruptedException
. Don't catch it, just propagate.public String evaluate(hudson.model.Run<?,?> run, hudson.FilePath workspace, hudson.model.TaskListener listener, String macroName, Map<String,String> arguments, com.google.common.collect.ListMultimap<String,String> argumentMultimap) throws MacroEvaluationException, IOException, InterruptedException
public boolean hasNestedContent()
expand(AbstractBuild, TaskListener, String)
for additional expansion.public static hudson.ExtensionList<TokenMacro> all()
public static String expand(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, String stringWithMacro) throws MacroEvaluationException, IOException, InterruptedException
public static String expand(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens) throws MacroEvaluationException, IOException, InterruptedException
public static String expand(hudson.model.Run<?,?> run, hudson.FilePath workspace, hudson.model.TaskListener listener, String stringWithMacro) throws MacroEvaluationException, IOException, InterruptedException
public static String expand(hudson.model.Run<?,?> run, hudson.FilePath workspace, hudson.model.TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens) throws MacroEvaluationException, IOException, InterruptedException
public static String expandAll(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, String stringWithMacro) throws MacroEvaluationException, IOException, InterruptedException
public static String expandAll(hudson.model.Run<?,?> run, hudson.FilePath workspace, hudson.model.TaskListener listener, String stringWithMacro) throws MacroEvaluationException, IOException, InterruptedException
public static String expandAll(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens) throws MacroEvaluationException, IOException, InterruptedException
public static String expandAll(hudson.model.Run<?,?> run, hudson.FilePath workspace, hudson.model.TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens) throws MacroEvaluationException, IOException, InterruptedException
@Nonnull protected static hudson.FilePath getWorkspace(@Nonnull hudson.model.AbstractBuild<?,?> context) throws MacroEvaluationException
context
- BuildMacroEvaluationException
- Workspace is inaccessible@CheckForNull public static hudson.model.Run<?,?> getPreviousRun(@Nonnull hudson.model.Run<?,?> run, hudson.model.TaskListener listener)
Builder.getRequiredMonitorService()
does not wait for the
previous build, so in the case of parallel-capable jobs, we need to
behave sensibly when a later build actually finishes before an earlier
one.run
- a run for which we may be sending maillistener
- a listener to which we may print warnings in case the
actual previous run is still in progressCopyright © 2016–2018. All rights reserved.