11 Using Scripts for Configuration and Management

This chapter describes how to use scripts to configure and manage your deployment:

Understanding Scripting
Script Syntax
Starting the Scripting Engine

Understanding Scripting

You can use scripts to manage and configure your Service Broker.

Processing Servers and Signaling Servers expose MBeans. The MBeans are accessible through the Scripting Engine.

The Scripting Engine itself has an MBean server that exposes MBeans related to configuration. These MBeans are accessible through the Scripting Engine.

The Scripting Engine executes operations on MBean-level. Operations and parameters are defined in a script that the Scripting Engine executes. The script format is an XML representation of the MBeans.

The script expresses the MBean operations you want to perform and all data you want to provide as parameters to the operations.

Script Syntax

A script has the top-level element <player>. Each operation to be performed is defined within the element <mbean>. Individual operations are defined within the element <operation>. Each parameter for an operation is defined within an element which name is the same as the parameter name defined by the MBean.

Table 11–1 describes the syntax of the script file.

Table 11-1 Structure of an XML Management Script

Element	Description
player	Main element. Child element: mbean (zero or more) Optional attributes: host port This element defines which JMX server to connect to. The Scripting Engine and all Processing Servers and Signaling Servers have an MBean server. When updating configuration data, the Scripting Engine provides its own JMX server, so there is not need to specify a JMX server. The attribute host corresponds to the host name or IP-address of the server where the Processing Server and Signaling Server is deployed. The attribute port corresponds to the JMX Registry port defined for the Processing Server and Signaling Server. The JMX Registry port for Processing Servers and a Signaling Servers are defined in the domain configuration.
mbean	Parent element: player Child element: operation (zero or more) Attribute: name This element defines the object name of the MBean to use. The attribute name corresponds to the MBean class name. The fully classified name must be used. See the JavaDoc for the MBeans for information on MBean class names.
operation	Parent element: mbean Child element: parameter_name (zero or more) Attribute: name This element defines the operation to invoke on the Mbean defined in the element mbean. The attribute name corresponds to the name of the operation defined by the MBean.
parameter_name	Parent element: operation or another parameter_name Child element: another parameter_name (zero or more) Attribute: no attribute For simple data types, the name of this element corresponds to the name of the in-parameter for the operation. All values of simple data types are represented as the String representation of the value. Boolean values are represented as [TRUE, FALSE] or [1, 0]. For complex data types, see "Representation of Complex Data Structures".
set	Parent element: mbean Child element: none Attributes: name value This element defines which MBean attribute to set and the value to set it to. The MBean is defined in the parent element mbean element. The attribute name defines the name of the MBean attribute. The attribute value defines the value to set.
get	Parent element: mbean Child element: none Attribute: name This element defines which MBean attribute to get. The MBean is defined in the parent mbean element. The attribute name defines the name of the MBean attribute.

Setting and Getting Attributes

An MBean attribute can be set and get using the accessor methods of the attribute.

You get the value by prefixing the attribute name with get or is.

If the accessor method for an attribute is isAttribute_name or getAttribute_name, use the element get in the script to get the value.

If the accessor method for an attribute is setAttribute_name, use the element set in the script to get the value.

Example:

Example 11–1 describes how to get the attribute StartLevel in the MBean oracle.axia.api.management.agent.ManagementAgentMBean. The corresponding method on the MBean is int getStartLevel().

Example 11-1 Getting an MBean Attribute

<mbean name="oracle:type=oracle.axia.api.management.agent.ManagementAgentMBean">
   <get name="StartLevel"/>
</mbean>

Example:

Example 11–2 describes how to set the attribute UseWellKnownAddress on the MBean CoherenceConfigTypeMBean. The MBean is retrieved by using the object name: oracle:name=oracle.axia.storage.provider.coherence,name0=coherenceConfiguration,name1=useWellKnownAddress,type=oracle.axia.cm.ConfigurationMBean,version=1.0.0.0.

Example 11-2 Setting an MBean Attribute

