# System Administrator’s Guide

# Deployment Model for Communication Services and Container Services

This section describes the deployment model used in Oracle Communications Services Gatekeeper. Communication services are packaged and deployed in EAR files. The EAR files are grouped, all network protocol plug-ins that share the same group of application-facing interfaces, are packaged into the same EAR file.

Container services are packaged and deployed separately from the communication services, and should not be modified.

- Packaging of Communication Services

- Version Handling of Communication Services
- Deploy and Undeploy Communication Services and plug-ins
- Version Handling and Patching of Communication Services

- Overview of Container Services and Configuration Files

- Container services
- Retired container services
- Retired container services
- Disabling of ORB
- Patching of Container Services

## Packaging of Communication Services

The communication services are grouped so that all communication services that share a common set of application-facing interfaces are grouped together. For example, off-the-shelf, Oracle Communications Services Gatekeeper is delivered with two communication services for Parlay X 2. 1 Third Party Call:

- Parlay X 2. 1 Third Party Call/INAP, where INAP is exposed through Parlay X 2.1 Third Party Call interfaces.
- Parlay X 2. 1 Third Party Call/SIP, where SIP is exposed through Parlay X 2.1 Third Party Call interfaces.

Each group of communication services is packaged in two separate EAR files:

`wlng_at_<communication service>.ear`, which serves as the service facade. This part consists only of modules shared among the communication service. The `wlng_at_<communication service>.ear` is deployed in the Access Tier.

`wlng_nt_<communication service>.ear`, which serves as the service enabler. This part contains the network protocol plug-ins for the communication service and common modules for the communication service. The `wlng_nt_<communication service>.ear` is deployed in the Network Tier.

The communication services EAR files are located in the `$BEA_HOME/ocsg_4.1/applications` directory.

.

Example
The files holding the communication services that share the Parlay X 2.1 Third Party Call communication service layer consist of the following artifacts: `wlng_at_third_party_call_px21.ear` `wlng_nt_third_party_call_px21.ear` wlng_nt_third_party_call_px21.ear contains, among other modules: `Plugin_px21_third_party_call_inap.jar`, which contains the Parlay X 2.1 Third Party Call/INAP plug-in. `Plugin_px21_third_party_call_sip.jar`, which contains the Parlay X 2.1 Third Party Call/SIP plug-in. See note below. Other modules in this EAR are shared between the two network protocol plug-ins: including the common parts that are tied to the implementation of the communication layer, and any libraries and utilities shared among the plug-ins.
Note: | `Plugin_px21_third_party_call_sip.jar` is not the only artifact needed in order to achieve end-to-end service communication for communications services connecting to the SIP network. There is also a part that is deployed as a SIP servlet in the SIP Server container. In addition, for plug-ins that use HTPP as the transport protocol and handle network-triggered messages from the network node, there is an HTTP servet. HTTP servlets are packaged as Web Archives (WARs) and are packaged in the networ tier EAR for the communication service . The SIP servlet parts are packaged in a set of files: wlng-integration-management.jar, wlng-integration-console-ext.war, wlss-int.ear, and wlng-security.jar.

When adding or removing a plug-in to or from `wlng_nt_<communication service>.ear`, the EAR must be exploded and the plug-in specific parts being either added or removed.

Listing 17-1describes the elements in `wlng_nt_<communication service>.ear`.

Listing 17-1 Contents of wlng_nt_<communication service>.ear

    +---APP-INF/lib

                ...

                <communication service>_callback_client.jar

                /<utilities 1>.jar

                ...

                /<utilities n>.jar

    +---META-INF/MANIFEST.MF

                /application.xml

                /weblogic-application.xml

                /weblogic-extension.xml

    +---<plug-in 1>.jar

         ...

    +---<plug-in n>.jar

    +---<plug-in 1>.war

         ...

    +---<plug-in n>.war

    +---<communication service>_service.jar

All plug-ins in the service enabler are packaged as individual jar files in the root of the EAR together with the service EJB, `<communication service>_service.jar`.

If a plug-in connects to the telecom network using HTTP and supports network-triggered requests, there is also a corresponding WAR file that contains the servlet.

