Oracle® Communications Service Broker System Administrator's Guide Release 6.1 Part Number E29444-01 |
|
|
PDF · Mobi · ePub |
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.
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.
The roles who use the Scripting Engine include the following: System Administrator, Service Operator, Network Engineer, and Support Engineer.
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
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:
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:
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. |
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.
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.
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=*
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.
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.
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>
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':
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 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>
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.