Package org.jenkinsci.plugins.tokenmacro

Class TokenMacro

java.lang.Object

org.jenkinsci.plugins.tokenmacro.TokenMacro

All Implemented Interfaces:

ExtensionPoint

Direct Known Subclasses:

AdminEmailMacro, BuildNumberMacro, BuildUrlMacro, BuildUserMacro, DataBoundTokenMacro

public abstract class TokenMacro
extends Object
implements ExtensionPoint

A macro that expands to text values in the context of a 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' ]
 

Views

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

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor	Description
TokenMacro()

Method Summary

Modifier and Type	Method	Description
abstract boolean	acceptsMacroName(String macroName)	Returns true if this object can evaluate the macro of the given name.
static ExtensionList<TokenMacro>	all()	All registered extension points.
abstract String	evaluate(AbstractBuild<?,?> context, 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, Map<String,String> arguments, com.google.common.collect.ListMultimap<String,String> argumentMultimap)
static String	expand(AbstractBuild<?,?> context, TaskListener listener, String stringWithMacro)
static String	expand(AbstractBuild<?,?> context, TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens)
static String	expand(Run<?,?> run, FilePath workspace, TaskListener listener, String stringWithMacro)
static String	expand(Run<?,?> run, FilePath workspace, TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens)
static String	expandAll(AbstractBuild<?,?> context, TaskListener listener, String stringWithMacro)
static String	expandAll(AbstractBuild<?,?> context, TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens)
static String	expandAll(Run<?,?> run, FilePath workspace, TaskListener listener, String stringWithMacro)
static String	expandAll(Run<?,?> run, FilePath workspace, TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens)
List<String>	getAcceptedMacroNames()
static List<String>	getAutoCompleteList(String input)
static Run<?,?>	getPreviousRun(Run<?,?> run, TaskListener listener)	Looks for a previous build, so long as that is in fact completed.
protected static FilePath	getWorkspace(AbstractBuild<?,?> context)	Gets a workspace of the build in the macro.
boolean	hasNestedContent()	Returns true if this object allows for nested content replacements.

Methods inherited from class java.lang.Object

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

Constructor Details

TokenMacro

public TokenMacro()

Method Details

acceptsMacroName

public abstract boolean acceptsMacroName(String macroName)

Returns true if this object can evaluate the macro of the given name.

Parameters:

macroName - By convention we encourage all caps name.

Returns:

true ... to claim the macro of the given name and have evaluate(AbstractBuild, TaskListener, String, Map, ListMultimap) called.

evaluate

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

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().

Parameters:

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 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,
 @CheckForNull
 FilePath workspace,
 TaskListener listener,
 String macroName,
 Map<String,String> arguments,
 com.google.common.collect.ListMultimap<String,String> argumentMultimap)
                throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

hasNestedContent

public boolean hasNestedContent()

Returns true if this object allows for nested content replacements.

Returns:

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

getAcceptedMacroNames

public List<String> getAcceptedMacroNames()

getAutoCompleteList

public static List<String> getAutoCompleteList(String input)

all

public static ExtensionList<TokenMacro> all()

All registered extension points.

Returns:

All registered token macro classes.

expand

public static String expand(AbstractBuild<?,?> context,
 TaskListener listener,
 String stringWithMacro)
                     throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

expand

public static String expand(AbstractBuild<?,?> context,
 TaskListener listener,
 String stringWithMacro,
 boolean throwException,
 List<TokenMacro> privateTokens)
                     throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

expand

public static String expand(Run<?,?> run,
 @CheckForNull
 FilePath workspace,
 TaskListener listener,
 String stringWithMacro)
                     throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

expand

public static String expand(Run<?,?> run,
 @CheckForNull
 FilePath workspace,
 TaskListener listener,
 String stringWithMacro,
 boolean throwException,
 List<TokenMacro> privateTokens)
                     throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

expandAll

public static String expandAll(AbstractBuild<?,?> context,
 TaskListener listener,
 String stringWithMacro)
                        throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

expandAll

public static String expandAll(Run<?,?> run,
 @CheckForNull
 FilePath workspace,
 TaskListener listener,
 String stringWithMacro)
                        throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

expandAll

public static String expandAll(AbstractBuild<?,?> context,
 TaskListener listener,
 String stringWithMacro,
 boolean throwException,
 List<TokenMacro> privateTokens)
                        throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

expandAll

public static String expandAll(Run<?,?> run,
 @CheckForNull
 FilePath workspace,
 TaskListener listener,
 String stringWithMacro,
 boolean throwException,
 List<TokenMacro> privateTokens)
                        throws MacroEvaluationException,
IOException,
InterruptedException

Throws:

MacroEvaluationException

IOException

InterruptedException

getWorkspace

@NonNull
protected static FilePath getWorkspace(@NonNull
 AbstractBuild<?,?> context)
                                throws MacroEvaluationException

Gets a workspace of the build in the macro.

Parameters:

context - Build

Returns:

Retrieved workspace

Throws:

MacroEvaluationException - Workspace is inaccessible

getPreviousRun

@CheckForNull
public static Run<?,?> getPreviousRun(@NonNull
 Run<?,?> run,
 TaskListener listener)

Looks for a previous build, so long as that is in fact completed. Necessary since 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.

Parameters:

run - a run for which we may be sending mail

listener - a listener to which we may print warnings in case the actual previous run is still in progress

Returns:

the previous run, or null if that run is missing, or is still in progress