3 Customizing the Application Test Environment

This chapter describes how to customize the ATE using a configuration file.

About Customizing the ATE

Network operators can use a startup configuration file to create a custom version of the ATE that reflects the services and defaults that they want to expose to application developers.

For information on incorporating new custom communication services into the ATE, see the "Virtual Communication Service Module for the ATE" section in the "Extending the ATE and the PTE" chapter in Platform Developer Studio Developer's Guide. That section describes the Java classes generated for the ATE's virtual communications services.

The Startup Configuration File

To customize the ATE, create a configuration file that defines the version that you will distribute. This configuration sets the appearance of the ATE on its initial startup.

To customize the ATE:

Create a file named startup-configuration.xml.
Save this file in the product installation directory of the ATE.

If a startup-configuration.xml file exists in the product installation directory of the ATE, the ATE takes on the appearance and behavior configured by the elements in this file. Elements not included in this configuration file retain their default appearance and behavior.

If no startup-configuration.xml file exists in the product installation directory directory, the entire default configuration is used.

You can use a different filename for startup-configuration.xml by overriding the oracle.ocsg.pte.startup.config system property.

Example Startup Configuration File

The following is a sample startup-configuration.xml file that you can use as a basis for creating your own. The rest of this chapter explains the various elements in detail.

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="http://www.oracle.com/ns/ocsg/50/at">
 
  <general>
    <title>A new title for the ATE</title>
    <version>7.0</version>
    <copyright>(c) 2010 My Company</copyright>
    <icon>anewicon.gif</icon>
  </general>
 
  <account visible="true">
    <users>
      <user name="domain_user" password="domain_user"/>
      <user name="bob" password="foo"/>
    </users>
  </account>
 
  <sla visible="true">
    <enforcements enabled="true">
      <value path="sendMessage.subject" operation="contains" value="world"/>
      <value path="sendMessage.charging.currency" operation="does_not_contain" value="euro"/>
      <request name="sendSms" count="5" timeAmount="10" timeUnit="seconds"/>
    </enforcements>
  </sla>
 
  <payment visible="false"/>
 
  <vcs>
    <mbeans>
      <mbean name="px21_tl" attribute="MaximumCount" value="7"/>
    </mbeans>
    <visible>
      <module className="oracle.ocsg.pte.impl.vcs.sessionmanager.SessionManagerModule" title="Session Manager"/>
      <module className="oracle.ocsg.pte.impl.vcs.px21_sms.SmsModule" title="Short Messaging"/>
      <module className="oracle.ocsg.pte.impl.vcs.px21_tl.TerminalLocationModule" title="Terminal Location"/>
    </visible>
  </vcs>
 
</config>

Order of Configuration Elements

The top-level configuration elements must appear in the order in which they appear in the example.

The order is:

<general>
<account>
<sla>
<payment>
<vcs>

When Configuration Elements Are Read

The ATE reads most configuration elements when the ATE starts.

Exceptions are the data elements: <users> inside the <account> element and <enforcements>, inside the <sla> element. The ATE reads <users> and <enforcements> only on installation of the ATE.

To circumvent this restriction to change the data elements without reinstalling the ATE:

Stop the ATE.
Delete the sdk_home_dir/product_installation_dir/runtime/pte.dat file.
Edit the startup-configuration.xml file with your changes.
Save the file.
Start the ATE.

Customizing General Characteristics

You can change the following general characteristics of the ATE in the <general> element in the startup-configuration.xml file.

title
version
copyright
icon

The title, version, and icon appear in the ATE title bar and in the About window accessed from the ATE´s Help menu item.

The copyright appears in the About window.

To customize general characteristics of the ATE:

Create a <general> element in the startup-configuration.xml file, or use an existing <general> element.
Do any or all of the following:
- To change the title of the ATE, create a <title> element inside the <general> element and enter your title for the ATE between the <title> element's delimiters.
- To change the version of the ATE, create a <version> element inside the <general> element and enter your version string between the <version> element's delimiters.
- To change the copyright of the ATE, create a <copyright> element inside the <general> element and enter your copyright string between the <copyright> element's delimiters.
- To change the icon of the ATE, create an <icon> element inside the <general> element and enter the name of the icon image file between the <icon> element's delimiters.
  
  Store the icon image in the ATE root directory, which is the same directory that contains the startup-configuration.xml file.
Save the file.

Any elements that you do not specify remain unchanged from the default ATE.

The following is a sample <general> element.

<general>
    <title>A new title for the ATE</title>
    <version>7.0</version>
    <copyright>(c) 2010 My Company</copyright>
    <icon>anewicon.gif</icon>
  </general>

Customizing a VCS

You can customize a VCS in the following ways:

