Developer's Guide for Parlay X

Get
Adobe Reader

Introduction and Overall Workflow

The following sections provide an overview of developing using the Parly X APIs:

About WebLogic Network Gatekeeper Web Services applications

WebLogic Network Gatekeeper Web Services applications are services offering their users access to telecom functionality. The applications can access the telecom functionality through two different Web services APIs. Which API to use depends on the application's needs for network functionality and means of access.

For applications that will provide standardized basic telecom functionality, it is recommended to use the Parlay X APIs.

For applications with a need for more granular control, the Extended Web Services interfaces can be used.

This guide describes how to develop Parlay X applications that connects to the WebLogic Network Gatekeeper. WebLogic Network Gatekeeper acts as aParlay X gateway to the underlying telecom network.

Using the Parlay X APIs you can quickly develop powerful telecom-enabled applications using any programming environment supporting Web Services.

Architecture

Figure 2-2, Parlay X and JS2SE applications, on page 2-4 illustrates different ways of using the Web Services APIs as provided by the WebLogic Network Gatekeeper, as well as examples of different execution environments for applications.

get_started.html

There are two flavours of Web Services; XML-based RPC and WS-I.

get_started.html

Web services applications

Web services applications executes in an environment capable of handling Web Services.

The Web Services applications communicates with the WebLogic Network Gatekeeper using SOAP/HTTP.

Parlay X based applications

A Web Services Parlay X application

uses an API that is standardized.
has a well-defined, small set of methods available.
is stateless.

Development environment

Below is a description of an example development environment. Integrated programming environments, like Visual Studio .Net can be used for development of Web Services applications, but this guide uses a minimalistic approach. For the purpose of this guide, the following will do:

an ordinary text editor.
Java 2 SDK 1.4.2, see J2SE SDK, http://java.sun.com.
Axis 1.1, see Apache Axis, http://ws.apache.org/axis.
JavaMail API 1.2, see JavaMail, http://java.sun.com, for messaging applications handling multimedia messages.

The following files, from the Axis distribution, are used:

axis.jar
axis-ant.jar
commons-discovery.jar
commons-logging.jar
jaxrpc.jar
saaj.jar
wsdl4j.jar

The following JavaMail files are used:

mail.jar
activation.jar

Information exchange with the service provider

Before an application is developed, the application developer and the service provider must exchange information regarding resources.

The first step for the application developer is to define which resources to use, call, messaging, location, status, payment etc. and to map these requirements to an APIs that corresponds to these resources.

The next step is to exchange the information according to .

Table 2-1 Information exchange between Parlay X application developer and WebLogic Network Gatekeeper operator

Module	API	Information to be provided by the
Module	API	Application developer	WebLogic Network Gatekeeper Operator
Access	Access		Application ID. Service provider ID. Application Instance Group ID. Password for the Application Instance Group.
Network-Initiated Third Party Call	Call	URL of the end-point. If the application always shall be triggered when the calling party goes off-hook..	Access number to the application, if any. Can be a range of numbers.
SMS	Send SMS		Mailbox ID and corresponding password.
	SMS Notification	URL of the end-point.	Access number to the application. Mailbox ID and corresponding password.
	Receive SMS		Mailbox ID and corresponding password.
Multimedia Message	Send Message		Mailbox ID and corresponding password.
	Receive Message		Mailbox ID and corresponding password.
	Message Notification	URL of the end-point.	Access number to the application. Mailbox ID and corresponding password.

WebLogic Network Gatekeeper operator must also communicate which services and methods that are supported by the deployment.

In addition to this information, other information related to commercial, security, and privacy regulations must also be exchanged. Examples includes:

Charging plans to use
Number of concurrent application instances.
Amount of usage of the different resources, for example allowed number of send SMS requests.
Black/white listed addresses.
Allow/deny lists for user status and user location requests.

Overall development workflows

Below you find overall workflows for development of Web Services applications based on Parlay X.

Two main scenarios are identified:

WebLogic Network Gatekeeper acts as a server and the application is the client. In this scenario, the application uses a Web Service provided by WebLogic Network Gatekeeper.
the application acts as a server and WebLogic Network Gatekeeper is the client. In this scenario, the application in itself is the provider of a Web Service and WebLogic Network Gatekeeper invokes methods on this Web Service.

Often, an application acts as both server and client.

get_started.html

In Parlay X, all methods starting with "handle" or "notify", for example "handleBusy" are methods that WebLogic Network Gatekeeper invokes on the application's server-part. The application's server side implements the interface.

