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 java.lang.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

TokenMacro()

Method Summary

abstract boolean	acceptsMacroName(java.lang.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 java.lang.String	evaluate(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, java.lang.String macroName, java.util.Map<java.lang.String,java.lang.String> arguments, com.google.common.collect.ListMultimap<java.lang.String,java.lang.String> argumentMultimap) Evaluates the macro and produces the token.
static java.lang.String	expand(hudson.model.AbstractBuild<?,?> context, hudson.model.TaskListener listener, java.lang.String stringWithMacro) Expands all the macro, and throws an exception if there's any problem found.

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(java.lang.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 java.lang.String evaluate(hudson.model.AbstractBuild<?,?> context,
                                          hudson.model.TaskListener listener,
                                          java.lang.String macroName,
                                          java.util.Map<java.lang.String,java.lang.String> arguments,
                                          com.google.common.collect.ListMultimap<java.lang.String,java.lang.String> argumentMultimap)
                                   throws MacroEvaluationException,
                                          java.io.IOException,
                                          java.lang.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.

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

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

all

public static hudson.ExtensionList<TokenMacro> all()

All registered extension points.

expand

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

Expands all the macro, 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

java.io.IOException

java.lang.InterruptedException