6 Managing Domains

This chapter describes how to manage and configure a domain.

Understanding Domains
Creating a Domain
- Creating a Domain That Is Accessed Using a Shared File System
- Creating a Domain That Is Accessed Using HTTP
Opening a Domain Configuration and Locking It for Changes
Switching Domain Configuration Mode
Mapping Custom Server Names to Names Required by Service Broker
Setting a Service Broker Domain Name
Adding a Server to a Domain Configuration
Removing a Server from a Domain Configuration
Managing Domain Properties
DomainServiceMBean
ConfigurationAdminMBean

Understanding Domains

A set of Processing Servers are grouped into a Processing Domain and a set of Signaling Servers are grouped into a Signaling Domain.

Servers within a domain are symmetrical, which means that they all have the same bundles deployed and started. A domain has an associated domain configuration. The domain configuration is kept in a directory that is accessed by all servers in the domain. The directory is accessed using a shared file system or by way of the Domain Web server.

The domains interwork and propagate protocol events across the tier boundaries. Figure 6–1 gives an overview of the tiers and the domains and how they interwork.

Figure 6-1 Overview of Domains and Tiers

An administration client, for example the Administration Console, has access to all domain configurations and can propagate management operations and configuration updates to all Processing Servers and Signaling Servers, regardless of which domain they belong to. An administration client is either the stand-alone Administration Console, the Web Console Web server, the Scripting Engine, or an external client.

The administration clients use the DomainServiceMBean to:

Create and remove a domain configuration.
Add servers to and remove servers from the domain configuration.
Manage properties for a domain.
Manage settings for servers in a domain.
Specify whether to work in online mode (where configuration updates are propagated to all servers in the domain as each change is made) or offline mode (where updates are saved to the domain configuration directory and propagated to servers later).

Creating a Domain

When you create a domain, the domain's bundles are copied to a domain directory. Configuration data for the particular domain is stored in this directory. You specify the location of the domain directory when you start the servers.

You choose how your servers access the domain configuration directory:

Using a shared file system

You must make sure that the servers have access to the specified directory. For information on setting up a shared file system, see the documentation for your operating system.
Using HTTP

You must make sure that the Domain Web server can access the domain directory and that the URL is mapped to that directory. See Chapter 5, "Starting and Stopping Domain Web Servers".
Note:
- The Domain Web server is intended for test and evaluation environments only. You should not use the Domain Web server in a production deployment.

In both cases, you need to specify the type of domain you are creating:

Processing Domain
Signaling Domain
Combined

If you need to, you can later change some of the settings (see "Managing Domain Properties").

Two scripts are provided that simplify the domain creation process:

create_domain.xml
create_hosted_domain.xml

The scripts are stored in the following directory:

Oracle_home/axia/admin_console/scripts

Execute the scripts using the Scripting Engine. Start the scripts from the directory admin_console.

The default cluster setting for domains created by the scripts is IP-multicast, and you will be prompted for multicast settings when running the scripts. This setting can be changed after the domain is created. See Chapter 8, "Managing Clusters" for more information.

For information about the scripts, see "Creating a Domain That Is Accessed Using a Shared File System" and "Creating a Domain That Is Accessed Using HTTP".

You can also use the DomainServiceMBean directly to create your domain:

To access the domain directory using a Shared File System, invoke the operation void createDomain(String type, String domainPath).
To access the domain directory using HTTP, invoke the operation void createHostedDomain(String type, String domainPath, String hostAddress).

Creating a Domain That Is Accessed Using a Shared File System

The script create_domain.xml creates a domain that is accessed using a shared file system.

To create a domain:

Execute the script by entering:

script.sh scripts/create_domain.xml
When you are prompted for domain.type, enter one of the following:
- ocsb-pn to create a Processing Domain.
- ocsb-ssu to create a Signaling Domain.
- ocsb-basic to create a combined Domain.
When you are prompted for domain.path, enter the path to the directory where the domain configuration shall be created.
When you are prompted for domain.axia.ssl, enter:
- true to enable SSL.
- false to disable SSL.
  
  This parameter corresponds to the domain property axia.ssl. See Managing Domain Properties.