Show or hide a VCS module.
Change the title that appears on a VCS´s tab in the VCS panel.
Set your own defaults for the VCS MBean attribute values.

You configure these customizations in the <vcs> element in the startup-configuration.xml file.

Showing/Hiding a VCS Module

By default, all VCSs are invisible in the ATE.

To show a VCS module:

Create a <vcs> element in the startup-configuration.xml file, or use an existing <vcs> element.
Create a <visible> element inside the <vcs> element, or use an existing <visible> element.

For each VSC module that you want to show, insert a <module> element inside the <visible> element.

Each <module> element has an attribute for:

The class name of the VCS in the className attribute
The title that you want to appear on the VCS´s tab in the title attribute

Table 3-1 lists the class names of the VCS modules. These are the valid values for the className attribute.

Table 3-1 VCS Class Names

VCS	Class Name
Session Manager	oracle.ocsg.pte.impl.vcs.sessionmanager.SessionManagerModule
Short Messaging	oracle.ocsg.pte.impl.vcs.px21_sms.SmsModule
Multimedia Messaging	oracle.ocsg.pte.impl.vcs.px21_mms.MmsModule
Terminal Location	oracle.ocsg.pte.impl.vcs.px21_tl.TerminalLocationModule
Terminal Status	oracle.ocsg.pte.impl.vcs.px21_ts.TerminalStatusModule
Payment	oracle.ocsg.pte.impl.vcs.px30_payment.ParlayX30PaymentModule
Third Party Call	oracle.ocsg.pte.impl.vcs.px21_tpc.ThirdPartyCallModule
Binary Sms	oracle.ocsg.pte.impl.vcs.binarysms.BinarySmsModule
Example	oracle.ocsg.pte.example.vcs.ExampleModule

Save the file.

Any VCS that you do not specify in the <visible> element remains hidden.

To hide a VCS module, delete its <module> element.

The following <vcs> element example shows the Session Manager, Short Messaging, and Terminal Location VCSs in the ATE. All the other VCSs remain hidden.

<vcs>
    <visible>
       <module    className="oracle.ocsg.pte.impl.vcs.sessionmanager.SessionManagerModule" title="Session Manager"/>
       <module className="oracle.ocsg.pte.impl.vcs.px21_sms.SmsModule" title="Short Messaging"/>
       <module className="oracle.ocsg.pte.impl.vcs.px21_tl.TerminalLocationModule" title="Terminal Location"/>
    </visible>
</vcs>

The <visible> elements are applied each time the ATE starts up.

Changing a VCS Title

You can display a different title on a VCS tab by changing the title attribute of the <module> element inside the <visible> element.

To change the title of a VCS tab, specify a different value for the title attribute of the VCS module that you want to change inside the <module> element. See step 3 in Showing/Hiding a VCS Module.

The following example sets the title on the Short Messaging VCS tab to SMS.

<vcs>
    <visible>
      <module className="oracle.ocsg.pte.impl.vcs.px21_sms.VCSSmsModule" title="SMS"/>
    </visible>
  </vcs>

Reconfiguring the Default VCS MBean Attributes

The MBean attributes that are settable in the VCS are configured with default values when the ATE starts. You can change these default values in your custom configuration.

To reconfigure a default VCS MBean attribute:

Create a <vcs> element in the startup-configuration.xml file, or use an existing <vcs> element.
Create an <mbeans> element inside the <vcs> element, or use an existing <mbeans> element.
For every attribute for which you want to change the default value, insert an <mbean> element inside the <mbeans> element.

Each <mbean> element has
- A name attribute for the MBean name of the VCS.
- An attribute attribute for the VCS attribute.
- A value attribute for the default value.
Table 3-2 lists the valid MBean name values for the name attribute for VCS modules that support configurable attributes.

Table 3-2 VCS MBean Names

VCS MBean Name

Terminal Location

px21_tl

Terminal Status

px21_ts

Payment

px30_payment

Third Party Call

px21_tpc

Valid values for the attribute attribute are the names displayed in the Configuration tab of the VCS in the ATE. Some VCSs do not have any configurable attributes.
Save the file.

VCS	MBean Name
Terminal Location	px21_tl
Terminal Status	px21_ts
Payment	px30_payment
Third Party Call	px21_tpc

Attributes that you do not specify in an <mbean> element retain their default values.

The application developer can modify these defaults from the Configuration tab of a visible VCS for the duration of an ATE session, but those changes do not persist. The next time the ATE starts up, the default values configured in the startup-configuration.xml file are used.

The following example sets the default value for the Terminal Location VCS´s MaximumCount attribute to 7 and the default value for the Terminal Status VCS´s NotificationFrequency attribute to 8.

