Package jenkins.util

Interface ScriptListener

All Superinterfaces:

ExtensionPoint

All Known Implementing Classes:

DefaultScriptListener

public interface ScriptListener
extends ExtensionPoint

A listener to track in-process script use.

Note that (unsandboxed) script execution can easily result in logging configuration being changed, so if you rely on complete logging of scripting actions, make sure to set up logging to remote systems.

Since:

2.427

See Also:

Jenkins._doScript(StaplerRequest, org.kohsuke.stapler.StaplerResponse, javax.servlet.RequestDispatcher, hudson.remoting.VirtualChannel, hudson.security.ACL), GroovyCommand, GroovyshCommand, GroovyHookScript

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	ScriptListener.ListenerOutputStream	OutputStream that callsfireScriptOutput(String, Object, Object, String, hudson.model.User) with the output it writes to the wrapped OutputStream, and otherwise just forwards ScriptListener.ListenerOutputStream.flush() and ScriptListener.ListenerOutputStream.close().
static class	ScriptListener.ListenerWriter	Writer that calls fireScriptOutput(String, Object, Object, String, hudson.model.User) with the output it writes to the wrapped Writer, and otherwise just forwards ScriptListener.ListenerWriter.flush() and ScriptListener.ListenerWriter.close().

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Method Summary

Modifier and Type	Method	Description
static void	fireScriptExecution(String script, groovy.lang.Binding binding, Object feature, Object context, String correlationId, User user)	Fires the onScriptExecution(String, Binding, Object, Object, String, hudson.model.User) event.
static void	fireScriptOutput(String output, Object feature, Object context, String correlationId, User user)	Fires the onScriptOutput(String, Object, Object, String, hudson.model.User) event.
default void	onScriptExecution(String script, groovy.lang.Binding binding, Object feature, Object context, String correlationId, User user)	Called just before scripts are executed.
default void	onScriptOutput(String output, Object feature, Object context, String correlationId, User user)	Called when a script produces output.

Method Detail

onScriptExecution

default void onScriptExecution(@CheckForNull
                               String script,
                               @CheckForNull
                               groovy.lang.Binding binding,
                               @NonNull
                               Object feature,
                               @CheckForNull
                               Object context,
                               @NonNull
                               String correlationId,
                               @CheckForNull
                               User user)

Called just before scripts are executed. Examples include:

• Groovy script console script execution
• groovy CLI command
• Start and end of a groovysh CLI command session, as well as individual commands submitted
• Execution of scripts integrating with Script Security Plugin

Parameters:

script - The script to be executed or null if no script is available yet (e.g. a shell has just been opened).

binding - The script binding, or null if unavailable/inapplicable.

feature - The feature that triggered this event. Usually a fixed string or even a Class if that's unambiguously describing the feature (e.g., Object.getClass()).

context - Object representing the script definition context (e.g. Run). Can be null if not applicable (e.g., CLI commands not acting on jobs/builds).

correlationId - This value is used to correlate this script event to other, related script events. Callers are expected to provide values that allow receivers to associate script execution and output. Related events should have identical values.

user - If available, the user who executed the script. Can be null.

onScriptOutput

default void onScriptOutput(@CheckForNull
                            String output,
                            @NonNull
                            Object feature,
                            @CheckForNull
                            Object context,
                            @NonNull
                            String correlationId,
                            @CheckForNull
                            User user)

Called when a script produces output. This can include error output.

Parameters:

output - The output of the script.

feature - The feature that triggered this event. Usually a fixed string or even a Class if that's unambiguously describing the feature (e.g., Object.getClass()).

context - Object representing the script definition context (e.g. Run). Can be null if not applicable (e.g., CLI commands not acting on jobs/builds).

correlationId - This value is used to correlate this script event to other, related script events. Callers are expected to provide values that allow receivers to associate script execution and output. Related events should have identical values.

user - If available, the user for which the output was created. Can be null.

fireScriptExecution

static void fireScriptExecution(@CheckForNull
                                String script,
                                @CheckForNull
                                groovy.lang.Binding binding,
                                @NonNull
                                Object feature,
                                @CheckForNull
                                Object context,
                                @NonNull
                                String correlationId,
                                @CheckForNull
                                User user)

Fires the onScriptExecution(String, Binding, Object, Object, String, hudson.model.User) event.

Parameters:

script - The script to be executed or null if no script is available yet (e.g. a shell has just been opened).

binding - The script binding, or null if unavailable/inapplicable.

feature - The feature that triggered this event. Usually a fixed string or even a Class if that's unambiguously describing the feature (e.g., Object.getClass()).

context - Object representing the script definition context (e.g. Run). Can be null if not applicable (e.g., CLI commands not acting on jobs/builds).

correlationId - This value is used to correlate this script event to other, related script events. Callers are expected to provide values that allow receivers to associate script execution and output. Related events should have identical values.

user - If available, the user who caused this event. Can be null.

fireScriptOutput

static void fireScriptOutput(@CheckForNull
                             String output,
                             @NonNull
                             Object feature,
                             @CheckForNull
                             Object context,
                             @NonNull
                             String correlationId,
                             @CheckForNull
                             User user)

Fires the onScriptOutput(String, Object, Object, String, hudson.model.User) event.

Parameters:

output - The output of the script.

context - Object representing the script definition context (e.g. Run). Can be null if not applicable (e.g., CLI commands not acting on jobs/builds).

correlationId - This value is used to correlate this script event to other, related script events. Callers are expected to provide values that allow receivers to associate script execution and output. Related events should have identical values.

user - If available, the user for which the output was created. Can be null.