When you are prompted for multicast.address, enter the IP multicast address to use to join the domains. The value of the multicast.address parameter must be within the range 224.0.0.0 to 239.255.255.255.
When you are prompted for multicast.port, enter the IP multicast port to use to join the domains. The value of the multicast.port parameter must be 1024 or greater.
When you are prompted for multicast.ttl, enter the time-to-live for a multicast. The value of the multicast.ttl parameter must be 1 or greater.

Example with input in bold:

Enter a value for parameter 'domain.type': ocsb-basic
Enter a value for parameter 'domain.path': /domains/ocsb-basic-fs
Enter a value for parameter 'domain.axia.ssl': false
Enter a value for parameter 'multicast.address': 239.255.255.255
Enter a value for parameter 'multicast.port': 1234
Enter a value for parameter 'multicast.ttl': 1

Creating a Domain That Is Accessed Using HTTP

The script create_hosted_domain.xml creates a domain that is accessed using HTTP.

To create a domain:

Execute the script by entering:

script.sh scripts/create_hosted_domain.xml
When you are prompted for domain.type, enter:
- ocsb-pn to create a Processing Domain.
- ocsb-ssu to create a Signaling Domain.
- ocsb-basic to create a combined Domain.
When you are prompted for domain.path, enter the path to the directory where the domain configuration shall be created.
When you are prompted for domain.hosted.url, enter the host name and port for the Domain Web server that gives access to the domain configuration.

The port is defined in the property org.eclipse.equinox.http.jetty.http.port in the file hosting.properties. Default value is 9000. See Appendix A, "System Administrator's Reference".

Also see Chapter 5, "Starting and Stopping Domain Web Servers".
When you are prompted for domain.axia.ssl, enter:
- true to enable SSL.
- false to disable SSL.
  
  This parameter corresponds to the domain property axia.ssl. See Managing Domain Properties.
When you are prompted for multicast.address, enter the IP multicast address to use to join the domains. The value of the multicast.address parameter must be within the range 224.0.0.0 to 239.255.255.255.
When you are prompted for multicast.port, enter the IP multicast port to use to join the domains. The value of the multicast.port parameter must be 1024 or greater.
When you are prompted for multicast.ttl, enter the time-to-live for a multicast. The value of the multicast.ttl parameter must be 1 or greater.

Example with input in bold:

Enter a value for parameter 'domain.type': ocsb-basic
Enter a value for parameter 'domain.path': /domains/ocsb-basic-http
Enter a value for parameter 'domain.hosted.url': http://localhost:9001/
Enter a value for parameter 'domain.axia.ssl': false
Enter a value for parameter 'multicast.address': 239.255.255.255
Enter a value for parameter 'multicast.port': 1234
Enter a value for parameter 'multicast.ttl': 1

Opening a Domain Configuration and Locking It for Changes

You need to open a domain configuration in order to make configuration updates to it. When you open the domain, it is locked for edits from other administration clients. To open a domain configuration, invoke the operation openDomain on the MBean DomainServiceMBean.

Once you open the domain, you can make configuration changes in two modes:

Autocommit mode

When you update configurations in this mode, changes are committed and written to the configuration directory immediately. This is the default configuration mode.
Transaction mode

When you update configuration in this mode, multiple changes accumulate into one transaction. Setting the domain configuration to transaction mode makes it possible to perform a set of configuration updates and have them applied all at once. To change to the transaction mode, invoke the operation begin on the MBean ConfigurationAdminMBean. To commit the accumulated changes, invoke the operation commit on the MBean ConfigurationAdminMBean. To discard the accumulated changes, invoke the operation rollback on the MBean ConfigurationAdminMBean.

To release the lock created when the domain was opened, invoke the operation closeDomain on the MBean DomainServiceMBean.

Switching Domain Configuration Mode

The domain configuration mode specifies how configuration updates are propagated to servers in the domain.

If configuration updates are propagated to all servers in the domain as the changes are done, the domain configuration is online.

If updates are done only to the domain configuration and applied to each server when it is re-started, the domain configuration is offline.