`APP-INF/lib` contains any JARs that are shared among the plug-ins in the EAR. This includes the client library for the service callback EJB `<communication service>_callb`ack_client.jar and one or more utility jar files can be present, depending on the type of communication service.

`META-INF/MANIFEST.MF` is a standard manifest file.

`META-INF/application.xml` is the standard deployment descriptor for EARs.

`META-INF/weblogic-application.xml` is the WebLogic Server-specific deployment descriptor.

`META-INF/weblogic-extension.xml` is a WebLogic Server-specific deployment descriptor.

For more information about enterprise application deployment descriptor elements, see Oracle WebLogic Server Developing Applications with WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/programming.

Listing 17-2 describes the elements in a plug-in jar file.

Listing 17-2 Contents of <plug-in X>.jar

    +---com/

    +---org/

    +---META-INF/MANIFEST.MF

    +   instancemap

    +   srv_depl.xml

The jar contains the regular elements in a jar and also an `instancemap`, used among other thing to instantiate the plug-in specific implementation of the plug-in interface using the InstanceFactory. See InstanceFactory in Platform Development Studio - Developer’s Guide for more information.

### Deployment of SOAP and RESTful Facades on Multiple AT Clusters

For those communication services that have RESTful facades, both SOAP and RESTful facades are included in the standard EAR files. If your installation uses a single cluster of AT servers, this raises no issues. But if your installation needs to use multiple clusters of AT servers, you need to make some adjustments. As a result of certain internal characteristics, it is not possible to deploy the RESTful facade on multiple AT clusters within the same domain. It is possible to deploy both the RESTful facade and the SOAP facade on a single cluster within the domain and to deploy only the SOAP facade on multiple other clusters within that same domain. To support this, a special second set of EAR files should be deployed instead of the standard EAR files. These special equivalent EAR versions contain only SOAP interfaces. The file names are identical to those of the standard files except that a `_soap` is appended to the end of the name. The following is a list of the SOAP-only EAR files that should be deployed (as needed) in this situation:

- wlng_at_call_notification_px21_soap.ear
- wlng_at_multimedia_messaging_px21_soap.ear
- wlng_at_payment_px30_soap.ear
- wlng_at_presence_px21_soap.ear
- wlng_at_push_message_ews_soap.ear
- wlng_at_session_soap.ear
- wlng_at_sms_px21_soap.ear
- wlng_at_subscriber_profile_ews_soap.ear
- wlng_at_terminal_location_px21_soap.ear
- wlng_at_third_party_call_px21_soap.ear

These files are found in the `$BEAHOME/ocsg_4.1.1/applications` directory of your installation. Information on the content of these files is available in the “Properties” section of each respective communication services reference in this guide.

This procedure should be done before going into production. It is recommended that you make the console-based changes (all but step 6) with only the Admin Server running. For step 6, you will need to shut down all servers and re-start.

In general these are the steps required. Using the Admin console:

1. Create Managed Servers for the non-REST AT clusters (for example, WLNG_AT1 and WLNG_AT2).
2. Create Managed Servers for the REST_AT cluster (for example, REST_AT1 and REST_AT2)
3. Create the clusters for these servers (for example WLNG_AT_Cluster and REST_AT_Cluster).
4. Assign the Managed Servers to their appropriate clusters:

WLNG_AT_Cluster WLNG_AT1 WLNG_AT2

REST_AT_Cluster REST_AT1 REST_AT2

5. Change all deployed applications with REST interfaces (that is, the standard EARs), including session manager, to target REST_AT_Cluster
6. Change the targets of the AT JMS Servers from WLNG_AT* to the REST_AT*
7. Change the target of WLNG_ATJMSResource from WLNG_AT_Cluster to REST_AT_Cluster.
8. Shut down all servers. Carefully edit the config.xml file manually. In default installations this file can be found at `<domain-home>/config/config.xml.`
Listing 17-3 The snippet to edit

    <custom-resource>

      <name>accesstier</name>

      <target>WLNG_AT_Cluster</target>

      <descriptor-file-name>custom/at.xml</descriptor-file-name>

      <resource-class>com.bea.wlcp.wlng.management.descriptor.resource.WlngTierResource</resource-class>

      <descriptor-bean-class>com.bea.wlcp.wlng.management.descriptor.bean.WlngTierBean</descriptor-bean-class>

      </custom-resource>

