Skip Headers
Oracle® Communications Service Broker System Administrator's Guide
Release 6.1
Part Number E29444-01
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
PDF · Mobi · ePub

4 Using the Scripting Engine to Configure a Domain

This chapter describes how to use the scripts to configure and manage a domain.

Scripts are used to automate configuration tasks you want to repeat multiple times. For example, you can use a script to configure multiple clusters of managed servers.

About Using Scripts

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 an 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 the data you want to provide as parameters to the operations.

Audience For Using The Scripting Engine

The roles who use the Scripting Engine include the following: System Administrator, Service Operator, Network Engineer, and Support Engineer.

Tasks You Can Perform Using the Scripting Engine

You can perform many essential tasks using the Administration Console including the following:

  • Add and configure managed servers in a domain

  • Manage Signaling Domain Signaling Server Units (SSUs): Configure IP addresses, point codes, routes, timeout intervals

  • Manage Processing Domain Interworking Modules (IMs) and supplementary IMs

  • Configure the Orchestration Engine (OE)

  • Manage Applications

  • Manage the Subscriber Store

  • Install and update software bundles

  • Configure SNMP traps

  • Configure Diameter AVPs

  • Manage the credential stores

  • Manage the persistent stores

  • Manage runtime 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 whose name is the same as the parameter name defined by the MBean.

Table 4-1 describes the syntax of the script file.

Table 4-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 no 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 are deployed.

The attribute port corresponds to the JMX Registry port defined for the Processing Servers and Signaling Servers.

The JMX Registry port for Processing Servers and 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 Oracle Communications Service Broker Configuration and Runtime MBean Java API Reference 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].

See "Representing Complex Data Structures" for complex data types.

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 4-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 4-1 Getting an MBean Attribute

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

Example 4-2 describes how to set the attribute UseWellKnownAddress on the MBean CoherenceConfigTypeMBean. The MBean is retrieved 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 4-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 4-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 4-3 Invoking an MBean Operation

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

Using Wildcard Characters in Scripts

The Scripting Engine supports the “*“ (asterisk) and “?“ (question mark) wildcard characters to match MBean names. The asterisk matches any sequence of zero or more characters, and the question mark matches any single character.

This example matches all versions of this Diameter MBean.

oracle:type=oracle.axia.cm.ConfigurationMBean,name=oracle.axia.protocol.diameter,version=*

Creating and Using Variables in Scripts

Your Scripting Engine scripts gets the value of a variable using this notation:

${variable_name}

Where:

variable_name is the name you give each variable.

You have these options for setting the value of a variable using the Windows-based operating systems:

  • Using -Dvar_name=variable_name.

  • Using result_property.

  • Entering a value manually at the script prompts (if the variable is undefined).

These options are explained in the following sections.

Using AXIA_OPTS to Create Variables

You define variables from the command line using the AXIA_OPTS environment variables.

The syntax for AXIA_OPTS is:

export AXIA_OPTS=-Dvariable_name=variable_value

For example, use this command to set the variable domain.path to /domains/ocsb-basic-fs:

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

The value of domain.path is used in the script when the variable is referenced. This example references it:

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

AXIA_OPTS supports multiple arguments.

Using result_property to Create Variables

You can specify the Scripting Engine to capture the result of an MBean operations using the result_property attribute. This example

<mbean name="oracle:type=oracle.axia.cm.ConfigurationMBean,name=oracle.axia.protocol.diameter,version=2.0.0,name0=ProtocolAdapter,name1=workManagers,name2=workManager[0],name3=capacity">
  <operation name="capacity result_property="workmanager.capacity"/>
  <operation name="increaseWMcapacity>
    <arg1>${workmanager.capacity}</arg1>
  </operation
</mbean>

Entering Undefined Variable Values at a Script Prompt

If a variable is not defined in a script, the Scripting Engine prompts for a value of the variable at the command line. 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 like this:

Enter a value for parameter 'domain.path':

Representing Complex Data Structures

You can use complex data structures as in-parameters to operations. When referring to elements of complex data structures in Java, the elements are normally addressed 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 this:

...
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 4-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 4-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/ocsb61/admin_server.

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.

Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Book List
Book List		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us