Setting the domain configuration offline makes it possible to perform a set of configuration updates and have them applied the next time a server is restarted. This is used for example when doing a rolling upgrade of an installation.

To switch the domain configuration mode from online to offline, or from offline to online, invoke the operation setOffline on the MBean DomainServiceMBean.

Mapping Custom Server Names to Names Required by Service Broker

To operate properly, Service Broker imposes the following requirements on naming servers in the Signaling Domain and Processing Domain:

Names of Signaling Servers must follow the pattern "ssu_<server-number>". For example, the following names are valid: ssu_1, ssu_2, ssu_3.
Names of Processing Servers must follow the pattern "pn_<server-number>". For example, the following names are valid: pn_1, pn_2, pn_3.

During the installation, if you specified custom server names that do not follow these patterns, you need to map custom server names to names that follow the pattern required by Service Broker. You can perform this mapping using ServersMBean and ServerMBean.

For more information, see "Mapping Custom Server Names to Service Broker Server Names" in Oracle Communications Service Broker Configuration Guide.

Setting a Service Broker Domain Name

After you created a domain, in addition to the name that you assigned to this domain during its creation, you must assign a Service Broker domain name to it.

For more information, see "Setting a Service Broker Domain Name" in Oracle Communications Service Broker Configuration Guide.

Adding a Server to a Domain Configuration

Each Signaling Server and Processing Server has a set of server-unique settings that identifies the server in the domain. Table 6–1 describes the server settings.

Table 6-1 Server Settings

Property	Description
name	The name of the server. The name must be unique across all domains. You use this name when you start the server. Format: alpha-numeric characters. Case-sensitive. Do not use white space in the name.
host	The host name or IP-address of the machine where the server will run. Format: alpha-numeric. IP-address format or DNS name format.
port	General purpose IP port to use for traffic to the server. Format: numeric.
adminPort	The IP port to use for propagating configuration updates to the server. Format: numeric
jmxJrmpPort	The port to use for Java Remote Method Protocol (JRMP) invocations to the server. Format: numeric.
jmxRegistryPort	The port to use for the MBean server. Format: numeric.

To add a server to a domain configuration, invoke the operation addManagedServer on the MBean DomainServiceMBean. Provide the server settings as parameters to the operation.

When adding a new server to your deployment, the server software needs to be installed, it needs to be added to the domain configuration, and it needs to be configured. For a description of this procedure, see Chapter 7, "Adding and Removing Processing Servers and Signaling Servers".

Removing a Server from a Domain Configuration

To remove a server from a domain configuration, invoke the operation removeManagedServer on the MBean DomainServiceMBean.

When removing a server from your deployment, the server software needs to be removed, it needs to be removed from the domain configuration, and server-specific settings needs to be removed. For a description of this procedure, see Chapter 7, "Adding and Removing Processing Servers and Signaling Servers".

Managing Domain Properties

Each domain configuration has a set of properties. The properties are name-value pairs. See Table 6–2.

The domain properties are set when the domain configuration is created and they can be edited.

Table 6-2 Domain Properties

Name	Value
axia.domain.host	Specifies the URI to the domain configuration. Format: [file\| http]://Context_path If your domain configuration is accessed using the Domain Web server, use the scheme http://. Example: http://myhost:9000/ If your domain configuration is accessed using a shared file system, use the scheme file://.
axia.ssl	Specifies if SSL is enabled or disabled for management operations. Set this property to: true to enable SLL. false to disable SSL See Chapter 1, "Configuring Security".
axia.admin.ssl	Specifies if SSL is enabled or disabled for the administration port. Set this property to: true to enable security for the administration port. false to disable security for the administration port. The administration port is used for propagating configuration updates and to deploy OSGi bundles to servers. Only valid if axia.ssl is set to true. See Chapter 1, "Configuring Security".
axia.domain.id	Specifies the domain name in a multi-processing domain. To maintain domain exclusivity, each domain is assigned a unique name. All domains with the same ID are assumed to be in the same domain. Format: Can only contain letters, digits or underscores (a-z, A-Z, 0-9_). Case sensitive. Length: Between 1 and 8 characters. Examples: 23DoMain domain_1 If no name is specifically assigned, the value is default.

