| Oracle® Communications Converged Application Server Concepts Release 5.1 Part Number E27705-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Converged Application Server Concepts Release 5.1 Part Number E27705-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the environment for developing applications with Oracle Communications Converged Application Server.
Oracle Communications Converged Application Server is a development and runtime platform for implementing and deploying communication services. The Converged Application Server supports capabilities that form the basis for advanced communication services, including those represented by Rich Communication Services (RCS) and VoLTE. The Converged Application Server simplifies the development of converged applications that provide voice, IM, rich media, and presence services to end users.
In addition to a comprehensive runtime environment for services, Converged Application Server provides a development environment, the Service Creation Environment (SCE), that eases the task of creating converged applications.
The Service Foundation Toolkit (SFT) is a converged application Java development framework. It provides APIs that abstract the details of the communication protocol for your application, enabling you to focus on the service value provided by your converged SIP and HTTP applications.
The SFT provides APIs that your applications can use to interact with the components that enable rich services in an IMS environment, such as media, presence, and charging servers.
The Converged Application Server provides comprehensive support for the SIP protocol. The SIP protocol, specified by JSR 289: SIP Servlet API, extends the basic concept of the Servlet. The SIP Servlet API specification describes not only the programming API but also the Servlet container function. The container is the Server (software) that hosts or “contains” applications written using the API. The SIP Servlet container hosts SIP applications.
The Converged Application Server SIP container performs a number of SIP functions as specified by various RFCs, thus taking the burden off of the applications themselves. At the same time, the container exposes the application to SIP protocol messages through the SIP Servlet API. In this way, the application can perform various actions based on the SIP messages it receives from the container. Different applications can be coded and deployed to the container in order to provide various telecommunication or multimedia services.
The Converged Application Server Service Creation Environment (SCE) consists of a faceted framework that supplements the Oracle Enterprise Pack for Eclipse (OEPE). The SCE provides tools and resources you can use to develop converged applications, including wizards, simulators, and templates.
The SCE software is distributed alongside the Converged Application Server, and can be installed in OEPE from the Converged Application Server home directory.
The SCE adds a project type to the Eclipse environment, the Converged Application Project. For a project, you can use either the base converged application configuration or the Diameter project configuration, if you need to develop applications capable of interacting with external Diameter nodes.
After creating the project, you can take advantage of the SCE tools, which include:
SIP Servlet wizard
SIP Client wizard
SIP Servlet Templates
CommunicationBean (SFT) wizard
HSS authentication and Diameter charging simulators
SIPp integration interface
The code generation tools eliminate many of the hand-coding tasks required for converged application development. The CommunicationBean wizard, for example, lets you add SFT event listeners and annotations using GUI controls.
Figure 2-1 shows the Service Creation Environment simulators page in OEPE.
The SIP Servlet API enables applications to perform a complete set of SIP Signaling functions. The SIP Protocol specification defines different types of high level SIP roles, namely User Agents (UAs) which include UA Clients, UA Servers, and Back to back user agents (B2BUAs). The SIP protocol also defines the roles of Proxies, Registrars, and Redirect Servers. The SIP Servlet API is a allows any of these roles to be coded as SIP Servlet application.
SIP is an extensible protocol, which is one of its strengths. Applications can extend the base protocol to add new features as necessary. In fact, there are a number of RFCs that define extensions to the base IETF RFC 326 SIP: Session Initiation Protocol. The SIP Servlet API is also designed to allow developers to easily extend functionality. This is accomplished by dividing up the SIP processing between the container functions the applications. Most of the base protocol processing is performed by the container, leaving some of the higher level tasks for the applications to perform. This clever division is what lends a great deal of power and flexibility to the SIP Servlet API.
The SIP Servlet container handles "non-application-specific" complexity outside of the application code itself. Concerns like network connectivity, protocol transactions, dialog management and route processing are required by virtually all applications, and it would be enormously wasteful and error-prone to require each application to implement this support. With the SIP Servlet API, all of these tasks are managed by the container, leaving applications to provide higher level functions.
As an example, consider a SIP Proxy component:
A SIP Servlet within the SIP Servlet container receives a SIP request object and proxies it. A SIP Proxy must add its own Via header to the request; the header is required by the base SIP protocol to indicate which entities were traversed by the request. The Via header also stores the branch identifier which acts as the transaction identifier.
Because the maintenance of transactions and their associated state machine is maintained by the container, it is the container that actually inserts the Via headers into the SIP Request.
The downstream SIP entity which next receives the request sends the response back along the path built up by the SIP entities in the path of the request that have inserted themselves into the Via or Record-Route headers.
The container gets the response, removes the Via header it inserted in the original request and then processes the response. The application code does not need to manage the Via header, which simplifies application development.
There are many cases in which the SIP Servlet container handles this sort of mundane, but essential, protocol detail.
The SIP Servlet API specification is closely aligned with the Java EE specifications, and it is expected that containers that host SIP Servlet applications also make Java EE features available to developers. The most notable of these features is the HTTP Servlet container. There are many use cases in which a converged application, using both SIP and HTTP functions, is required, from conferencing and click-to-call applications to Presence and User Agent Configuration Management applications. Converged applications can also combine other protocols such as Diameter to perform advanced functions such as modifying subscriber profile data.
Figure 2-2 illustrates that javax.servlet.http and javax.servlet.sip converge in the SIP Servlet API.
The SIP Servlet API enables multiple applications to execute on the same request or response, independently of one another. This is another very powerful feature of the SIP Servlet API. The promise is that application developers are able to write applications providing features that are independent of each other, but can be deployed to the same host SIP Servlet container. The applications can be “composed” (or sequenced) to provide a service on a call. This composition is facilitated by the container. See Appendix A, "SIP Servlet API Service Invocation," for more information.
Application data stored in container-managed session objects can benefit from replication and failover. Almost all applications that perform some useful functions require some state between different Requests and Responses. Some state information is mandated by the SIP protocol itself, such as the transaction state machine with its Server and Client Transactions, and the Dialog state machine.
The container also has a notion of message context which encapsulates the SIP level state, and the concept of Sessions, which are the SIP Servlet API constructs. Applications can save their own state in the Session objects maintained by the container. A carrier-grade container will replicate this state such that the call becomes fault tolerant of a container instance, as is done in Converged Application Server.
Figure 2-3 shows the logical layers of a Converged Application Server SIP Servlet Container. The five layers shown from the bottom are what are known as the SIP stack, the functionality of which is defined in RFC 3261 and the associated RFCs that extend the base protocol.
SIP, being a transaction-based protocol, has a well-defined transaction layer. SIP requests are always followed by one or more provisional Responses and one final response, with the exception of the ACK which has no response. The transaction machinery is designed to keep track of the provisional and final responses.
Figure 2-3 shows the message processing layers in the Converged Application Server SIP Servlet container which are the following from top to bottom: Dialog Management Layer, Transaction Layer, Message Parser, the Transport Layer, and the bottom layer comprising of TCP, UDP, and TLS.
A dialog is a point-to-point session between two SIP endpoints that is uniquely identified by a dialog identifier. Not all SIP requests create dialogs. However, the ones that do create dialogs have a well-defined mechanism of establishing and tearing down the dialog (INVITE, SUBSCRIBE/NOTIFY, REFER).
The SIP stack shown in this diagram is not strictly in accordance with RFC 3261. It differs from the specification in that there is a layer called Transaction User (TU) above the Transaction layer, and the dialog management layer is not explicitly a layer in 3261. The “Dialog layer” is a very visible constituent of a SIP Servlet container because the dialogs correspond roughly to the SipSession objects. In Figure 2-3, the TU layer is actually split between the Dialog management layer and the big Container block.
The primary purpose of the Container is to host SIP Servlet applications that are written to the container's SIP Servlet API implementation. It exposes objects like SipServletRequest, SipServletResponse, different types of Sessions, facilities such as Timer, Logging, and so forth.
Although SIP is a human-readable, text-based protocol, and is well-defined in RFC 3261, writing SIP applications can be a challenging task. The SIP Servlet API is designed to simplify SIP application development. While the SIP Servlet API allows access to all the headers present in a SIP Request, it does not require applications to understand or modify all of them for correct protocol behavior. Also, there are some headers that are strictly off limits for applications. The SIP Servlet API defines the so-called "system headers" which are to be managed only by the container. These headers include the From, To, Call-ID, CSeq, Via, Route (except through pushRoute), Record-Route, and Contact headers. Applications can add attributes to the Record-Route header and Contact header fields in all request messages, as well as 3xx and 485 responses. Additionally, for containers such as Converged Application Server that implement the reliable provisional responses extension, RAck and RSeq are also considered to be system headers. The system header management performed by the container offloads a tremendous amount of complexity from applications.
The From, To, Call-ID, and CSeq message headers collectively identify a given SIP dialog. The SIP Servlet container keeps track of the dialog state and dialog-related data for the hosted applications. The SIP Servlet container is responsible for managing Record-Route, Contact, and Via headers because the network listen points, failure management, multi-homing, transport switching, and so forth are also handled by the container. Applications can participate in the routing decisions of a Request emanating from the container by explicitly modifying Request-URI or adding Route headers with pushRoute. As a result, applications have no responsibility for resource management. The SIP Servlet API draws heavily from Java EE standardization and common practices, such as the declarative usage of container features such as security, mapping, and environment resources.
Perhaps the greatest advantage of the SIP Servlet API is the API itself. The SIP Servlet API abstracts a large number of complex SIP tasks behind intuitive constructs. The Proxy interface, representing the proxy functionality in SIP, is an excellent example. A proxy can:
Be stateful or stateless.
Recurse automatically (send Requests automatically) upon receipt of a 3xx SIP response code to the Contact address(es) contained in the Response header.
Use the Record-Route header to ensure that subsequent requests also go through it.
Act as a forking proxy to proxy to multiple destinations, either in parallel or in sequence.
With the SIP Servlet API, all of these options are simple attributes of the Proxy object. The container-managed Proxy deals with all low level details like finding a target set (based on Request-URI or Route headers), applying RFC rules if a strict router is upstream or downstream, creating multiple client transactions, correlating responses, choosing the best response, and so forth.
This section describes additional important interfaces and constructs of the SIP Servlet API, and includes examples.
The SipServlet class extends the GenericServlet class in the servlet base package. The service method dispatches the SIP message to either doRequest() or doResponse(), and in turn the requests are directed to the doXXX methods for Requests such as doInvite, doSubscribe, and so forth, or to doXXX methods for Responses such as doSuccessResponse and doErrorResponse.
The servlet-mapping element defined in the deployment descriptor can define the rule that MUST be satisfied before invoking a particular Servlet. The mapping rules have a well-defined grammar in JSR 116. Example 2-1 shows a mapping that invokes a Servlet only if the Request is an INVITE and the host part of the Request-URI contains the string “oracle.com”. See Appendix A, "SIP Servlet API Service Invocation," for more information on servlet mapping rules.
Example 2-1 Example Servlet Mapping Rule
pattern
<and>
<equal>
<var>request.method</var>
<value>INVITE</value>
</equal>
<contains ignore-case="true">
<var>request.from.uri.host</var>
<value>oracle.com</value>
</contains>
</and>
</pattern>
There is normally only one SipServlet object accessed by concurrent Requests, so it is not a place to define any call- or session- specific data structure. The doXXX methods in the application generally implement the business logic for a given request. Consider Example 2-2.
Example 2-2 Example SIP Servlet
1: package test;
2: import javax.servlet.sip.SipServlet;
3: import javax.servlet.sip.SipServletRequest;
4: import java.io.IOException;
5: public class SimpleUasServlet extends SipServlet {
6: protected void doInvite(SipServletRequest req)
7: throws IOException {
8: req.createResponse(180).send();
9: req.createResponse(200).send();
10: }
11: protected void doBye(SipServletRequest req) throws IOException {
12: req.createResponse(200).send();
13: req.getApplicationSession().invalidate();
14: }
15: }
Example 2-2 shows a simple UAS Servlet that is invoked on an incoming INVITE Request (triggered by a rule similar to the one defined in Example 2-1). The container invokes the application by invoking the doInvite method. The application chooses to send a 180 Response (line 8) followed by a 200 Response (line 9). The application does nothing with the ACK, which would be sent by the UAC. In this case the container receives the ACK and silently ignores it. If it were a stateful proxy it would have proxied it.
As its name suggests, this class is used to create various SIP Servlet API objects such as Request, SipApplicationSession, Addresses, and so forth. An application acting as a UA can use it to create a new Request. Requests created through the factory have a new Call-ID (with the exception of a particular method for B2BUAs in which the application can chose to re-use the existing Call-ID on the upstream leg) and do not have a tag in the To header. The Factory object can be retrieved using the javax.servlet.sip.SipFactory attribute on the ServletContext.
See the "findme" example installed with Converged Application Server for an example of obtaining a factory object using SipFactory.
There are two classes of SIP messages: SipServletRequest and SipServletResponse. These classes respectively represent SIP Requests (INVITE, ACK, INFO, and so forth) and Responses (1xx, 2xx, and so forth). Messages are delivered to the application through various doXXX methods defined in the SipServlet class.
SIP is an asynchronous protocol and therefore it is not obligatory for an application to respond to a Request when the doRequest(doXXX) method is invoked. The application may respond to the Request at a later stage, because they have access to the original Request object.
Both the SipServletRequest and SipServletResponse objects are derived from the base SipServletMessage object, which provides some common accessor/mutator methods such as getHeader(), getContent(), and setContent(). The SipServletRequest defines many useful methods for Request processing:
SipServletRequest.createResponse() creates an instance of the SipServletResponse object. This represents the Response to the Request that created it. Similarly, SipServletRequest.createCancel() creates a CANCEL Request to a previously sent Request.
Note:
The CANCEL is sent if the UAC decides to not proceed with the call if it has not received a response to the original request. Sending a CANCEL if you have received a 200 response or not received a 100 response would be wrong protocol behavior, luckily the SIP Servlet API steps up to rescue here too. The UAC application can create and send a CANCEL oblivious to these details. The container ensures that a CANCEL is sent out only if a 1xx response code is received, and any response >200 is not received.SipServletRequest.getProxy() returns the associated Proxy object to enable an application to perform proxy operations.
SipServletRequest.pushRoute(SipURI) enables a UAC or a proxy to route the request through a server identified by the SipURI. The effect of this method is to add a Route header to the request at the top of the Route header list.
Another method of interest is SipServletRequest.isInitial(). It is important to understand the concept of initial and subsequent requests, because an application may treat each one differently. For example, if an application receives a Re-INVITE request, it is delivered to the Servlet's doInvite() method, but the isInitial() method returns false.
Initial requests are usually requests outside of an established dialog, of which the container has no information. Upon receiving an initial Request, the container determines which application should be invoked; this may involve looking up the Servlet-mapping rules. Some Requests create dialogs, so any Request received after a dialog is established falls into the category of a "subsequent" Request. Closely-linked with the dialog construct in SIP is the SipSession object (see "SipSession").
In the SipServletResponse object, one particular method of interest is createAck(). createAck() creates an ACK Request on a 2xx Response received for the INVITE transaction. ACKs for non-2xx responses of the INVITE transaction are created by the container itself.
The SipSession roughly corresponds to a SIP dialog. For UAs the session maintains the dialog state as specified by the RFC, in order to correctly create a subsequent request in a dialog. If an application is acting as a UA (a UAC or a B2BUA), and after having processed an initial request wants to send out a subsequent request in a dialog (such as a Re-INVITE or BYE), it must use SipSession.createRequest() rather than one of SipFactory methods. Using a factory method would result in requests being created “out of dialog”.
The SipSession is also a place for an application to store any session-specific state that it requires. An application can set or unset attributes on the SipSession object, and these attributes are made available to the application over multiple invocations.
SipSession also provides the SipSession.setHandler(String nameOfAServlet) method, which assigns a particular Servlet in the application to receive subsequent Requests for that SipSession.
The SipApplicationSession logically represents an instance of the application itself. An application may have one or more protocol sessions associated with it, and these protocol sessions may be of type SipSession or HttpSession as of JSR 116. Applications can also store application-wide data as an attribute of the SipApplicationSession.
Any attribute set on a SipApplicationSession object or its associated SipSession is visible only to that particular application. The SIP Servlet API defines a mechanism by which more than one application can be invoked on the same call. This feature is known as application composition. SipApplicationSession provides a getSessions() method that returns the protocol sessions associated with the application session. Figure 2-4 shows the containment hierarchy of the different sessions in the SIP Servlet API.
The encodeUri(URI) method in the SipApplicationSession interface is of particular interest. This method encodes the SipApplication identifier with the URI specified in the argument. If the container receives a new request with this encoded URI, even if on a different call, it associates the encoded SipApplicationSession with this Request. This method can link two disparate calls, and it can be used in a variety of other ways. SipApplicationSession is also associated with application session timers (see "Application Timers").
The SIP Servlet API provides a timer service that applications can use. The TimerService interface can be retrieved using a ServletContext attribute, and it defines a createTimer(SipApplicationSession appSession, long delay, boolean isPersistent, java.io.Serializable info) method to start an application-level timer.
The SipApplicationSession is implicitly associated with application-level timers. When a timer fires, the container invokes an application-defined TimerListener and passes it the ServletTimer object. The listener can use the ServletTimer object to retrieve the SipApplicationSession, which provides the correct context for the timer's expiry.
In terms of the SIP Servlet API, a converged application is one that involves more than one protocol, in this case SIP and HTTP. Example 2-3 presents an example of a simple JSP page which can be accessed through an HTTP URL.
Example JSP Showing HTTP and SIP Servlet Interaction
Example 2-3 Example JSP Showing HTTP and SIP Interaction
1: <html>
2: <body>
3: <%
4: if (request.getMethod().equals("POST")) {
5: javax.servlet.sip.SipFactory factory =
6: (javax.servlet.sip.SipFactory) application.getAttribute(javax.servlet.sip.SipServlet.SIP_FACTORY);
7: javax.servlet.sip.SipApplicationSession appSession =
8: factory.createApplicationSession();
9: javax.servlet.sip.Address to =
10: factory.createAddress("sip:localhost:5080");
11: javax.servlet.sip.Address from =
12: factory.createAddress("sip:localhost:5060");
13: javax.servlet.sip.SipServletRequest invite =
14: factory.createRequest(appSession, "INVITE", from, to);
15: javax.servlet.sip.SipSession sess = invite.getSession(true);
16: sess.setHandler(“sipClickToDial");
17: //invite.setContent(content, contentType);
18: invite.send();
19: }
20: %>
21: <p>
22: Message sent ...
23: </p>
24: </body>
25: </html>
The JSP shown in Example 2-3 would need to be packaged in the same application as a SIP Servlet. The entire application is a skeleton of a click-to-dial application (called sipClickToDial), where by clicking on a Web page you initiate a SIP call.
The HTTP Servlet creates a SIP Request from a factory and sends it to a SIP URI. When an HTTP POST Request is sent to the HTTP Servlet it obtains the SipFactory on line 5-6. Next, it creates an application session (line 7-8). The application session is the center piece for all of the application's SIP and HTTP interactions. The overall purpose is to send out a SIP Request, which is done in lines 13-14, but first the application creates the From and To headers to be used when forming the INVITE request.
On line 16 the application assigns a handler to the SipSession that is associated with the INVITE Request that was created, and this ensures that the Response sent by a UAS that receives the request is dispatched to a SIP Servlet for processing.
In the example shown in Example 2-4 below, the application receives a SUBSCRIBE Request and sends out a NOTIFY Request. The application then waits for the notification recipient for three seconds, and if does not receive a success response (a 2xx class response), then it may take some other action (for example, log a message).
Example 2-4 Example of SUBSCRIBE and NOTIFY Handling
1: public class Sample_TimerServlet extends SipServlet
2: implements TimerListener {
3: private TimerService timerService;
4: private static String TIMER_ID = "NOTIFY_TIMEOUT_TIMER";
5: public void init() throws ServletException {
6: try {
7: timerService =
8: (TimerService)getServletContext().getAttribute
9: ("javax.servlet.sip.TimerService");
10: }
11: catch(Exception e) {
12: log ("Exception initializing the servlet "+ e);
13: }
14: }
15: protected void doSubscribe(SipServletRequest req)
16: throws ServletException, IOException {
17: req.createResponse(200).send();
18: req.getSession().createRequest("NOTIFY").send();
19: ServletTimer notifyTimeoutTimer =
20: timerService.createTimer(req.getApplicationSession(), 3000,
21: false, null);
22: req.getApplicationSession().setAttribute(TIMER_ID,
23: notifyTimeoutTimer);
24: }
25: protected void doSuccessResponse(SipServletResponse res)
26: throws javax.servlet.ServletException, java.io.IOException {
27: if (res.getMethod().equals("NOTIFY")) {
28: ServletTimer notifyTimeoutTimer =
29: (ServletTimer)(res.getApplicationSession().getAttribute(TIMER_ID));
30: if (notifyTimeoutTimer != null) {
31: notifyTimeoutTimer.cancel();
32: res.getApplicationSession().removeAttribute(TIMER_ID);
33: }
34: }
35: }
36: public void timeout(ServletTimer timer) {
37: // This indicates that the timer has fired because a 200 to
38: // NOTIFY was not received. Here you can take any timeout
39: // action.
40: // .........
41: timer.getApplicationSession().removeAttribute
("NOTIFY_TIMEOUT_TIMER");
42: }
43: }
In Example 2-4, the Servlet itself implements TimerListener so that it will be notified of the timeout. The example starts by obtaining the TimerService from the ServletContext in lines 7-9. The timer is then set for 3000 ms (3 seconds) upon receiving the SUBSCRIBE request on line 20. Note that the timer could be set at any stage. There is also an option to attach an object to the timer. The object could be used as an identifier or an invokable message at a later stage. This sample simply associates the timer with a literal.
After sending the NOTIFY the application creates the timer and saves its reference in the SipApplicationSession for later use on line 22.
If the application receives a 200 response to the NOTIFY, it can then extract the timer reference and cancel the timer (line 25). However, if no response is received in 3 seconds, then the timer fires and the container calls the timeout() callback method (line 36).
The IMS specification defines the Sh interface as the method of communication between the Application Server (AS) function and the Home Subscriber Server (HSS), or between multiple IMS Application Servers. The AS uses the Sh interface in two basic ways:
To query or update a user's data stored on the HSS
To subscribe to and receive notifications when a user's data changes on the HSS
The user data available to an AS may be defined by a service running on the AS (repository data), or it may be a subset of the user's IMS profile data hosted on the HSS. The Sh interface specification, 3GPP TS 29.328 V5.11.0, defines the IMS profile data that can be queried and updated via Sh. All user data accessible via the Sh interface is presented as an XML document with the schema defined in 3GPP TS 29.328.
The IMS Sh interface is implemented as a provider to the base Diameter protocol support in Converged Application Server. The provider transparently generates and responds to the Diameter command codes defined in the Sh application specification. A higher-level Profile Service API enables SIP Servlets to manage user profile data as an XML document using XML Document Object Model (DOM). Subscriptions and notifications for changed profile data are managed by implementing a profile listener interface in a SIP Servlet.
Converged Application Server includes only a single provider for the Sh interface. Future versions of Converged Application Server may include new providers to support additional interfaces defined in the IMS specification. Applications using the profile service API will be able to use additional providers as they are made available.
Servlets that manage profile data can explicitly obtain an Sh XML document from a factory using a key, and then work with the document using DOM.
The document selector key identifies the XML document to be retrieved by a Diameter interface, and uses the format protocol://uri/reference_type[/access_key].
Table 2-1 summarizes the required document selector elements for each type of Sh data reference request.
Table 2-1 Summary of Document Selector Elements for Sh Data Reference Requests
| Data Reference Type | Required Document Selector Elements | Example Document Selector |
|---|---|---|
|
RepositoryData |
sh://uri/reference_type/Service-Indication |
sh://sip:user@oracle.com/RepositoryData/Call Screening/ |
|
IMSPublicIdentity |
sh://uri/reference_type/[Identity-Set] where Identity-Set is one of:
|
sh://sip:user@oracle.com/IMSPublicIdentity/Registered-Identities |
|
IMSUserState |
sh://uri/reference_type |
sh://sip:user@oracle.com/IMSUserState/ |
|
S-CSCFName |
sh://uri/reference_type |
sh://sip:user@oracle.com/S-CSCFName/ |
|
InitialFilterCriteria |
sh://uri/reference_type/Server-Name |
sh://sip:user@oracle.com/InitialFilterCriteria/www.oracle.com/ |
|
LocationInformation |
sh://uri/reference_type/(CS-Domain | PS-Domain) |
sh://sip:user@oracle.com/LocationInformation/CS-Domain/ |
|
UserState |
sh://uri/reference_type/(CS-Domain | PS-Domain) |
sh://sip:user@oracle.com/UserState/PS-Domain/ |
|
Charging information |
sh://uri/reference_type |
sh://sip:user@oracle.com/Charging information/ |
|
MSISDN |
sh://uri/reference_type |
sh://sip:user@oracle.com/MSISDN/ |
Converged Application Server provides a helper class, com.bea.wcp.profile.ProfileService, to help you easily retrieve a profile data document. The getDocument() method takes a constructed document key, and returns a read-only org.w3c.dom.Document object. To modify the document, you make and edit a copy, then send the modified document and key as arguments to the putDocument() method.
See "Using the Profile Service API (Diameter Sh Interface)" in Converged Application Server Diameter Application Development Guide for more information.
The IMS Sh interface enables applications to receive automatic notifications when a subscriber's profile data changes. Converged Application Server provides an easy-to-use API for managing profile data subscriptions. A SIP Servlet registers to receive notifications by implementing the com.bea.wcp.profile.ProfileListener interface, which consists of a single update method that is automatically invoked when a change occurs to profile to which the Servlet is subscribed. Notifications are not sent if that same Servlet modifies the profile information (for example, if a user modifies their own profile data).
Note:
In a replicated environment, Diameter relay nodes always attempt to push notifications directly to the engine tier server that subscribed for profile updates. If that engine tier server is unavailable, another server in the engine tier cluster is chosen to receive the notification. This model succeeds because session information is stored in the SIP data tier, rather than the engine tier.Actual subscriptions are managed using the subscribe method of the com.bea.wcp.profile.ProfileService helper class. The subscribe method requires that you supply the current SipApplicationSession and the key for the profile data document you want to monitor. See "Using Document Keys for Application-Managed Profile Data" for more information.
Applications can cancel subscriptions by calling ProfileSubscription.cancel(). Also, pending subscriptions for an application are automatically cancelled if the application session is terminated.
Example 2-5 shows sample code for a Servlet that implements the ProfileListener interface.
Example 2-5 Sample Servlet Implementing ProfileListener Interface
package demo;
import com.bea.wcp.profile.*;
import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipServlet;
import org.w3c.dom.Document;
import java.io.IOException;
public class MyServlet extends SipServlet implements ProfileListener {
private ProfileService psvc;
public void init() {
psvc = (ProfileService) getServletContext().getAttribute(ProfileService.PROFILE_SERVICE);
}
protected void doInvite(SipServletRequest req) throws IOException {
String docSel = "sh://" + req.getTo() + "/IMSUserState/";
// Subscribe to profile data.
psvc.subscribe(req.getApplicationSession(), docSel, null);
}
public void update(ProfileSubscription ps, Document document) {
System.out.println("IMSUserState updated: " + ps.getDocumentSelector());
}
}
The ProfileListener interface is handled similar to the TimerService provided by JSR 116 for application timers. Multiple Servlets in an application may implement the ProfileListener interface, but only one Servlet may act as a listener. The SIP deployment descriptor for the application must designate the profile listener class in the set of listeners as shown in Example 2-6.
With Converged Application Server, you can upgrade a deployed SIP application to a newer version without losing existing calls being processed by the application. This type of application upgrade is accomplished by deploying the newer application version alongside the older version. Converged Application Server automatically manages the SIP Servlet mapping so that new requests are directed to the new version. Subsequent messages for older, established dialogs are directed to the older application version until the calls complete. After all of the older dialogs have completed and the earlier version of the application is no longer processing calls, you can safely un-deploy it.
Converged Application Server's upgrade feature ensures that no calls are dropped while during the upgrade of a production application. The upgrade process also enables you to revert or rollback the process of upgrading an application. If, for example, you determine that there is a problem with the newer version of the deployed application, you can simply un-deploy the newer version. Converged Application Server then automatically directs all new requests to the older application version.
To use the application upgrade functionality of Converged Application Server:
You must assign version information to your updated application in order to distinguish it from the older application version. Note that only the newer version of a deployed application requires version information; if the currently-deployed application contains no version designation, Converged Application Server automatically treats this application as the “older” version.
Both the deployed application and the updated application must provide only SIP protocol functionality. You cannot upgrade converged HTTP/SIP applications using these procedures.
A maximum of two different versions of the same application can be deployed at one time.
If your application hard-codes the use of an application name (for example, in composed applications where multiple SIP Servlets process a given call), you must replace the application name with calls to a helper method that obtains the base application name. Converged Application Server provides SipApplicationRuntimeMBean methods for obtaining the base application name and version identifier, as well as determining whether the current application version is active or retiring.
When applications take part in a composed application (using application composition techniques), Converged Application Server always uses the latest version of an application when only the base name is supplied.
Converged Application Server also provides the ability for Administrators to upgrade the SIP Servlet container, JVM, or application on a cluster-wide basis without affecting existing SIP traffic. This is accomplished by creating multiple clusters and having Converged Application Server automatically forward requests during the upgrade process. See the discussion on upgrading the Oracle Communications Converged Application server software in Converged Application Server Administration Guide for more information on upgrading the SIP Servlet container, JVM, or applications.
Oracle Communication Converged Application Server provides support for GSM Association's (GSMA) IR.92 specifications for delivering Voice over LTE (VoLTE). You can implement these services using either the SIP Servlet 1.1 (JSR 289) or the Service Foundation Toolkit (SFT).
SFT provides enhanced APIs that you can use to quickly and easily implement applications for delivering IR.92-compliant supplementary services over VoLTE. The APIs provide support for supplementary services such as Call Forwarding, Incoming and Outgoing Call Barring, ID Presentation and Restriction, Multi-Party Conferencing, and Message Waiting Indication (MWI).
GSM Association's (GSMA) IR.92 specifications defines the IP Multimedia Subsystem (IMS) profile for delivering Voice over LTE (VoLTE). The GSMA VoLTE initiative has defined IMS as the common way to deliver voice and messaging services over mobile broadband all-IP networks.
In September 2010, GSMA published the IREG Permanent Reference Document IR.92, which outlines the specifications for migrating 2G and 3G mobile voice, video and messaging services to 4G mobile broadband networks, such as LTE.
This chapter describes the following IR.92 call control services, and their implementation in Converged Application Server:
Communication Diversion (also referred to as Call Diversion or Call Forwarding) lets users of the service (the called party, or callee) forward incoming calls to another phone number (the third party). The third party may be a mobile telephone, voice-mail box, or other telephone number where the desired called party is situated.
With Communication Diversion activated:
Users can continue to make outgoing calls from their telephone while incoming calls are forwarded.
When the telephone number the user's calls are being forwarded to is busy, callers to the forwarded number will receive a busy signal.
Converged Application Server supports the following IR.92 defined Communication Diversion modes for VoLTE:
Communication Forwarding Unconditional 3GPP TS 24.604
Communication Forwarding on No Reply 3GPP TS 24.604
Communication Forwarding on not Logged in 3GPP TS 24.604
Communication Forwarding on Busy 3GPP TS 24.604
Communication Forwarding on not Reachable 3GPP TS 24.604
Communication Diversion applications forward calls by removing the callee (the person to whom the call is being made), and adding a new participant (the third party) in the calle's place.
Communication Barring lets users bar (or restrict) certain or all types of calls to and from their phone. For example, a user can restrict outgoing calls, outgoing international calls, or incoming calls from undesirable callers.
Converged Application Server supports the following IR.92 defined Call Barring modes for VoLTE:
Barring of All Incoming Calls 3GPP TS 24.611
Barring of All Outgoing Calls 3GPP TS 24.611
Barring of Outgoing International Calls 3GPP TS 24.611
Barring of Outgoing International Calls—ex Home Country 3GPP TS 24.611
Barring of Incoming Calls When Roaming 3GPP TS 24.611
To implement international call barring, the Communication Barring application must have access to the phone number of the participant. The application can access this information from various sources, such as the Registrar, to determine roaming status. Similarly, the profile of the user—such as country of origin—can be obtained by the application using other interfaces (for example, the Diameter interface).
Communication Hold (also referred to Call Hold) allows a user to suspend a communication session—the reception of media stream(s) from an established IP multimedia session—and resume the media stream(s) at a later time. Placing a Communication Hold on an ongoing session is achieved by sending a Session Description Protocol (SDP) offer where each of the communications (media streams) to be held are marked with the sendonly attribute if they were previously bidirectional media streams. To resume the session, a new SDP offer is issued in which each of the held media streams is marked with the default sendrecv attribute.
Communication Hold also allows an AS to play music or an announcement to the held party. This is achieved using an AS that acts as a third-party call controller (3PCC), and replaces the existing session of one of the users with a session originating from an application server that plays the announcement or music until the user's session is resumed. See the 3GPP TS 24.628 specification for more information on the playing of announcements during Communication Hold.
The 3GPP TS 24.610 specification requires that the AS of the User Equipment (UE) invoking a media stream whose SDP session attribute is recvonly use a lower bandwidth. The SDP specifies a lower bandwidth by setting the bandwidth (the b= line in the SDP) to a lower value. The b= line contains two elements:
The bandwidth value expressed in kilo bits per second (kbps).
An alphanumeric modifier that indicates the communication session or media stream to which to apply the specified bandwidth value.
The modifiers whose bandwidth values are specified by SFT are:
AS—Application Specific Maximum, which specifies the total bandwidth for a single media stream from one source.
RS—RTCP bandwidth allocated to active data senders.
RR—RTCP bandwidth allocated to other participants (receivers) in the RTP session.
When the bandwidth setting is enabled, SFT sets the default value for the AS bandwidth to zero (b=AS:0). The b=RR: and b=RS: parameters are set to a value of 800 kbps, which is high enough to allow the continuation of the RTCP flow: b=RR:800 and b=RS:800
Example 2-7 Bandwidth Line in the Session Description Protocol
v=0 o=alice 2890844526 2890842807 IN IP4 126.16.64.4 s=SDP Seminar c=IN IP4 224.2.17.12/127 t=2873397496 2873404696 m=audio 49170 RTP/AVP 0 b=AS:0 b=RR:800 b=RS:800
Note:
The 3GPP TS 24.610 specification recommends that the AS modify the bandwidth for media streams whose SDP session attribute isrecvonly. Media streams whose SDP session attribute are inactive, sendonly, and sendrecv are not affected.While the 3GPP TS 24.610 specification recommends these values to preserve network bandwidth when a communication is placed on hold, you may need to adjust the bandwidth to better suit the requirements of the Communication Hold application.
Converged Application Server supports the following Identity Presentation and Restriction services:
Originating Identification Presentation (OIP): Enables the called party to receive a network generated and trusted identity of the calling user on the screen of the mobile device. The originating user may also present a custom identity to be seen at the called party. The user generated identity is usually screened by the network of the originating user.
Originating Identification Restriction (OIR): Invoked when the calling user does not want their identity to be shown to the called party. In such cases, the network of the originating user signals to the network of the called user, to withhold the identity of the calling user.
Terminating Identification Presentation (TIP): Enables the calling party to receive the identification information of the remote party from the network. This information is provided to the originating party once the IMS communication has been accepted between the endpoints. The information is delivered regardless of the capability of the handset to process such information at the originating end.
Terminating Identification Restriction (TIR): Provides the terminating party with an option to restrict the identity to be presented to the originating party of the IMS communication. Logically speaking, TIR is the opposite of TIP.
To support the Identity Presentation and Restriction services listed above:
UE and IMS core network must support the SIP procedures described in the 3GPP TS 24.607 specification. Service configuration, as described in Section 4.10 of 3GPP TS 24.607, is optional.
UE and IMS core network must support the SIP procedures in the 3GPP TS 24.608 specification. Service configuration, as described in section 4.9 of 3GPP TS 24.608, is optional.
The privacy service role is instantiated by a network intermediary. Typically this function is performed by entities that act as SIP proxy servers. The privacy service is designed to provide privacy functions for SIP messages that cannot otherwise be provided by the UAs themselves. Table 2-2 lists the semantics of each priv-value, and the RFC that defines them.
Table 2-2 Types of Privacy Service Behaviors
| Privacy Type | Description |
|---|---|
|
|
Request that privacy services provide a user-level privacy function. See RFC 3323, "A Privacy Mechanism for the Session Initiation Protocol (SIP)" for more information. |
|
|
Request that privacy services modify headers that cannot be set arbitrarily by the user. For example, the Contact and Via headers. See RFC 3323, "A Privacy Mechanism for the Session Initiation Protocol (SIP)" for more information. |
|
|
Request that privacy services provide privacy for session media. See RFC 3323, "A Privacy Mechanism for the Session Initiation Protocol (SIP)" for more information. |
|
|
Privacy services must not perform any privacy function. See RFC 3323, "A Privacy Mechanism for the Session Initiation Protocol (SIP)" for more information. |
|
|
Privacy service must perform the specified services or fail the request. See RFC 3323, "A Privacy Mechanism for the Session Initiation Protocol (SIP)" for more information. |
|
|
Privacy requested for Third-Party Asserted Identity. See RFC 3325, "Private Extensions to the Session Initiation Protocol (SIP) for Asserted Identity within Trusted Networks" for more information. |
|
|
Privacy requested for History-Info headers. See RFC 4244, "An Extension to the Session Initiation Protocol (SIP) for Request History Information" for more information. |
RFC 5379 describes privacy considerations and the recommended treatment of each SIP header that may reveal user-privacy information. Section 5, "Recommended Treatment of User-Privacy-Sensitive Information" of RFC 5379 describes how each header affects privacy, the desired treatment of the value by the user agent and privacy service, and other details needed to ensure privacy.Table 2-3 lists the recommended treatment for each priv-value contained in the SIP header. See "Section 5" of RFC 5379 "Guidelines for Using the Privacy Mechanism for SIP" for more information.
Table 2-3 Treatment of User-Privacy Information in Target SIP Headers
| Target SIP Headers | Where | User | Header | Session | ID | History |
|---|---|---|---|---|---|---|
|
Call-ID |
R |
Anonymize |
||||
|
Call-Info |
Rr |
Delete |
Not added |
|||
|
Contact |
R |
Anonymize |
||||
|
From |
R |
Anonymize |
||||
|
History-Info |
Rr |
Delete |
Delete |
Delete |
||
|
In-Reply-To |
R |
Delete |
||||
|
Organization |
Rr |
Delete |
Not added |
|||
|
P-Asserted-Identity |
Rr |
Delete |
Delete |
|||
|
Record-Route |
Rr |
Anonymize |
||||
|
Referred-By |
R |
Anonymize |
||||
|
Reply-To |
Rr |
Delete |
||||
|
Server |
r |
Delete |
Not added |
|||
|
Subject |
R |
Delete |
||||
|
User-Agent |
R |
Delete |
||||
|
Via |
R |
Anonymize |
||||
|
Warning |
r |
Anonymize |
The History-Info header (defined in RFC 4244) provides a way of capturing any redirection information that may have occurred during a particular call. Without the History-Info header the redirecting information would be lost. The History-Info header is generated when a SIP request is re-directed, and can appear in any SIP request not associated with a dialog. The History-Info header is generated by a User Agent or proxy and is passed from one entity to another through requests and responses.
Communication Waiting (also referred to as Call Waiting) informs a user (or the user equipment) that limited resources are available for incoming calls. Typically this means that the callee is involved in a communication session with another caller, and is not able to answer the incoming call from the second caller. Communication Waiting provides a mechanism by which you can create an application to inform a user that there is a second incoming call. The user then has the choice of accepting, rejecting, or ignoring the waiting call. Converged Application Server supports the 3GPP TS 24.615 and the GSMA IR.92 specifications.
When using SFT to develop Communication Waiting services, Converged Application Server supports both network- and terminal-based Communication Waiting.
Network-based Communication Waiting occurs when the AS determines that one of the following conditions has occurred:
The SIP INVITE request fulfills the Network Determined User Busy (NDUB) condition for the callee.
The caller receives a SIP message 486 Busy Here (indicating that the callee is busy) with a 370 Warning in the SIP header field indicating that there is insufficient bandwidth for the call to complete.
To support network-based Communication Waiting, the AS performs the following functions in response to receiving an appropriate Communication Waiting condition:
Modifies the SIP INVITE request and forwards or re-sends it to User B.
Provides an announcement to User C upon receipt of a 180 Ringing response from User B.
Inserts an Alert-Info header field set to urn:alert:service:call-waiting in the 180 Ringing response and forwards it to User C
Rejects the communication by sending a 486 Busy Here response to User C upon receipt of a 415 Unsupported Media Type response.
Terminal-based Communication Waiting occurs when the AS receives the SIP message 180 Ringing with the Alert-Info header URN Indication Values set to urn:alert:service:call-waiting.
To support terminal-based Communication Waiting, the application server performs the following functions in response to receiving an appropriate Communication Waiting condition:
Sends an announcement to the calling user (the caller).
Sends a 180 Ringing response to the caller.
Initiates the Telephony Application Server-Communication Waiting (TAS-CW) timer. This optional timer specifies the amount of time the network will wait for a response from User B, in response to the communication from User C. The value of the timer is between 0.5 and 2 minutes.
If the TAS-CW timer expires, the AS sends a CANCEL request to User B with a Reason header field set to "SIP," and the cause set to 408 Request Timeout, indicating that the user could not be found in the allotted time. A 480 Temporarily Unavailable response is sent to User C, including a Reason header field set to ISUP Cause Code 19, indicating that these was no answer from the callee.
Message Waiting Indication (MWI) is a service that informs a user about the status of recorded messages. To use the notification feature, the user must subscribe to a notification service that makes use of the Message Waiting Indication status messages. With the Message Waiting Indication feature you can:
Send notification when a new subscription arrives.
Specify when notifications are sent in response to subscriptions.
Reject subscriptions.
Terminate subscriptions.
Note:
Typically a voice-mail server manages Message Waiting Indication accounts. When a new message arrives, the voice-mail server typically provides a listener or API that you can resister with to receive notification of new messages. How the application manages the message account is beyond the scope of the SFT Message Waiting Indication APIs.Message Waiting Indication lets the AS notify a subscriber that there is a message waiting for them. The indication is delivered to the subscriber's UE after they have successfully subscribed to the Message Waiting Indication service. Message Waiting Indication is defined in the 3GPP TS 24.606 specification.
When Converged Application Server receives a SUBSCRIBE message, SFT notifies the MWI application via a SUBSCRIPTION event. RFC 3842 specifies that a NOTIFY message must be sent when accepting new subscriptions, the subscription has expired, or an unsubscribe event occurs. Converged Application Server's Event Notification Service sends these NOTIFY messages automatically.
Announcements are service-related messages played to a recipient to inform them about the state of a call. Announcements can be provided using either audio or video content. Converged Application Server supports the playing of announcements as defined in the 3GPP TS 24.628 specification.
Converged Application Server supports the following approaches to playing announcements:
Send the media stream to the recipient of the announcement for playback.
This approach uses a media server and Media Resource Function Processor (MRFP). The media is streamed to the recipient using the Real-time Transport Protocol (RTP) after establishing a media session with the media server. Based on the point-in-time at which the media session is initiated, an early- or non-early media session can be used.
SFT reserves a media resource using the JSR 309 API (the JSR 309 driver used by the media server). The underlying mechanism between the JSR309 driver and MRFP is protocol agnostic.
Send information about the media content that lets the recipient retrieve and playback the announcement.
This approach sends a URI identifying the media to the recipient, allowing them to determine whether or not to play the announcement.
Converged Application Server lets you access an XML Document Management Server (XDMS). The XDMS handles the management of user-generated XML documents stored on the network, such as authorization rules and contact and group lists (also referred to as resource lists).
The XML Configuration Access Protocol Server (XCAP server), provides an interface that allows for the manipulation of service-related data stored as XML documents within the XDMS. The XCAP specification defines how an HTTP address (or URI) can identify the way XML documents are stored on an XCAP server. It also defines how the URI can be used to identify entire XML documents, individual elements, or XML attributes that can be retrieved, updated, or deleted.
An Application Unique ID (AUID), which uniquely identifies the application usage, must be created.
The XML schema must be defined.
The default namespace binding, which maps the namespace prefixes to the namespace URIs, must be set.
The MIME type of the document must be defined.
The XCAP server must be able to validate the content of each XCAP document that is being modified.
The data in the XML document must have a well defined semantic.
Naming conventions for XCAP client URIs must be set.
Resource interdependencies, how changes to one resource will effect other resources, has to be determined.
The following operations are supported using XCAP:
Retrieving an item
Deleting an item
Modifying an item
Adding an item
The XCAP addressing mechanism is based on XML Path Language (XPath), a query language for selecting nodes in XML documents. The operations above can be executed on XML documents and elements. Operations to XML attributes are not supported, however, attributes can be handled indirectly by modifying the elements that contain them.
Converged Application Server provides two levels of XCAP support: Access to the XDMS using a base XCAP API that is not specific to any schema, and a high level API providing support for GSMA IR.92 supplementary services using VoLTE as supported by the Service Foundation Toolkit (SFT). The VoLTE version of the XCAP API, supports the following supplementary services:
3GPP TS 24.611 Communications Diversion
3GPP TS 24.604 Communication Barring
3GPP TS 24.607 Originating Identification Presentation and Originating Identification Restriction
3GPP TS 24.608 Terminating Identification Presentation and Terminating Identification Restriction
3GPP TS 24.615 Communication Waiting
The supported VoLTE functions are:
Partial operations (adding and removing XML elements)
Data validation
Support for 409 XCAP error responses as defined in Section 11 of RFC 4825
|
 Copyright © 2005, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|