<mbeans>
      <mbean name="px21_tl" attribute="MaximumCount" value="7"/>
      <mbean name="px21_ts" attribute="NotificationFrequency" value="8"/>
    </mbeans>

Customizing the Account Manager

The ATE is configured with a default account that applications use to access the VCS. The credentials for this account are:

User Name=domain_user
Password=domain_user

The user name and password are included in the SOAP header or HTTP basic authentication credentials in the application's requests.

Showing and Hiding the Account Manager

By default, the default account is visible in the Account Manager when the ATE starts.

You can configure whether the Account Manager panel should be displayed or hidden.

To show or hide the Account Manager panel:

Create an <account> element in the startup-configuration.xml file, or use an existing <account> element.
Do one of the following:
- To hide the Account Manager panel, set the <account> element's visible attribute to false.
- To show the Account Manager panel, set the <account> element's visible attribute to true.
Save the file.

Creating Accounts

You can create additional accounts for applications to use as credentials for requests sent to a VCS.

To create an account:

Create an <account> element in the startup-configuration.xml file, or use an existing <account> element.
Create a <users> element inside the <account> element, or use an existing <users> element.
For every account that you want to create, insert a <user> element inside the <users> element.

Each <user> element has a name attribute for the user name and a password attribute for the password.
Save the startup-configuration.xml file.

The following example creates two application accounts and hides the Account Manager panel. Applications can send requests using either set of credentials.

<account visible="false">
    <users>
      <user name="dev1" password="plm9zaq"/>
      <user name="dev2" password="cde4rfv"/>
    </users>
  </account>

Accounts are read when the ATE is installed. See When Configuration Elements Are Read for more information.

Customizing the SLA Manager

You can customize the following characteristics of the VCS's SLA Manager:

Show or hide the SLA Manager
Provide default value enforcements
Provide default rate enforcements

By default, the SLA Manager panel is visible when the ATE starts.

Showing and Hiding the SLA Manager

To show or hide the SLA Manager panel:

Create an <sla> element in the startup-configuration.xml file, or use an existing <sla> element.
Do one of the following:.
- To hide the SLA Manager panel, set the <sla> element's visible attribute to false
- To show the SLA Manager panel, set the <sla> element's <visible> attribute to true.
Save the file.

Creating Policy Enforcements

You can provide policy enforcements in the ATE to test how applications handle policy restrictions. These restrictions would be enforced by actual service-level agreements when the application is deployed.

To create policy enforcements:

Create an <sla> element in the startup-configuration.xml file, or use an existing <sla> element.
Create an <enforcements> element inside the <sla> element, or use an existing <enforcements> element.
Do one of the following:
- To enable all enforcements, set the enabled attribute of the <enforcements> element to true.
- To disable all enforcements, set the enabled attribute of the <enforcements> element to false.
You cannot enable or disable individual enforcements.
For every value enforcement, create a <value> element inside the <enforcements> element.

Set the path, operation, and value attributes of the <value> element to define the value enforcement. See Managing Value Enforcements for more information about these attributes.
For every rate enforcement, create a <request> element inside the <enforcements> element.

Set the name, count, timeAmount, and timeUnit attributes of the <request> element to define the rate enforcement. See Managing Rate Enforcements for more information about these attributes.
Save the file.

The following example creates two value enforcements and one rate enforcement, enables those enforcements, and shows the SLA Manager in the ATE.

<sla visible="true">
    <enforcements enabled="true">
      <value path="sendMessage.subject" operation="contains" value="world"/>
      <value path="sendMessage.charging.currency" operation="does_not_contain" value="euro"/>
      <request name="sendSms" count="5" timeAmount="10" timeUnit="seconds"/>
    </enforcements>
  </sla>

When the SLA Manager panel is visible, the application developer can create additional value and rate enforcements that apply for the duration of the session. The developer can also modify or delete the enforcements that are currently configured. Any modifications the application developer makes are applicable only for the duration of the SDK session. Only those enforcements configured in the startup-configuration.xml file are persistent when the ATE is restarted.

Enforcements are read when the ATE is installed. See When Configuration Elements Are Read for more information.

Showing And Hiding Payment Accounts Panels

You can configure whether the Payment Account and Payment Account Detail panels should be displayed or hidden.

These panels are treated as a unit, which means that you must hide both panels or show both panels.

To show or hide the Payment Account and Payment Account Detail panels:

Create a <payment> element in the startup-configuration.xml file, or use an existing <payment> element.
Do one of the following:.
- To hide the Payment Account and Payment Account Detail panels, set the <payment> element's visible attribute to false.
- To show the Payment Account and Payment Account Detail panels, set the <payment> element's visible attribute to true.