Change the target in the accesstier custom resource from WLNG_AT_Cluster to WLNG_AT_Cluster, REST_AT_Cluster.

9. Start up the Admin Server and install and deploy the SOAP-only EAR files to the non-REST cluster (WLNG_AT_Cluster).
10. Start the newly installed EAR files using the Admin Console. If you forget to do this, their status will be “prepared”.
11. Start your Managed Servers.

For more information on using the Admin Console to accomplish these tasks, click Help on the console screeen. WebLogic Server Administration Console Help comes up.

### Version Handling of Communication Services

Communication services are versioned and can be upgraded using in-production deployment.

The versioning is on EAR level, which means that all network protocol plug-ins for a given collection of application-facing interface are redeployed.

The version is specified in the attribute `Weblogic-Application-Version` in `META-INF/manifest.mf` in `wlng_at_<communication service>.ear` and `wlng_nt_<communication service>.ear`, respectively.

For more information about how to develop applications for production redeployment, see Oracle WebLogic Developing Applications with WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/programming/index.html.

### Deploy and Undeploy Communication Services and plug-ins

Individual communication service are deployed and undeployed as EARs.

See Oracle WebLogic Server Deploying Applications to WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/deployment/ for a description of the different deployment options.

The EAR names for each communication service and the JAR names for the network protocol plug-in are found under the heading “Properties for <Communication service>” in the section of Oracle Communications Services Gatekeeper Administration Guide (this guide) which describes the management of the network protocol plug-in for the communication service in question.

For example, the EAR names for the Third Party Call communication service are found in Properties for Parlay X 3.0 Third Party Call/Parlay MultiParty Call Control, Properties for Parlay X 2.1 Third Party Call/SIP, and Properties for Parlay X 2.1 Third Party Call/INAP.

The properties section also describes the JAR file for the plug-in and other artifacts, such as third-party libraries, used by the plug-in.

Below is an example on how to undeploy the Parlay X 2.1 Third Party Call communication service:

    java weblogic.Deployer -adminurl http://<admin host>:<admin port> -user <admin user> -password <admin password -name wlng_nt_third_party_call_px21 -undeploy -graceful

If a plug-in has been removed from the EAR, use the mechanism described in Performing a Hitless Upgrade.

### Version Handling and Patching of Communication Services

To upgrade communication services, patches are applied using a patch tool. The patch tool operates on the EAR files for the communication services. The version of the plug-in is the same as the version of the service enabler it is packaged in, the versioning is on EAR file level.

Below is the typical process for applying patches to communication services.

1. The patch, in the form of a JAR file is provided.
2. The patch is applied to the original EAR file witch results in a new, patched, EAR. For example, if the original EAR version is 4.0, the version of the new EAR is 4.0_1. A sequence number should be suffixed to make each version unique.
3. The new EAR file is deployed and the old version is undeployed, using in-production redeployment, see Hitless Upgrade Using Production Redeployment.
4. If another issue is detected for the same EAR a second patch JAR is provided.
5. The patch is applied to the already patched EAR and creates version 4.0_2.
6. The new patched EAR is deployed.

Alternatively, both patches can be applied at the same time. This will result in the same version as when applying them separately (version 4.0_2).

#### Patch Tool

Patches are applied using an Ant build file: `$BEA_HOME/ocsg_4.1/server/bin/build.xml`

The correct `CLASSPATH` must be setup in order for the patch build file. Run `setWLSEnv.sh` or `setWLSEnv.cmd` located in `$BEA_HOME/`wlsserver_10.3/server/bin to setup the environment.

There are two targets available in the build file:

- `patch` - Applies patches to an EAR file.
- `printpatches` - Displays the currently applied patches.

The syntax is:

    ant [patch | printpatches] -Dsrc= -Ddest= -Dversion= -Dpatchdir= -Dpatchfiles=

