Oracle® Communication and Mobility Server Developer’s Guide Release 10.1.
Oracle Communication and Mobility Server Developer’s Guide Release 10.1.3 E10293-02 Copyright © 2006, 2007, Oracle. All rights reserved. The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws.
Contents Preface ................................................................................................................................................................. ix Audience....................................................................................................................................................... Documentation Accessibility ..................................................................................................................... Related Documents ......
Setting and Accessing Global Init Parameters ............................................................................ Configuring Application Sessions ................................................................................................ Defining a Servlet............................................................................................................................ Defining the Servlet Mapping ........................................................................................
Importing the Third Party Call Control Example Project ............................................................ Deploying a SIP Application to OCMS............................................................................................... Testing an Application ............................................................................................................................ Changing the Logging Level ..........................................................................................
Rf Provider .................................................................................................................................. Rf Listener ................................................................................................................................... Rf Message Factory .................................................................................................................... Rf Events................................................................................
avp Element ................................................................................................................................ type Element ............................................................................................................................... enum Element............................................................................................................................. grouped Element.............................................................................
viii
Preface This preface contains the following topics: ■ Audience ■ Documentation Accessibility ■ Related Documents ■ Conventions Audience This guide is intended for developers and programmers who want to use Oracle Communication and Mobility Server to create custom applications. Documentation Accessibility Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community.
TTY Access to Oracle Support Services Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services within the United States of America 24 hours a day, seven days a week. For TTY support, call 800.446.2398.
1 Overview This chapter describes application development for the Oracle Communication and Mobility Server (OCMS) in the following sections: ■ "Introduction to Oracle Communication and Mobility Server" ■ "Application Development in OCMS" Introduction to Oracle Communication and Mobility Server Oracle Communication and Mobile Server (OCMS) is a carrier-grade SIP application environment for the development, deployment, and management of SIP applications.
Application Development in OCMS Application Development in OCMS The OCMS environment enables you to develop JSR-116-compliant applications through its support of the following: ■ SIP Servlet API ■ Parlay X Web Service Interface SIP Servlet API OCMS supports development of SIP servlets using the JSR-116 SIP Servlet API. Using these interfaces, you can build a SIP Servlet to create customized SIP-based components that terminate SIP messages, send SIP responses, and proxy SIP messages.
Application Development in OCMS Figure 1–1 OCMS SCE Application Development Support Overview 1-3
Application Development in OCMS 1-4 Oracle Communication and Mobility Server Developer’s Guide
2 SIP Servlets This chapter provides an overview of SIP Servlets and the SIP Servlet API (as described in JSR-116) in the following sections: ■ "Introduction to SIP Servlets" ■ "The SIP Container" ■ "SIP Servlets and SIP Applications" ■ "SIP Servlet Environment" ■ "Classes and Methods" ■ "Configuring SIP Applications in sip.
The SIP Container The SIP Container This section describes the SIP Container (Figure 2–1) by discussing the following components: ■ Servlet Context ■ SIP Application Sessions ■ Protocol Sessions ■ Transactions ■ Servlets ■ Listeners Figure 2–1 The SIP Container Object Model Servlet Context The Servlet Context is a servlet view of the SIP application to which it belongs. Using the Servlet Context, the servlet can access such global application services as listeners and context init parameters.
The SIP Container SIP Application Sessions While an application may involve several types of servlet sessions (for example, SIP and HTTP), these sessions must be related to the same application. This is done through a SIP Application Session. The SIP Application Session can hold multiple protocol sessions; the protocol sessions can be of the same type or different types (SIP, HTTP). A SIP Application Session can hold attributes available to all protocol sessions related to that application session.
The SIP Container Servlets Each servlet defined in the deployment descriptor has one instantiation. Because servlets are run in a multi-threaded environment, only data that is common to all requests and responses, such as init parameters, are stored as member variables. Increased Servlet Modularity Each servlet, which includes a and a section in the deployment descriptor file (sip.xml) also has a section.
SIP Servlet Environment SIP Servlets and SIP Applications A SIP application is a J2EE-compliant application accessed over the SIP protocol. Applications are triggered by an inbound SIP protocol request, just as Web applications are triggered by an inbound HTTP protocol request. An application has a protocol interface such as SIP or HTTP (presentation tier) that reaches servlets and other business objects (logic tier) which in turn are managed and have resource connections to the database (data tier).
SIP Servlet Environment d. The servlets are created and initiated with the init parameters prepared by the Servlet Config. Each servlet is run as one instance. The init method in the servlets is executed. e. A SIP Application Manager, which contains a reference to SipApplicationSessions and the SipFactory, is created. Figure 2–3 Initial Requests Processed by the SIP Container 2. 3.
Classes and Methods Servlet Mapping A SIP application can contain one or more SIP Servlets. When the SIP container receives SIP requests, the container selects a SIP application to serve the request. The SIP application then evaluates its rules (that is, the servlet-mapping defined in the sip.xml file) to find the appropriate SIP servlet that responds to the request. The SIP application then uses the first SIP servlet that matches the request.
Classes and Methods Outside of the service method, the doRequest() and doResponse() are the broadest methods provided by the SipServlet class. These methods enable tasks that are independent of the received method or response. You can extend methods to perform specific request and response handling tasks.
Classes and Methods A SIP request consists of the following: ■ Request line ■ Headers ■ Empty line ■ Message body All parts of the SIP request for instance request URI, headers and parameters are accessible through these interfaces. The SIP container handles many of these system headers.
Classes and Methods method that returns an iterator of the SIP headers of the message. The setHeader method sets or adds an address for a header. Specifying the name of the header in getHeaders(name) method returns another iterator of String objects containing all of the values for that header. For those headers that conform to AddressHeader, the getAddressHeader(name) method will return the header parsed as an Address object.
Classes and Methods Example 2–3 Accessing Parameters in SipURI // Create a SipURI, set the port, the lr, and the transport // protocol parameter SipURI myURI; myURI = sipFactory.createSipURI("bob", "10.0.0.10"); myURI.setPort(5072); myURI.setLrParam(true); myURI.setTransportParam("udp"); Address SIP addresses found in headers, such as the From, To, and Contact headers, are stored as javax.servlet.sip Address objects.
Classes and Methods ■ ■ Dialog-related information such as tags, contacts, and CSeq in the SIP messages are handled automatically. On outgoing requests, OCMS performs DNS lookups and supports NAPTR-, SRV-, and A-records (according to RFC 3263). Storing Data as Session Attributes The SIP Servlet API enables data to be stored as session attributes. Session attributes can be used to store session specific data to be used in responses and subsequent requests or from a listener class.
Configuring SIP Applications in sip.xml Configuring SIP Applications in sip.xml SIP servlets must be declared in the application’s deployment descriptor, the sip.xml file. The sip.xml file enables you to configure the init parameters and the rules that match initial requests with SIP servlets.
Configuring SIP Applications in sip.xml Defining a Servlet The element defines the SIP container’s servlets. A servlet requires a servlet name , and a servlet class, . The name must be unique within the application and the class must be the fully qualified name of the servlet class, as illustrated in Example 2–7. Example 2–7 Servlet Name and Servlet Class MyServlet com.company.example.
Configuring SIP Applications in sip.xml Creating Rules Using the Request Object Structure The request object model enables you to define rules for processing SIP requests. This section describes the object model and the predicates for building the rules. The Request object contains many sub objects, for example SipURI which extends the URI object. The request object contains the following elements: ■ method: The method of the request is represented as String.
Configuring SIP Applications in sip.xml Conditions Table 2–1 lists the operators. Table 2–1 Operators Condition Name Description equal Compares the value of a variable with a literal value and evaluates to true if the variable is defined and its value equals that of the literal. Otherwise, the result is false. exists Takes a variable name and evaluates to true if the variable is defined, or to false if the variable has not been defined.
Configuring SIP Applications in sip.xml Table 2–3 describes the variable values. Table 2–3 Variable Values Variable Value request.method MESSAGE request.uri sip:bob@example.com request.uri.scheme sip request.uri.user bob request.uri.host example.com request.uri.port 5060 request.uri.tel request.from "Alice" ;tag=1234 request.from.uri sip:alice@example.com request.from.uri.scheme sip request.from.uri.user alice request.from.uri.host example.com request.from.
SIP Servlets in OCMS to false as does the whole rule while the three conditions are all inside the and condition. SIP Servlets in OCMS This section describes the OCMS extensions to the SIP Servlet API as well as its implementation of it.
SIP Servlets in OCMS – Servlet 1 matches all requests. All of these applications have been deployed into the SIP container, but no default application has been specified. The SIP container then designates all of the SIP applications that it locates as the default application. For example, when the SIP container receives an INVITE request which does not designate which application to invoke, the SIP container checks for default applications.
SIP Servlets in OCMS Protocol Sessions The SIP Servlet specification infers that other protocol sessions, such as HTTP, can be placed in the same SIP Application Session. However, OCMS currently supports only the SIP protocol. This does not prevent you from creating converged SIP and HTTP applications. Please refer to Oracle Communication and Mobility Server documents on Oracle Technology Network (http://www.oracle.com/technology/index.html) for examples.
SIP Servlets in OCMS OCMS Authentication and Login Modules OCMS provides Digest Access Authentication against the users, user roles, and user data stored in the TimesTen In-Memory Database or against an external RADIUS (Remote Authentication Dial-In User Service) server. OCMS also supports authentication and authorization services for users provisioned to OID (Oracle Internet Directory).
SIP Servlets in OCMS 2-22 Oracle Communication and Mobility Server Developer’s Guide
3 Advanced SIP Servlet Configuration This chapter describes advanced topics related to SIP servlets through the following sections: ■ Using the appId Parameter to Set Addresses for SIP Applications ■ Configuring Application Security Using the appId Parameter to Set Addresses for SIP Applications Because JSR 116 does not state how to set the address for a SIP application, OCMS extends the specification by including a parameter called appId, (application ID) which is located either in the URI of the top-m
Using the appId Parameter to Set Addresses for SIP Applications Example 3–1, illustrates a ROUTE header present in the request. If the OCMS SIP servlet container has been configured to acknowledge the IP address of 192.168.0.100 as its address, it then uses the appId in the ROUTE header and invokes the application called presence. Example 3–1 The appId Parameter in the Route Header of an Incoming Request SUBSCRIBE sip:bob@example.com To: . From: . Route:
Using the appId Parameter to Set Addresses for SIP Applications Figure 3–1 Setting the Application Routing for an INVITE Request The SipUriList attribute is comprised of a comma-separated list of URIs, transport methods, and appIds of applications that the Application Router inserts in the ROUTE header of an incoming request. The default list, which routes requests to the Proxy Registrar, is defined as sip::;transport=TCP;lr;appId=proxyregistrar For example: sip:144.
Configuring Application Security Configuring Application Security The deployment descriptor file enables application security through its element. Security is declared per servlet by adding a element to servlets that require authentication and authorization. The element defines servlet authentication.
Configuring Application Security If a SIP client sends a REGISTER request to a server as illustrated in Example 3–4, then a 401 (Unauthorized) message is returned to the client. If the authentication succeeds, then the roles of the user are checked against the role names set in the .
Configuring Application Security 3-6 Oracle Communication and Mobility Server Developer’s Guide
4 Programming Guidelines This chapter describes programming guidelines for SIP Servlet applications in the following sections: ■ Introduction ■ Marking Applications as Distributable ■ Storing Data in Application Sessions ■ Avoiding Static Data ■ Avoiding Blocking Calls ■ Invalidating the SipApplicationSession and SIPSession ■ Monitoring the Memory Usage ■ Avoiding Storing Shared Resources in Sessions ■ Avoiding Creating Threads ■ Creating B2BUA Applications Introduction For an applicatio
Storing Data in Application Sessions Storing Data in Application Sessions All data that must persist for a session must be stored in the SIP Application Session explicitly and must be serializable. Avoiding Static Data As a corollary, to the previous recommendation, avoid using static variables in an application, instead use standard J2EE mechanisms such as EJB or database storage to achieve persistent storage of data that can be made available to another cluster node in the event of a failure.
Creating B2BUA Applications It will clone the request with the following modifications: ■ The From header field of the new request has a new tag chosen by the container. ■ The To header field of the new request has no tag. ■ The Call-ID will be new (or duplicated in sameCallId is true) ■ ■ The Record-Route and Via header fields are not copied. The container will add its own Via header field to the request when it is actually sent outside the application server.
Creating B2BUA Applications 4-4 Oracle Communication and Mobility Server Developer’s Guide
5 Building a SIP Servlet Application This chapter illustrates how to build a SIP Servlet application through OCMS SCE by creating a new project, importing an existing project, or by importing one of the example project provided with OCMS SCE. For more information on the OCMS SCE example projects and other SIP servlets, including source code, refer to Oracle Communication and Mobility Server documents on Oracle Technology Network (http://www.oracle.com/technology/index.html).
SIP Application Development Process Refer to Oracle Communication and Mobility Server Installation Guide for installation instructions. 3. Initializing the OCMS Service Creation Environment, and adding OCMS as a Server in OCMS SCE. Refer to Oracle Communication and Mobility Server Installation Guide. 4. Defining the public and private hosts (for JBoss installations): the Tomcat Web container is configured by default to have two hosts that can be used by any service; a public host and a private host.
Importing an Existing Project 7. Test your application a. Deploy the application to the application server. b. Test and debug the application. Creating a New Dynamic Web Project with SIP Support Perform the following procedure to create a new project in Eclipse for deployment to OCMS: 1. Close the "welcome" window of Eclipse if it is shown. 2. Select the Eclipse Java perspective by selecting Window, Open Perspective, and Java. 3.
Importing Example Projects A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS. Importing Example Projects The section describes how to import and configure the example projects provided by OCMS SCE.
Importing Example Projects Figure 5–1 OCMS SCE Example Projects Importing the Basic Response SIP Application Example Project Perform the following procedure to import the Basic Response example project into Eclipse SCE: 1. Close the "welcome" window of Eclipse if it is shown. 2. Select the Eclipse Java perspective by selecting Window, Open Perspective, and Java. 3.
Importing Example Projects 3. Import the example SIP servlet project by selecting File, New, Project, OCMS SCE, Example Projects, Call Forward SIP Application Example Project. 4. Enter callforward as the project name and click Finish. A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS.
Deploying a SIP Application to OCMS A new Java Project is created in the Package Explorer. Access the Package Explorer by selecting Window, Show View, Package Explorer. To deploy your project, perform the steps described in Deploying a SIP Application to OCMS. Deploying a SIP Application to OCMS Perform the following procedure to deploy SIP applications to OCMS: 1.
Testing an Application 2. Right-click the server in the Servers view and select Publish to start and deploy the SIP applications (Figure 5–3). Figure 5–3 Selecting Publish in the Servers View to Deploy Applications The application is ready to be tested. Testing an Application After you have built and deployed your application you must test its functionality. When starting OCMS the application will automatically be started.
Testing an Application Even if a SIP servlet fails to startup the server will display that it is started. You must view the log file to verify whether the SIP servlet deployed successfully. Note: Testing a Third Party Call Control Servlet To test an application, open a Web browser and navigate to the URL of the application on the OCMS server. For example, to test the Third Party Call Control servlet perform the following steps: 1. Navigate to the following URL http://localhost:8888/tpcc (Figure 5–4).
Testing an Application 5-10 Oracle Communication and Mobility Server Developer’s Guide
6 OCMS Parlay X Web Services This chapter describes OCMS support for the Parlay X 2.0 Presence Web services interfaces for developing applications. The Web service functions as a Presence Network Agent which can publish, subscribe, and listen to notifies on behalf of the users of the Web service.
Installing the Web Services Installing the Web Services The Web services are packaged as a standard .ear file and can be deployed the same as any other Web services through Enterprise Manager. The .ear file contains two .war files that implement the two interfaces. If the Web services are deployed on the same server as the presence server, they must be a child application of the Presence server. Installing the Aggregation Proxy The aggregation proxy is packaged as a standard .
Using the Presence Web Services Interfaces Table 6–1 (Cont.) PresenceConsumer Interface Operation Description startPresenceNotification Not supported. endPresenceNotification Not supported. Table 6–2 PresenceNotification Interface Operation Description statusChanged Not supported. statusEnd Not supported. notifySubscription Not supported. subscriptionEnded Not supported. Table 6–3 PresenceSupplier Interface Operation Description publish Maps directly to a SIP PUBLISH.
Using the Presence Web Services Interfaces // These inputs are required but not used. SimpleReference sr = new SimpleReference(); sr.setCorrelator("unused_correlator"); sr.setInterfaceName("unused_interfacename"); sr.setEndpoint(new URI ("http://unused.com")); // Calling the web service consumer.subscribePresence (new URI ("sip.presentity@test.example.com") , pat, "unused", sr); Interface: PresenceConsumer, Operation: getUserPresence Call this operation to retrieve a subscribed presentity presence.
Using the Presence Web Services Interfaces Interface PresenceSupplier, Operation: publish and Oracle Specific "Unpublish" This is the first operation the application must call before using another operation in this interface. It serves three purposes: ■ It allows the Web services to associate the current HTTP session with a user. ■ It publishes the user’s presence status. ■ It subscribes to watcher-info so that the Web services can keep track of any watcher requests.
Using the Presence Web Services Interfaces // should be used as device note. other1.setName("ServiceNote"); other1.setValue(serviceName); typeValueOther1.setOther(other1); paOther1.setTypeAndValue(typeValueOther1); // The note is not used. Can be anything. paOther1.setNote("OracleExtension"); paOther1.setLastChange(dateTime); //Unpublish Functionality Implemented by OCMS //To perform an "Unpublish", set OtherValue to (Expires, 0) //OtherValue other = new OtherValue(); //other.setName("Expires"); //other.
OCMS Parlay X Presence Custom Error Codes Interface: PresenceSupplier, Operation: getSubscribedAttributes This operation returns only a single item of PresenceTypeAttribute.Activity. An exception will be thrown if there is no existing subscription. Code Example PresenceAttributeType[] pat = getSubscriberdAttributes("sip:watcher@test.example.com"); Interface: PresenceSupplier, Operation: blockSubscription This operation places a watcher into the block list.
OCMS Parlay X Presence Custom Error Codes 6-8 Oracle Communication and Mobility Server Developer’s Guide
A Oracle Diameter Java APIs This appendix describes the Oracle Diameter Java APIs in the following sections: ■ "Diameter Java Base Protocol API" ■ "3GPP/Rf Diameter Java API" ■ "3GPP/Ro DIAMETER JAVA API" ■ "3GPP/Sh Diameter Java API" ■ "Diameter Application Example" Figure A–1 Oracle Diameter Architecture The Base Protocol library is the main element in the picture. It contains the base protocol implementation, and is available as a standalone C++ shared library.
Diameter Java Base Protocol API On its upper side, the Diameter Base Protocol library, provides an application registration mechanism. The specific application subclass AcctApplication can be derived by user depending on the state machine required to be used by the application to be implemented. Each Application object can implement its own session subclass.
Diameter Java Base Protocol API Base Protocol Diameter Java Interface The Diameter Java API is composed of several interfaces: Diameter Factory The DiameterFactory interface is used by the Diameter applications to obtain specific instances of different implementations of all interfaces defined in Diameter Java API. The only instance of the DiameterFactory can be obtained using the getInstance() method.
Diameter Java Base Protocol API The DiameterMessage interface represents a Diameter Message as defined in [RFC 3588]. The Diameter messages are composed from AVPs added by calling add() method. Diameter Session The DiameterSession interface represents a Diameter session as per [RFC 3588]. A Diameter application calls the createClientDiameterSession method from the DiameterProvider interface if it needs to send a request for a new Diameter session.
3GPP/Rf Diameter Java API 3GPP/Rf Diameter Java API This section defines a Java API for the 3GPP [TS 32.299] Rf Interface over the Diameter protocol ([TS 32.225], [TS 32.200] and [TS 32.240] in order to specify). 3GPP/Rf Diameter Java Interface This section describes the Java interface. Rf Provider The DiameterRfProvider interface represents a Rf Diameter Application as defined in 3GPP Interfaces. An instance of a class implementing this interface can be obtained by calling the DiameterStack.
3GPP/Rf Diameter Java API int Accounting-Record-Number, String roleOfNode, String userSessionId, String callingPartyAddress, String calledPartyAddress) ■ Accounting-Answer (ACA)--The first following method creates a basic ACA (with only mandatory AVPs) and the second one creates a more sophisticated ACA with the most used AVPs as defined in 3GPP: ■ Diameter Message createAccountingAnswer (String Result-Code, int Accounting-Record-Type, int Accounting-Record-Number) ■ Diameter Message createAccountingAn
3GPP/Rf Diameter Java API Raise Events To send an accounting event to the Diameter stack, user has to call the accounting application eventRaised(DiameterEvent) method.The only accounting event triggered by the Rf application is DiameterRfOutOfSpaceEvent(Object, int). The different types of event for an DiameterRfOutOfSpaceEvent are: ■ ■ EVT_OUT_OF_SPACE: The event can be triggered by the application to inform the stack that there is no more space to store the received/sent accounting message.
3GPP/Rf Diameter Java API ■ SUPERVISION_TIMER_DURATION ■ INTERIM_INTERVAL ■ REALTIME_REQUIRED The default value of the INTERIM_INTERVAL and REALTIME_REQUIRED options can be overwritten dynamically by the application for a specific session by using the setSessionParameter() method. Rf Application FSM As presented in the [RFC 3588], different types of accounting records are sent depending on the actual type of accounted service.
3GPP/Ro DIAMETER JAVA API RECORD or STOP_RECORD. The reception of an accounting request message including an Accounting-Record-Type AVP value set to STOP_RECORD corresponds to the end of the session. RF Stateful Server FSM This FSM responds to the [RFC 3588] requirements which define the server side state machine that may be followed by applications that require keeping track of the session state at the accounting server.
3GPP/Ro DIAMETER JAVA API Ro Listener The DiameterRoListener interface processes accounting messages that are received by the DiameterRoProviderImpl class implementing the DiameterRoProvider interface. A DiameterRoListener instance is registered to a provider by the following method DiameterRoProvider. setDiameterRoListener (). This interface provides four principles methods: creditControlRequestReceived(), creditControlAnswerReceived(), reAuthRequestReceived() and reAuthAnswerReceived().
3GPP/Ro DIAMETER JAVA API ■ Credit-Control-Answer (CCA) The first following method creates a basic CCA (with only mandatory AVPs) and the second one creates an CCA from an CCR: ■ DiameterMessage createCreditControlAnswer(String resultCode, int authApplicationId, String CCRequestType, int CCRequestNumber) ■ Diameter Message createCreditControlAnswer(String resultCode, DiameterMessage messageCCR) ■ Re-Auth-Request (RAR) This method creates a basic RAR (with only mandatory AVPs) ■ Diameter Message crea
3GPP/Ro DIAMETER JAVA API ■ DiameterServiceEvent(Object, DiameterSession, int): This event is generated by the Diameter implementation when one service is finished. The different reasons to trigger an event for the Rf Interface are: ■ ■ ■ ■ ■ TERMINATE_SERVICE: The event is triggered by the stack when service is terminated by the stack or by server. GRANT_SERVICE: The event is triggered by the stack when service is granted by server.
3GPP/Ro DIAMETER JAVA API ■ TX_TIMER_DURATION ■ TRA_TIMER_DURATION ■ CCFH ■ ENABLE_INVALID_COMMAND ■ ENABLE_SND_MISSING_AVP Ro StateLess Client FSM admits following options setting ■ AUTO_DELETION ■ DDFH ■ TX1_TIMER_DURATION ■ TX2_TIMER_DURATION ■ BACKUP_TIMER_DURATION ■ RETRANSMISSION_INTERVAL ■ RETRANSMISSION_ATTEMPS ■ ENABLE_INVALID_COMMAND ■ ENABLE_SND_MISSING_AVP Ro Application FSM As presented in the [RFC 4006], different types of credit control requests are sent depending
3GPP/Sh Diameter Java API CCA(EVENT_REQUEST) stands for Credit-Control-Answer message with CC-Request-Type AVP set to EVENT_REQUEST. Below are the different types of FSM which can be implemented in Ro application. Ro Stateful Client FSM This FSM responds to the [RFC 4006] requirements which define the session-based credit control client state machine when the first interrogation is executed after the authorization/authentication process.
3GPP/Sh Diameter Java API The Properties parameter specifies the features that will be handled by this Sh provider. This is a list of properties which may contain a number of options. See section [5.2.6] for know more about Sh Application options. Sh Listener The DiameterShListener interface processes Diameter messages that are received by the DiameterShProviderImpl class implementing the DiameterShProvider interface.
3GPP/Sh Diameter Java API DiameterMessage createPushNotificationAnswer(String resultCode) ■ Subscribe-Notification-Request (SNR) DiameterMessage createSubscribeNotificationRequest(String destinationRealm, String userIdentity, String dataReference, String subsReqType) DiameterMessage createSubscribeNotificationRequest(String destinationRealm, String userIdentity, String dataReference, String subsReqType, String serviceIndication, String serverName) ■ Subscribe-Notification-Answer (SNA) DiameterMessage cr
Diameter Application Example Sh Application Options These options specify the features handled by the accounting Application. This is a list of Properties (see java.util.properties) which may contain a number of options.
Diameter Application Example The network element (acting as client) sends an Accounting-Request (ACR) with Accounting-Record-Type AVP set to EVENT_RECORD to indicate service specific information to the CDF (acting as server). The server processes the received Accounting-Request and returns an Accounting-Answer (ACA) message with Accounting-Record-Type AVP set to EVENT_RECORD to the client.
Diameter Application Example Figure A–5 Rf Provider Creation 3. Create my Rf Provider, an instance of DiameterRfProvider, using the following method: myStack.createDiameterRfProvider(). The instantiation is done with the application name matching the one configured in the xml dictionary, and attach it to a listener so that it receives all incoming messages. Among the parameters passed during the provider creation, properties is a set of accounting options previously defined at the section [3.2.
Diameter Application Example Figure A–7 Routes and Listening Points Creation 6. Create a listening Point from a LocalURI, an instance of DiameterListeningPoint, using the following method: myStack.createDiameterListeningPoint() 7. Create a route configuration using the following method: myStack.createDiameterRoute() but it’s not mandatory for server process, if the isUnknownPeerAuthorized() callback is implemented in the listener.
Diameter Application Example Figure A–9 ACR Reception 10. Create a client diameter session, an instance of DiameterSession, by using the method: createClientDiameterAcctSession(). 11. Send the created Accounting-Request (ACR) myACR to the server side by using the method: sendMessage(). 12. Process an incoming Accounting-Request (ACR) message contained in the received event by using the following method: accountingRequestReceived(event). Create a server session from the received request.
Diameter Application Example Figure A–11 ACA Reception 15. Send the created Accounting-Answer myACA to the client side. 16. Process the incoming Accounting-Answer (ACA) message contained in the received event by using the method: accountingAnswerReceived(event). Cleaning In the last step, a global cleaning of all created routes, providers and listening points is done. Figure A–12 Cleaning Up of Routes, Providers, and Listening Points 17.
B Programming Oracle Diameter Applications This appendix describes programming Oracle Diameter applications in the following sections: ■ "IP and Routes Configuration" ■ "Counters Management" ■ "Dictionary" ■ "Tracing and Logging Mechanism" IP and Routes Configuration Before a Java Diameter application is able to process messages exchanged with a distant peer, the IP configuration and Diameter protocol-specific configuration have to be done by the application as follows: 1.
IP and Routes Configuration String localURI = "aaa://server.realm.domain.com:41001"; myStack.createDiameterListeningPoint(localURI); As soon as the listening point has been created, the Diameter stack is ready to accept incoming connection from remote peers. If the Diameter stack receives a connection request from a peer that as not been declared in the routing table, then the isUnknownPeerAuthorized() of the DiameterListener interface is called.
Counters Management and application ID. Since the route is not available, the application is not able to exchange messages with the remote realm peers. Example B–2 illustrates a typical implementation of the DiameterListener.processEvent() method. Example B–2 Implementing the DiameterListener.
Counters Management Managing a Diameter Application with MBeans A Diameter Application can be managed remotely by registering the Diameter MBeans to a JMX agent and can be monitored by using the Java JConsole program. Registering the Diameter MBeans A Java application using the Diameter API can publish management information by registering instances of the DiameterStackImplMBean and DiameterProviderImplMBean interfaced to a JMX agent. This can be done as follows: import javax.management.
Dictionary And then select the application's JVM from the local list. The Diameter MBeans should be visible under the MBeans tab. Dictionary This section includes the following topics: ■ "Dictionary Composition" ■ "Dictionary Extension" Dictionary Composition When a user’s application requires using commands or AVPs that are not defined in the default loaded application dictionary, the user can extend the dictionary to define new commands and/or AVPs syntaxes to be used by the Diameter stack.
Dictionary The attributes are: 1. The application id attribute is the IANA-assigned Application Identifier for this application. The value 0 is dedicated to the base protocol which corresponds to the commands defined in RFC-3588 and RFC-4006. 2. The application name attribute is the human-readable name of this application. 3. The application vendor attribute is the name of the application vendor as previously defined in the element. 4.
Dictionary Example B–7 Defining the Element .... avp Element The element defines an AVP as described in RFC-3588. The attributes are: 1. The avp name attribute is the human-readable name of this AVP. 2. The avp code attribute defines the integer value used to encode the AVP for transmission on the network. 3.
Dictionary ■ "UNSIGNED32" ■ "UNSIGNED64" ■ "FLOAT32" ■ "FLOAT64" ■ "ADDRESS" ■ "IPADDRESS" ■ "TIME" ■ "UTF8STRING" ■ "DIAMETERIDENTITY" ■ "DIAMETERURI" ■ "IPFILTERRULE" ■ "QOSFILTERRULE" ■ "ENUMERATED" ■ "GROUPED" Note: These values are case-sensitive. In Example B–9, the AVP "Application-provided-called-party-address" is an UTF8String.
Dictionary Example B–10 Defining the Element grouped Element The element defines an AVP which encapsulates a sequence of AVPs together as a
Tracing and Logging Mechanism " \n" " \n" " \n" " \n" " \n" "\n"; + + + + + + //--> Apply new extension to current dictionary try { myStack . extendGrammar(myDictionary); } catch (DiameterException e) { // Handle dictionary syntax errors ...
Tracing and Logging Mechanism // ... } public void trace (String file, int line, int mask, String message) { System.err.println(...
Tracing and Logging Mechanism B-12 Oracle Communication and Mobility Server Developer’s Guide
C Accounting Event API This appendix describes the OCMS Accounting Event API, in the following sections: ■ Introduction ■ logEvent(SipServletRequest req, Map additional) Method ■ logEvent(SipServletResponse resp, Map additional) Method ■ logEvent(Map event, String category) Method ■ Event Processing in Log4j Introduction OCMS provides the Accounting Event API, an interface to create SIP event data that can be used for accounting and charging.
logEvent(SipServletRequest req, Map additional) Method Example C–1 Logging Events in the EventLogger Interface public interface EventLogger { public void logEvent(SipServletRequest req, Map additional); public void logEvent(SipServletResponse resp, Map additional); public void logEvent(Map event, String category); public boolean isEnabled(SipServletRequest req); public boolean isEnabled(SipServletResponse resp); public boolean isEnabled(String
logEvent(Map event, String category) Method logEvent(SipServletResponse resp, Map additional) Method The public void logEvent(SipServletResponse resp, Map additional) method logs an event with the characteristic response attributes listed in Table C–2 with any additional event attributes provided. The event will be logged to the following full Log4j category name: "eventlogger." + loggerName + ".RESPONSE." + method + "." + statuscode.
Event Processing in Log4j Table C–3 Method Attributes of the logEvent(Map event, String category) Attribute Key Description of attribute value Service The name of the service generating the event (that is, the full Log4j category name). The isEnabled method returns true only if the Log4j filter is configured so that a call to logEvent method with the same argument is logged.
Event Processing in Log4j Event Filtering By uncommenting or commenting categories in the Log4j configuration file (log4j.xml), events can be enabled or disabled as illustrated in Example C–3. The Log4j configuration determines which events generated from the servlets are logged to the event.log file. Example C–3 illustrates a Log4j configuration for displaying 200 (OK) responses to INVITE and BYE requests from the EventTestServlet. These responses are logged to the event.log file.
Event Processing in Log4j Example of BasicLayout Output Each attribute is displayed in a separate row with the key in bold text. REQUEST.INVITE: CreationTime=2005-04-15T07:50:51.767Z, To=;tag=0f54d930-f916-4702-8293-d8b014810a29, TimeZoneOffset=120, Method=INVITE, Content-Type=application/sdp, Service=eventlogger.com.example.EventTestServlet.REQUEST.
Index A Accounting API, C-4 Accounting Event API, C-1 Aggregation Proxy, 6-2 appId, 3-1 Application Router configuring, 3-1 applications, 2-5 default, 2-19 testing of, 5-8 asynchronous send method, 2-20 authentication, 2-21 B Back to Back User Agent, Basic Response, 5-4, 5-5 2-1, 4-2 C H Call Forward, 5-4, 5-5 classes SipServletRequest, 2-8 SipServletResponse, 2-8 classes and methods, 2-7 headers, 2-9, 2-11 HTTP X-3GPP-ASSERTED-IDENTITY, 6-2 HTTP, 2-20 HTTPS, 6-2 I D deployment descriptor, 2-2, 2-5,
Log4j, C-4 event filtering, C-5 event formatting and destination, event logging attributes, C-5 event processing, C-4 logEvent method, C-2 logging, C-5 logging events to a file, C-5 M memory usage, 4-2 MESSAGE requests, 2-7 Message Sender, 5-4, 5-6 messages, 2-8 methods addAddressHeader, 2-10 createRequest, 2-3 createResponse, 2-9 doAck, 2-8 doBye, 2-8 doCancel, 2-8 doErrorResponse, 2-8 doInfo, 2-8 doInvite, 2-8 doMessage, 2-8 doNotify, 2-8 doOptions, 2-8 doPrack, 2-8 doProvisionalResponse, 2-8 doPublish,
servlet context, 2-2 servlet mapping, 2-7 servlets, 2-4 session configuration values, 2-5 session attributes, 2-12 shared resources, 4-2 SIP, 2-5 applications, 2-5, 2-7 testing of, 5-8 headers, manipulating, 2-9 messages, 2-8 request or response content, 2-9 requests, 2-8 responses, 2-9 servlet mapping, 2-7 servlets, 2-4, 2-5, 2-7 session data, 2-20 transactions, 2-3 SIP Application Manager, 2-6 SIP Application Sessions, 2-3 SIP Applications addressing, 3-1 SIP Container, 2-2, 2-5, 3-1 processing initial re
Index-4
