org.jenkinsci.plugins.tokenmacro

Class TokenMacro

java.lang.Object

org.jenkinsci.plugins.tokenmacro.TokenMacro

All Implemented Interfaces:

hudson.ExtensionPoint

Direct Known Subclasses:

BuildNumberMacro, BuildUrlMacro, DataBoundTokenMacro

public abstract class TokenMacro
extends Object
implements hudson.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

hudson.ExtensionPoint.LegacyInstancesAreScopedToHudson

Constructor Summary

Constructors

Constructor and Description
TokenMacro()

Method Summary

Methods

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.
static String	expand(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, String stringWithMacro) Expands all the macros, and throws an exception if there's any problem found.
static String	expand(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens)
static String	expandAll(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, String stringWithMacro) Expands everything that needs to be expanded.
static String	expandAll(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, String stringWithMacro, boolean throwException, List<TokenMacro> privateTokens)
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 Detail

TokenMacro

public TokenMacro()

Method Detail

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

Evaluates the macro and produces the token.

Locale

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.

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.

all

public static hudson.ExtensionList<TokenMacro> all()

All registered extension points.

expand

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

Expands all the macros, and throws an exception if there's any problem found.

Parameters:

stringWithMacro - String that contains macro references in it, like "foo bar ${zot}".

Throws:

MacroEvaluationException

IOException

InterruptedException

expand

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

Throws:

MacroEvaluationException

IOException

InterruptedException

expandAll

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

Expands everything that needs to be expanded. Expands all the macros, environment variables, and build variables. Throws an exception if there's any problem found. This should be more convenient than having plugins do all 3 separately.

Parameters:

stringWithMacro - String that contains macro references in it, like "foo bar ${zot}".

Throws:

MacroEvaluationException

IOException

InterruptedException

expandAll

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

Throws:

MacroEvaluationException

IOException

InterruptedException