org.jenkinsci.plugins.workflow.log

Class TaskListenerDecorator

java.lang.Object

org.jenkinsci.plugins.workflow.log.TaskListenerDecorator

All Implemented Interfaces:

Serializable

public abstract class TaskListenerDecorator
extends Object
implements Serializable

A way of decorating output from a TaskListener. Similar to ConsoleLogFilter but better matched to Pipeline logging.

May be passed to a BodyInvoker in lieu of BodyInvoker.mergeConsoleLogFilters(hudson.console.ConsoleLogFilter, hudson.console.ConsoleLogFilter), using merge(org.jenkinsci.plugins.workflow.log.TaskListenerDecorator, org.jenkinsci.plugins.workflow.log.TaskListenerDecorator) to pick up any earlier decorator in StepContext.get(java.lang.Class<T>).

Expected to be serializable either locally or over Remoting, so an implementation of decorate(java.io.OutputStream) cannot assume that JenkinsJVM.isJenkinsJVM(). Any controller-side configuration should thus be saved into instance fields when the decorator is constructed.

See Also:

JENKINS-45693, Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	TaskListenerDecorator.Factory Allows a decorator to be applied to any build.

Constructor Summary

Constructors

Constructor and Description
TaskListenerDecorator()

Method Summary

Modifier and Type	Method and Description
static BuildListener	apply(TaskListener listener, FlowExecutionOwner owner, TaskListenerDecorator mainDecorator) Wraps a logger in a supplied decorator as well as any available from TaskListenerDecorator.Factorys.
abstract OutputStream	decorate(OutputStream logger) Apply modifications to a build log.
static TaskListenerDecorator	fromConsoleLogFilter(ConsoleLogFilter filter) Tries to translate a similar core interface into the new API.
static TaskListenerDecorator	merge(TaskListenerDecorator original, TaskListenerDecorator subsequent) Merges two decorators.

Methods inherited from class java.lang.Object

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

Constructor Detail

TaskListenerDecorator

public TaskListenerDecorator()

Method Detail

decorate

@NonNull
public abstract OutputStream decorate(@NonNull
                                               OutputStream logger)
                                        throws IOException,
                                               InterruptedException

Apply modifications to a build log. Typical implementations use LineTransformationOutputStream.

Parameters:

logger - a base logger

Returns:

a possibly patched result

Throws:

IOException

InterruptedException

merge

@Nullable
public static TaskListenerDecorator merge(@CheckForNull
                                                    TaskListenerDecorator original,
                                                    @CheckForNull
                                                    TaskListenerDecorator subsequent)

Merges two decorators.

Parameters:

original - the original decorator, if any

subsequent - an overriding decorator, if any

Returns:

null, or original or subsequent, or a merged result applying one then the other

fromConsoleLogFilter

@CheckForNull
public static TaskListenerDecorator fromConsoleLogFilter(@CheckForNull
                                                                       ConsoleLogFilter filter)

Tries to translate a similar core interface into the new API.

The filter may implement either ConsoleLogFilter.decorateLogger(AbstractBuild, OutputStream) and/or ConsoleLogFilter.decorateLogger(Run, OutputStream), but only ConsoleLogFilter.decorateLogger(AbstractBuild, OutputStream) will be called, and with a null build parameter.

The filter must be Serializable, and furthermore must not assume that JenkinsJVM.isJenkinsJVM(): the same constraints as for TaskListenerDecorator generally.

Parameters:

filter - a filter, or null

Returns:

an adapter, or null if it is null or (after issuing a warning) not Serializable

See Also:

JEP-210: Backwards Compatibility

apply

public static BuildListener apply(@NonNull
                                  TaskListener listener,
                                  @NonNull
                                  FlowExecutionOwner owner,
                                  @CheckForNull
                                  TaskListenerDecorator mainDecorator)

Wraps a logger in a supplied decorator as well as any available from TaskListenerDecorator.Factorys.

Does not apply ConsoleLogFilter.all() even via fromConsoleLogFilter(hudson.console.ConsoleLogFilter), since there is no mechanical way to tell if implementations actually satisfy the constraints. Anyway these singletons could not determine which build they are being applied to if remoted.

Parameters:

listener - the main logger

owner - a build

mainDecorator - an additional contextual decorator to apply, if any

Returns:

a possibly wrapped listener