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(StaplerRequest2, org.kohsuke.stapler.StaplerResponse2, jakarta.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 Details

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.