Developer's Guide for Extended Web Services
 |
 |
 |
|
 |
Get Adobe Reader |
Using the Extended Web Services
The following sections describe how to use the Extended Web Services APIs:
- About the Extended Web Services APIs
- WSDL files
- Workflow
- Access
- Messaging
- Charging
- Call
- Subscriber profile
- User interaction
- User location
- User status
- Exception handling
About the Extended Web Services APIs
The Extended Web Services interface offers a high-level abstraction of OSA/Parlay for use in a web services environment. It offers a more granular control over resources in the telecom network than Parlay X, and yet it provides the same low degree of complexity.
The API is designed for rapid application development. From an architectural point of view, the implementation of the API resides on top of the service capabilitiy modules in WebLogic Network Gatekeeper.
All applications accessing WebLogic Network Gatekeeper through the Web Services interfaces uses a Kerberos type of service token-based authentication. The application is provided with a user name (the application instance group ID) and a password. When an application wants access to WebLogic Network Gatekeeper the application instance logs in using the user name and password together with the application account ID and service provider ID to retrieve a service token. This mechanism may be extended, as an option using, for example Passport or other extended Kerberos Key Distribution Centre (KDC) authentication solutions. This is according to the WSSE (Web Services Security) standard.
To run an Extended Web Services application, access to either WebLogic Network Gatekeeper or Weblogic Network Gatekeeper Application Test Environment is needed, together with a set of WSDL files defining the API, login credentials and IDs of resources to use. These are provided by the service provider.
The interfaces are separated in different modules. Each main component is contained in a specific module. The modules are:
For detailed information on individual methods, see API Description Extended Web Services for WebLogic Network Gatekeeper.
WSDL files
WebLogic Network Gatekeeper supports Extended Web Services interfaces using the SOAP encoding (RPC encoding) approach.
By default, the WSDL files can be fetched from:
- http://<URL to WebLogic Network Gatekeeper>/wespa/services (The Web Services, also the endpoints)
- The WSDL files for the northbound (Listener) interfaces can be fetched from
http://<URL to WebLogic Network Gatekeeper>/wespa/wsdl (definitions of the listener interfaces)
For a description of the methods in each API, see API Description Extended Web Services for WebLogic Network Gatekeeper.
Workflow
The main program control flow when executing applications based on the Extended Web Services interfaces is described in pseudo code in Figure 3-1, Application execution workflow, on page 3-6.
Login and retrieve login ticket
To use any Web Service provided by WebLogic Network Gatekeeper a login ticket is needed. A login is needed to retrieve the ticket. The login ticket identifies the login session. This ticket is valid until a logout is performed. The ticket is sent in each consecutive method invocation to identify the originator of the invoker.
Details about locators, endpoints, so on are explained later in this section
AccessService accessService = new AccessServiceLocator();
java.net.URL endpoint = new java.net.URL(wsdlUrl);
Access access = accessService.getAccess(endpoint);
String loginTicket = access.applicationLogin(spID,
appID,
appInstGroupID,
appInstGroupPassword);
The login ticket ID retrieved when invoking applicationLogin is used in each consecutive invocation towards WebLogic Network Gatekeeper. See Define the security header.
The login credentials; spID, appID, appInstGroupId, and appinstGoupPassword are provided by the service provider.
Define the security header
The login ticket ID, as retrieved when logging in, is sent in the SOAP header together with a username/password combination for each invocation of a web service method.
Listing 3-2 Define the security header
org.apache.axis.message.SOAPHeaderElement header =
new org.apache.axis.message.SOAPHeaderElement(wsdlUrl, "Security", "");
header.setActor("wsse:PasswordToken");
header.addAttribute(wsdlUrl, "Username", ""+userName);
header.addAttribute(wsdlUrl, "Password", ""+sessionId);
header.setMustUnderstand(true);
The login ticket is supplied in the Password attribute. The userName attribute is defined by the service provider, normally in the format
<myUserName>@<myapplication>.
Axis 1.1 does not contain WSSE helper classes, so this is performed manually.
The header is defined upon the object representing the Web Service port to use. Also see Add security header.
Get hold of a Port
Below is the code for getting hold of a port. The example is using the Messaging interface.
Listing 3-3 Get hold of a port
MessagingService messagingService = new MessagingServiceLocator();
java.net.URL endpoint = new java.net.URL(messagingWsdlUrl);
messaging = messagingService.getMessaging(endpoint);
The details on the parameters of the messaging API are described in API Description Extended Web Services for WebLogic Network Gatekeeper.
Add security header
Adding the security header to a request is straightforward, as illustrated below. For information on how create the header, see Define the security header.
Listing 3-4 Add security header
((org.apache.axis.client.Stub)sendSms).setHeader(header);
Invoke a method
Below it is illustrated how to get hold of a port. The example is using the Send SMS API.
String mailboxTicket = messaging.openMailbox(myMailbox,
myMailboxPwd,
spID+appID+appInstGroupID);
The details on the parameters of the send SMS API are described in API Description Extended Web Services for WebLogic Network Gatekeeper.
Logout
The logout destroys the login ticket.
access.applicationLogout(sessionId);
The login Ticket is destroyed and cannot be used in consecutive method invocations.
Access
The following functionality is provided:
- Login an application to WebLogic Network Gatekeeper.
- Logout an application from WebLogic Network Gatekeeper.
- Change password.
For a description on how to use this API, see Login and retrieve login ticket and Logout. There is also support for changing the password.
Messaging
The messaging service capability makes it possible for an application to send, store, and receive SMSes and Multi Media (MMS) messages. In addition, the service supports send lists, smart messaging, EMS, and distribution of ring tones and logos. The send list feature allows for send list distribution of messages.
An administrator creates mailboxes with INBOX and OUTBOX folders for each subscriber or application. A mailbox structure is given in Figure 3-2.
An application is notified when a sent message has been successfully delivered to a recipient and when the service receives a message in an INBOX related to the application. Old messages are automatically removed from the mailboxes. The cleanup interval and age of messages to be deleted are configurable.
Charging
The charging service capability makes it possible for an application to charge a subscriber based on the content (content based charging) of a used service, for example a music video, rather than based on the amount or time used. Reservation/payment in parts and immediate charging are supported.
In immediate charging the amount is withdrawn from the subscriber's account at the same time the service is ordered.
To make sure the subscriber does not have to pay for a service not delivered, reservation/payment in parts can be used. In this case, the charging service reserves the whole or a part of the amount in the subscriber's account. The amount is not withdrawn until it has been verified that the subscriber has received the whole or a defined part of the service paid for. Reservation/payment in parts can also be used by an application before delivering a service to make sure that the amount to be charged is available on the subscriber's account.
The charging service also supports adding money to subscriber accounts.
Call
The call service capability provides applications with functions for call routing, call management, and call leg management. More than two call legs can be connected to a call simultaneously.
Two main usage scenarios for call control are identified; application initiated and network triggered calls.
Network triggered calls
Network triggered call is used for applications where call set up is triggered from the network, see Figure 3-3, Example of a network triggered call, on page 3-11.
The service contains functions that makes it possible for an application to provide:
- advice of charge
- call specific charging
- call re-routing
- user interaction through announcements and voice prompts
Application initiated calls
Typical usage for application initiated calls are voice chat applications and different types of click-to-call functionality in web and office applications. Figure 3-4, Example of an application initiated call, on page 3-12 shows an example where a call is set up using a web based address book application.
In addition, a call between two or more persons can be set up through an application interface. During the call it is possible to add and remove participants through the interface. Also, notifications when individual participants answers and hangs up can be presented.
Subscriber profile
The subscriber profile service makes it possible for an application to obtain and manage application subscriber profiles. A subscriber profile consists of data related to a subscriber and the subscriber's telephony terminal, see Table 3-2 on page 13. The data marked as read-only in the table can only be updated by the operator.
Table 3-2 Subscriber Profile Data
User interaction
The user interaction service makes it possible for an application to interact with call participant(s) during a call or with messaging users during a messaging session. The application communicates with call participant(s) through announcements or messages and with messaging users through text messages.
Call user interaction
The call participant(s) communicate through speech or tone sending. That is, both speech recognition and DTMF (using the terminal's key set (0-9, *, #)) can be used. Announcements can be purely informative or they can prompt a participant to reply through speech or sending DTMF tones back to the application.
Message based user interaction
With message based user interaction, the application and the end users communicate through text messages (SMSes or USSD messages).
SMS based user interaction provides application initiated SMSes with a transaction ID to connect requesting/prompting SMSes with end user's replies.
USSD messages from an application can be purely informative or they can prompt the end user to reply. USSD messages can also be used by the end user to initiate service sessions with applications. When initiating service sessions or replying to an application generated USSD message, the end user can only use the terminal's key set (0-9, *, #). The application can use any type of character supported by the end user's terminal.
User location
The user location service capability makes it possible for an application to obtain the geographical location of telephony terminals. The service supports:
Both single and periodic requests supports multiple destination addresses in one request.
The location can be specified as a base point (longitude, latitude) or as a descriptive (abstracted) position. An abstracted position describes the user's location in terms of:
Use of abstracted location information requires interaction with a geographic information system.
Using longitude and latitude, the location is specified as a base point (longitude, latitude) and a geometrical area in which the telephony terminal is located. The geometrical area is referred to as an uncertainty shape related to the base point. The uncertainty shapes are divided in to circles and ellipses.
When supported in the network, extended location, the altitude, terminal type, and a time stamp are also provided.
Also, the service supports provision of geographical information for a terminal, such as city or street address, to applications.
Exactly what is available to the requesting applications is dependant on the underlying networks.
Circle uncertainty shapes
The circle uncertainty shapes are:
The circle sector is an extended case of the circle, and the circle arc is a extended case of the circle sector, see Figure 3-5, Circle uncertainty shape definitions, on page 3-16.
Ellipse uncertainty shapes
The ellipse uncertainty shapes are:
The ellipse sector is an extended case of the ellipse, and the ellipse arc is a extended case of the ellipse sector, see Figure 3-6, Ellipse uncertainty shape definitions, on page 3-17.
Terminal altitude
If the terminal's altitude is provided, the actual terminal altitude is somewhere within a span defined by the provided altitude value and two times the altitude uncertainty, see Figure 3-7, Terminal altitude definition, on page 3-18.
A positive altitude value means above sea level, whereas a negative value means below sea level.
User status
The user status service capability makes it possible for an application to obtain the status of fixed, mobile and IP-based telephony terminals. Possible values are:
The service supports single, periodic and triggered status request and as well as multiple destination addresses in one request.
Exception handling
Currently, there are three different types of exceptions, as described below.
Service-specific exceptions
Service-specific exceptions, one or more for each service.
AccessException
Access exceptions, which are thrown when something is wrong with the data related to an operation. For instance, a user tries to retrieve a manager for a service that he or she is not allowed to use.
CommunicationException
Communication exceptions, which are thrown when a disturbance occurs in the network between the application and WebLogic Network Gatekeeper, or WebLogic Network Gatekeeper has lost some objects related the session.