<mbean name="oracle:name=oracle.axia.storage.provider.coherence,name0=coherenceConfiguration,name1=useWellKnownAddress,type=oracle.axia.cm.ConfigurationMBean,version=1.0.0.0">
   <set name="UseWellKnownAddress" value="true"/>
</mbean>

Invoking Operations

MBean operations can be invoked from scripts.

You invoke the operation by defining the name of the operation and in-parameters.

Use the element operation to define that it is an MBean operation. Set the attribute name to the name of the operation. Define each in-parameter to the operations as an XML element and close the element operation.

Example 11–3 describes how to invoke the operation with the signature void openDomain(java.lang.String domainPath) with domainPath set to /usr/local/sb/domain.

Example 11-3 Invoking an MBean Operation

<operation name="openDomain">
  <domainPath>/usr/local/sb/domain</domainPath>
</operation>

Using Variables

Variables can be used in scripts. The notation when using a variable is:

${variable_name}

Variables are set using system properties.

You set system properties by defining the variable using the Java -D flag. Set it in the environment variable AXIA_OPTS. The syntax is

SET AXIA_OPTS=-Dvariable_name=variable_value

For example, to set the variable domain.path to /domains/ocsb-basic-fs set the environment variable AXIA_OPTS using the command:

SET AXIA_OPTS=-Ddomain.path=/domains/ocsb-basic-fs

The value of domain.path is used in the script when the variable is referenced. Below is an example of how to reference it:

<operation name="openDomain">
   <domainPath>${domain.path}</domainPath>
</operation>

If the variable is not defined, the Scripting engine prompts for a value of the variable. For example, if the variable domain.path is not defined as a system property and it is used in a script, the Scripting Engine prompts you for the value as illustrated below:

Enter a value for parameter 'domain.path':

Representation of Complex Data Structures

Complex data structures can be used as in-parameters to operations. When referring to elements of complex data structures in Java, the elements are normally addresses using dot-notation to address individual data structures in the tree. The XML representation uses elements to separate individual member variables until a simple data object is reached.

The XML representation of this type is derived from the Java class using reflection.

For example, consider the Java class:

public class AnAddress {
   String host;
   int port;
}

An object of this class is used as a parameter to the MBean operation.

When defining the object in Java it could look like:

...
AnAddress anAddress = new AnAddress;
anAddress.host="localhost";
anAddress.port=9002;
...

The XML representation of the definition is

<anAddress>
        <host>localhost</host>
        <port>9002</port>
/<anAddress>

Example Script

Example 11–4 illustrates a script that creates the domain configuration directory /mydomain, and defines the Processing Server pn_2. The server is defined to execute on localhost, use the administration port 8902, listen to port 9002, use the JMX port 10103, and the JMX registry port 10003. Finally, the script closes the domain.

Example 11-4 Script That Creates a Domain Configuration and adds a Processing Server.

<!-- player connects to a particular host and port -->
<player>
  <!-- one or more mbeans -->
  <mbean name="DomainServiceMBean">
    <operation name="createDomain">
      <domainPath>/mydomain</domainPath>
    </operation>
    <operation name="openDomain">
      <domainPath>/mydomain</domainPath>
    </operation>
    <operation name="addManagedServer">
      <name>pn_2</name>
      <host>localhost</host>
      <port>9002</port>
      <adminPort>8902</adminPort>
      <jmxJrmpPort>10103</jmxJrmpPort>
      <jmxRegistryPort>10003</jmxRegistryPort>
    </operation>
    <operation name="closeDomain"/>
   
  </mbean>
</player>

Starting the Scripting Engine

The Scripting Engine can be used for changing configurations and to monitor Processing Servers and Signaling Servers.

You start the Scripting Engine from the directory Oracle_home/axia/admin_/console.

Oracle_home is the Oracle Home directory defined when you installed Service Broker.

The Scripting Engine is invoked using the script:

./script.sh xml_script_file

Replace xml_script_file with the file name of to script you want to execute.

The process that starts the Scripting Engine must have read-write privileges on the file system where the domain configuration resides.