Table 17-1 Arguments to patch build file
Target/Argument | Description
--- | ---
patch | This target applies a patch.
printpatches | This target displays the currently applied patches. The information includes: Manifest for the EAR Manifest-Version Bundle-Name Created-By Ant-Version Weblogic-Application-Version Bundle-Vendor Bundle-Version For each JAR in the EAR, patched class and ID of the patch is displayed.
src | The EAR file to apply the patch to.
dest | The EAR file that will contain the patch.
version | The new version for the EAR. Must be different from the original version.
patchdir | Directory that holds the patches. Paths are relative or absolute.
patchfiles | The JAR files that contains the patches. Wild cards are supported.

The patch tool detects conflicts if multiple patches try to patch the same file. In this situation an error message is displayed and combination (combo) patch must be used.

#### Examples

Below are usage examples.

Example | Command
--- | ---
View patch information for a single EAR file. | `ant printpatches -Dsrc=original.ear`
View patch information for all EARs in specified directory. | `ant printpatches -Dsrc=/path_to_ears`
Apply a single patch to an EAR. | `ant patch -Dsrc=original.ear -Ddest=patched.ear -Dversion=4.0_1 -Dpatchdir=/patches -Dpatchfiles=CR1234.jar`
Apply all patches located in the directory /patches. | `ant patch -Dsrc=original.ear -Ddest=patched.ear -Dversion=4.0_2 -Dpatchdir=/patches -Dpatchfiles=*.jar`

## Overview of Container Services and Configuration Files

Table 17-2 gives an overview of the Oracle Communications Services Gatekeeper configuration files.

Table 17-2 Oracle Communications Services Gatekeeper Configuration files
File | Contains configuration for...
--- | ---
$DOMAIN_HOME/config/config.xml | WebLogic Server. See the section describing the domain configuration files in Oracle WebLogic Server Understanding Domain Configuration at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/domain_config/ The following additions are specific to Oracle Communications Services Gatekeeper: ...a <custom-resource>, with `<name>accesstier</name>`, that specifies the location of at.xml. ...a <custom-resource>, with `<name>networktier</name>`, that specifies the location of nt.xml. ...A set of <app-deployment> specific for the deployed communication services. See the Deployment Artifacts section for the relevant communication service in Communication Service Reference. Do not edit this file manually. To manage the life-cycle of communication services, use the WebLogic Server tools, such as the Administration Console’s Deployment page or the command line tools described in Oracle WebLogic Server Deploying Applications to WebLogic Server at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/deployment/
$DOMAIN_HOME/config/custom/at.xml | Oracle Communications Services Gatekeeper Access Tier container and container services. This is a custom resource.
Note: | Do not edit this file.
$DOMAIN_HOME/config/custom/nt.xml | Oracle Communications Services Gatekeeper Network Tier container and container services. This is a custom resource.
Note: | Do not edit this file.
$DOMAIN_HOME/config/custom/wlng-edr.xml | EDRs, CDRs, and alarms. This is a custom resource
Note: | Do not edit this file manually.

### Container services

Table 17-3 describes the Oracle Communications Services Gatekeeper container services. The interfaces to these, together with common classes, are packaged in

    $BEA_HOME/ocsg_4.1/server/lib/wlng/wlng.jar

The container services are packaged in separate JARs, located in `$BEA_HOME/ocsg_4.1/modules`