The method invocations are SOAP requests over HTTP, which means that the server part of the application must be capable of handling SOAP requests.

When using Axis, the Simple Axis Server can be used as a SOAP engine during test. In a production system can, for example, Axis in combination with Tomcat be used.

Client-side Web Services using XML based RPC

Below is an overall work sequence for developing telecom enabled Web Services using XML-based RPC:

Make sure to retrieve the necessary IDs for the resources the application will use from the service provider. Examples are mailbox IDs, short numbers for network triggered applications and so on.

Retrieve the WSDL file that handles user login.

Retrieve WSDL files for the telecom services to use.

Generate stubs/proxy classes for the language to implement the application in. Use a tool that converts the WSDL into stubs for the preferred language. Examples of such tools are WSDL2Java and Soap Toolkit.

Compile and create Jar-files from the Java stubs.

Use the generated APIs to add telecom functionality to the application.

Compile the application.

Test the application in a test environment, for example the Application Test Environment.

Connect the application to WebLogic Network Gatekeeper with a connection to a live telecom network.

Server-side Web Services using XML based RPC

Below is an overall work sequence for developing telecom enabled Web Services using XML-based RPC:

Make sure to retrieve the necessary IDs for the resources the application will use from the service provider. Examples are mailbox IDs, short numbers for network triggered applications and so on.

Retrieve WSDL files for the telecom services to use.

Generate skeleton classes for the language to implement the application in. Use a tool that converts the WSDL into stubs for the preferred language. Examples of such tools are WSDL2Java and Soap Toolkit.

Compile and create Jar-files from the Java stubs.

Implement the generated interfaces and add telecom functionality to the application.

Adapt the generated WSDD file to bind the SOAP requests to the appropriate class.

Compile the application.

Deploy the application in an environment capable of decoding HTTP/SOAP messages. Examples of such environments includes Axis.

Communicate the end-point of the new application to the service provider.

Test the application in a test environment, for example the Application Test Environment.

Connect the application to WebLogic Network Gatekeeper with a connection to a live telecom network.

Example: Server-side Web Service

The example below shows how to define a web service that takes care of notifications on new SMS:es from to the applications' server side. The web service is the SMS notification API, containing the method notifySmsReception().

The Simple Axis Server is used as deployment environment for the application.

Below is an outline on the procedure:

Generate Java skeletons from the WSDL files:

%java org.apache.axis.wsdl.WSDL2Java --server-side 
--skeletonDeploy true parlayx_sms_notification_service.wsdl

Note: The Axis files must be in the classpath.

Compile and create Jar-files from the skeletons.

Move the empty implementation of the generated interfaces to the source directory of the application.

In the example, the class is named SmsNotificationBindingImpl.. When generating skeletons using WSDL2Java, the empty interface implementations are named <Name of API>BindingImpl.

Adapt the generated Web Service Deployment Descriptor (WSDD) files to bind the SOAP request to the appropriate class.

The WSDD files are used when deploying and undeploying services. Two files are generated: deploy.wsdd and undeploy.wsdd.
In the example, the tag
<parameter name="className" value="org.csapi.www.wsdl.parlayx.sms.v1_0.notification.SmsNotificationBindingSkeleton"/>
is replaced with
<parameter name="className" value="com.acme.apps.getSmsApp.SmsNotification"/>
in order to bind to the appropriate class.

Compile the application.

Verify that the application is deployed correctly by using a Web browser and point it to the URL of the web service. In the case of Simple Axis Server, the deployed Web Services can be found at the URL http://<host>:<port>/axis/services

Provide the service provider with the URL to the Web Service, and the data about the application; application ID and application instance group ID.

Run the application. The adapted file deploy.wsdd is used when instantiating the Simple Axis Server.

Testing an application

Figure 2-4, Application test flow, on page 2-13 shows the application test flow, from the application developers' functional test to deployment in a live network. An application developer can perform functional tests using ATE. The other tests in the flow are performed in cooperation between the application provider and the service provider.

get_started.html

When an application shall be tested using the ATE, the application is connected to ATE, which emulates the WebLogic Network Gatekeeper. Before testing in a test telephony network, a network simulator can be used.

An overview of the relation between ATE and WebLogic Network Gatekeeper is shown in Figure 2-5, ATE in relation to WebLogic Network Gatekeeper, on page 2-14.

get_started.html

For a applications based on Web Services, the applications uses the endpoints provided by ATE during test. After successful verification, the application uses endpoints provided by WebLogic Network Gatekeeper.