9 Configuring the Script Interceptor

You can configure and use script interceptors in conjunction with elastic scaling operations performed in dynamic clusters. The following sections describe how to configure the script interceptor:

Overview of the Script Interceptor

Script interceptors are provided as a means to perform tasks before or immediately after a scaling operation has been completed. During a scaling operation, it is necessary to perform functions with various entities or systems in the WebLogic Server environment. For example, before starting a new server instance in a dynamic cluster, it is necessary to coordinate with a virtualization manager to provision a new VM or to configure a machine.

Script interceptors can execute two main types of scripts:

Preprocessor scripts execute tasks prior to a scaling operation
Postprocessor scripts execute tasks immediately after a scaling operation

Script interceptors can also execute error handler scripts if an error occurs during the execution of the preprocessor or postprocessor scripts. And multiple script interceptor instances can be used in an interceptor chain for a scaling operation.

Note:

If the execution of a preprocessor script fails, then neither the associated scaling operation nor any subsequently configured interceptors are invoked. If a postprocessor script fails, the scaling action that preceded the invocation of that script cannot be reverted or otherwise cancelled.

Script interceptors are configured using the ScriptInterceptorMBean. Example 9-1 offers a sample script interceptor configuration.

Example 9-1 Configuring a Script Interceptor

EditServiceMBean editService = mbsFactory.getEditService();
ConfigurationManagerMBean configManager = editService.getConfigurationManager();
configManager.startEdit(5000, 5000);

DomainMBean domainMBean = editService.getDomainConfiguration();
InterceptorsMBean interceptors = (InterceptorsMBean) domainMBean.getInterceptors();
ScriptInterceptorMBean scriptInterceptor1 = interceptors.createScriptInterceptor("script-1");
scriptInterceptor1.setPriority(50);
PreProcessorScriptMBean pre1 = scriptInterceptor1.getPreProcessor();
pre1.setWorkingDirectory(domainMBean.getRootDirectory());
pre1.setPathToScript("/bin/sh");
pre1.setArguments(new String[] {domainMBean.getRootDirectory() + "/scripts/interceptors/echo-arg-interceptor.sh", "first"});
Properties envAsProps = new Properties();
envAsProps.put("env-key-1", "env-1-value");
envAsProps.put("env-key-2", "env-2-value");
envAsProps.put("env-key-3", "env-3-value");
pre1.setEnvironment(envAsProps);

ScriptInterceptorMBean scriptInterceptor2 = interceptors.createScriptInterceptor("script-2");
scriptInterceptor2.setPriority(20);
PreProcessorScriptMBean pre2 = scriptInterceptor2.getPreProcessor();
pre2.setWorkingDirectory(domainMBean.getRootDirectory());
pre2.setPathToScript("/bin/sh");
pre2.setArguments(new String[] {domainMBean.getRootDirectory() + "/scripts/interceptors/echo-arg-interceptor.sh", "second"});

configManager.save();
configManager.activate(5000);

You can also create and configure script interceptors using the WebLogic Server Administration Console. See Create script interceptors and Configure general settings for a script interceptor in the Oracle WebLogic Server Administration Console Online Help.

Configuring Preprocessor Scripts

Preprocessor scripts are executed by the script interceptor before a scaling operation has begun. Note that if the execution of a preprocessor script fails, neither any subsequent preprocessor script nor the corresponding scaling operation is invoked.

For more information about configuring preprocessor scripts for a script interceptor using the WebLogic Server Administration Console, see Configure preprocessor script settings for a script interceptor in the Oracle WebLogic Server Administration Console Online Help.

Configuring Postprocessor Scripts

Post-processor scripts are executed by the script interceptor after a scaling operation has been completed. Note that if the execution of a postprocessor script fails, the scaling operation that preceded it cannot be cancelled.

For more information about configuring postprocessor scripts for a script interceptor using the WebLogic Server Administration Console, see Configure post-processor script settings for a script interceptor in the Oracle WebLogic Server Administration Console Online Help.

Configuring Error Handling for a Script Interceptor

When configuring a preprocessor or postprocessor script for a script interceptor, you can specify an error handler script to use if an error occurs during the execution of the main script.

The error handler script is executed using the same arguments and environment properties as the command script.

Reserved Environment Variables

Script interceptors can pass both computed and dynamic parameters as environment variables to scripts. In addition, WLDF includes a set of reserved environment variables that can be used in scripts. These reserved environment variables are listed and described in the following table. Note that with the exception of the first variable in this table, WLS_SCRIPT_THIS_STEP_FAILED, each of these variables can be passed to preprocessor scripts, postprocessor scripts, and error handler scripts.

Environment Variable	Description
WLS_SCRIPT_THIS_STEP_FAILED	This variable is passed to error-handler scripts only. Value 'false' indicates some subsequent step failed. A value of `true` indicates that current step failed. A value of `false` indicates that a subsequent step failed.
WLS_SCRIPT_OUTPUT_FILE	Represents the path to the output properties file that scripts may create. The contents of the file will be read and passed to subsequent scripts.
WLS_SCRIPT_TEMP_DIR	Represents the path to the temporary directory in which scripts may create temporary files.
WLS_SCRIPT_DYNAMIC_CLUSTER_NAME	Represents the name of the dynamic cluster that is being scaled up or down.
WLS_SCRIPT_DYNAMIC_CLUSTER_OPERATION_NAME	Represents the current scaling operation, which is either `scaleUp` or `scaleDown`.
WLS_SCRIPT_DYNAMIC_CLUSTER_MIN_SIZE	Represents the minimum size of the dynamic cluster.
WLS_SCRIPT_DYNAMIC_CLUSTER_MAX_SIZE	Represents the maximum size of the dynamic cluster.
WLS_SCRIPT_DYNAMIC_CLUSTER_SIZE	Represents the current size of the dynamic cluster.
WLS_SCRIPT_DYNAMIC_CLUSTER_CANDIDATE_MEMBER_NAMES	Represents the names of candidate servers that may be chosen to be started or stopped.
WLS_SCRIPT_DYNAMIC_CLUSTER_REQUESTED_SCALING_SIZE	Represents the number of running servers in the cluster that are requested to be either incremented or decremented.
WLS_SCRIPT_DYNAMIC_CLUSTER_ALLOWED_SCALING_SIZE	Represents the actual number of servers that will be started or stopped (which may be smaller than the requested scaling size).
WLS_SCRIPT_DYNAMIC_CLUSTER_SCALED_MEMBER_NAMES	Represents the names of the servers that are chosen to be started or stopped during scale up or scale down operations.