To change or set domain property, invoke the operation setDomainProperty on the MBean DomainServiceMBean.

Provide the new property name-value pair to change as parameters to the operation. See Table 6–2.

DomainServiceMBean

JAR File

oracle.axia.platform.domainservice-version.jar

where version is the version number of the JAR file: for example, 1.0.0.0.

Package

oracle.axia.api.management.ds

Object Name

oracle:type=oracle.axia.api.management.ds.DomainServiceMBean

Factory Method

Created automatically.

Attributes

None.

Operations

void addManagedServer(String name, String host, int port, int adminPort, int jmxJrmpPort, int jmxRegistryPort)

Adds a new server to a domain configuration. See "Adding a Server to a Domain Configuration".

Parameters:

name Name of the server.
host Host of the server.
port General purpose port of the server.
adminPort Administration port of the server.
jmxJrmpPort JMX port of the server.
jmxRegistryPort JMX registry port of the server.

void closeDomain()

Closes a domain that has been opened for updates.

void createDomain(String type, String domainPath)

Creates a domain that is accessed by the servers using a shared file system.

Parameters:

type Type of domain to create of the server. Set it to:
- ocsb-pn to create a Processing Domain.
- ocsb-ssu to create a Signaling Domain.
- ocsb-basic to create a combined Domain.
domainPath Path to the directory where the domain configuration is created.

void createHostedDomain(String type, String domainPath, String hostAddress)

Creates a domain that is accessed by the Service Broker servers using HTTP or HTTPS.

Parameters:

type See createDomain.
domainPath See createDomain.
hostAddress Host and port for the Domain Web Server.

void editManagedServer(String name, String host, int port, int adminPort, int jmxJrmpPort, int jmxRegistryPort)

Edits the settings for a server. See "Adding a Server to a Domain Configuration".

Parameters:

name Name of the server.
host Host of the server.
port Port of the server.
adminPort Administration port of the server.
jmxJrmpPort JMX port of the server.
jmxRegistryPort JMX registry port of the server.

String getDomainProperty(String name)

Gets the value of a domain property. See Table 6–2.

Parameter:

name Name of the property.

isOffline()

Returns true if the domain is in offline configuration mode.

java.util.List<String>listDomainTypes()

Lists available domain types.

java.util.List<String>listServers()

Lists the name of the servers in the domain.

void openDomain(String domainPath)

Opens a domain for editing.

Parameter:

domainPath Path to the directory where the domain configuration is located.

void removeManagedServer(String name)

Removes a server from a domain.

Parameter:

name Name of the server to remove. See Table 6–1

void renameDomainProperty(String oldName, String newName, String value)

Renames a domain property. See Table 6–2.

Parameters:

oldName Old name of the property.
newName new name of the property.
value Value of the property.

void setDomainProperty(String name, String value)

Sets a property for a domain. See Table 6–2.

Parameters:

name Name of the property.
value Value of the property.

void setOffline(boolean offline)

Sets the domain to Offline or Online mode.

Parameter:

offline True to set the domain configuration mode to offline, and false to set it to online.

ConfigurationAdminMBean

JAR File

oracle.axia.cm.api-version.jar

where version is the version number of the JAR file: for example, 1.0.0.0.

Package

oracle.axia.api.management.cm

Object Name

oracle:type=oracle.axia.api.management.cm.ConfigurationAdminMBean

Factory Method

Created automatically.

Attributes

None.

Operations

void begin(): Sets the configuration changes mode to the Transaction mode.
void commit(): Commits configuration changes accumulated since the configuration changes mode changed to the Transaction mode using the begin operation.
boolean isTransactionActive(): Indicates if the configuration chnages mode is set to the Transaction mode.
java.util.List<String>listPendingConfiguration(): Lists pending configuration entries accumulated since the configuration changes mode changed to the Transaction mode using the begin operation.
void rollback(): Discards any pending configuration entries accumulated since the configuration changes mode changed to the Transaction mode using the begin operation.