Table 17-3 Container services
Container service | Summary
--- | ---
com.bea.wlcp.wlng.core.CoreServerService | Performs initial setup during the start-up sequence.
com.bea.wlcp.wlng.snmp.SNMPServerService | SNMP service.
com.bea.wlcp.wlng.corba.ob.OrbacusServerService | Initializes the Orbacus ORB and makes that the default ORB.
com.bea.wlcp.wlng.event_channel.EventChannelServerService | Broadcasts arbitrary events between modules and servers in a cluster.
com.bea.wlcp.wlng.storage.StorageServerService | Storage service.
com.bea.wlcp.wlng.storage.db.DbServerService | Storage provider for persistence using direct database access.
com.bea.wlcp.wlng.storage.inval.InvalidatingServerService | Storage provider for persistence using an invalidating cache.
com.bea.wlcp.wlng.storage.configuration.ConfigurationStoreServerService | Storage provider for configuration settings.
com.bea.wlcp.wlng.edr.EdrServerService | EDR service.
com.bea.wlcp.wlng.core.budget.BudgetServerService | Budget service.
com.bea.wlcp.wlng.georedundant.GeoRedundantServerService | Geographical redundancy service.
com.bea.wlcp.wlng.account.AccountServerService | Account service.
com.bea.wlcp.wlng.statistics.StatisticsServerService | Statistics service.
com.bea.wlcp.wlng.policy.PolicyServerService | Generic Policy evaluation service. Wraps implementations of rules engines.
com.bea.wlcp.wlng.plugin.PluginManagerServerService | Plug-in manager.
com.bea.wlcp.wlng.storage.georedundant.GeoRedundantStoreServerService | Storage provider for intercepting store operations for geographically redundant stores, forwarding changes to the geo storage server service functions and reads to the local storage provider.
com.bea.wlcp.wlng.geostorage.GeoStorageServerService | Geo storage server service that has the geo storage singleton services, manages the geo-master lifecycle, performs calls remote calls to the other site, and consistency checks between sites. Also has the geo storage Mbean.
com.bea.wlcp.wlng.tier_routing.TierRoutingManagerServerService | Tier routing manager.

### Retired container services

Table 17-4 describes the retired Oracle Communications Services Gatekeeper container services. These services are deprecated and are not deployed as a part of standard Oracle Communications Services Gatekeeper installation. The services are packaged in:

- `wlng_at_bc.ear`, see Table 17-4.
- `wlng_nt_bc.ear`, see Table 17-5.

Table 17-4 Retired services, kept for backwards compatibility in $BEA_HOME/ocsg_4.1/applications/wlng_at_bc.ear
Container service | Summary
--- | ---
Access Web Service | Used by applications to establish sessions. Uses the Access service, see Table 17-5s.

Table 17-5 Retired services, kept for backwards compatibility in $BEA_HOME/ocsg_4.1/applications/wlng_nt_bc.ear
Container service | Summary
--- | ---
Access_service | Used in connection with the Access Web service exposed to applications.
Slee_alarm | Alarm service used by external CORBA alarm listeners of the type used when integrating with Network Gatekeeper 2.2 and earlier.
Slee_charging | Charging service used by external CORBA charging listeners of the type used when integrating with Network Gatekeeper 2.2 and earlier.
Slee_edr | EDR service used by external CORBA EDR listeners of the type used when integrating with Network Gatekeeper 2.2 and earlier.

### Disabling of ORB

By default, the Orbacus ORB is started when Oracle Communications Services Gatekeeper starts.

The ORB binds to the same IP as WebLogic Server binds to. This can have impact on, among other things, the IOR callbacks having `localhost` in them if WebLogic Server is configured to listen to `localhost`.

If a deployment does not use any of the CORBA features, the ORB can be disabled.

When the ORB is disabled none of the EARs that contain modules that require CORBA can be deployed. This includes the EARs that contains any of the Retired container services and also any communication service EAR that includes an OSA/Parlay-type network protocol plug-in. See the administration section for each communication service for information about which parts of the communication service EAR are related to the OSA/Parlay-type network protocol plug-ins.

To disable the ORB, do the following steps on all servers:

1. Shutdown server.
2. Edit `$Domain_home/config/custom/nt.xml`
3. Remove the line:
   <service><service-class>com.bea.wlcp.wlng.corba.ob.OrbacusServerService</service-class></service>
4. Start server.

### Patching of Container Services

Patching of container services is done using SmartUpdate, see WebLogic Server Installing Patches and Maintenance Packs at http://download.oracle.com/docs/cd/E12840_01/common/smartupdate/guide/.

Patches to container services and WebLogic Server is done using rolling upgrades, see Oracle WebLogic Server Upgrading WebLogic Application Environments at http://download.oracle.com/docs/cd/E12840_01/wls/docs103/upgrade/index.html