Rhino SIP Servlet Overview and Concepts

Transcription

1 Rhino SIP Servlet Overview and Concepts TAS-153-Issue Release 1 August 2018

2 Notices Copyright 2017 Metaswitch Networks. All rights reserved. This manual is issued on a controlled basis to a specific person on the understanding that no part of the Metaswitch Networks product code or documentation (including this manual) will be copied or distributed without prior agreement in writing from Metaswitch Networks. Metaswitch Networks reserves the right to, without notice, modify or revise all or part of this document and/or change product features or specifications and shall not be responsible for any loss, cost, or damage, including consequential damage, caused by reliance on these materials. Metaswitch and the Metaswitch logo are trademarks of Metaswitch Networks. Other brands and products referenced herein are the trademarks or registered trademarks of their respective holders. 2

3 Contents 1 Rhino SIP Servlet Overview and Concepts Topics Architecture SIP Servlet resource adaptor Container services Management tools Developing a SIP Servlet Application Package as a "SAR" file Deploy with console or Ant commands SIP Servlet 1.1 Resource Adaptor Type Activities SipApplicationSession SipSession Events Interfaces SipFactory SipSessionsUtil ActivityContextInterface Hybrid Applications Participating in application selection Hybrid application example Application Naming Automatic application naming Manual application naming Application Router Default application router Custom application routers SLEE Resource Adaptor Support How do applications access the RAs? Dependencies RA Type Bindings Package declaration for an application

4 1 Rhino SIP Servlet Overview and Concepts This document introduces features and concepts behind Rhino SIP Servlet, a SIP Servlet 1.1 JSR 289 container that runs on the OpenCloud Rhino SLEE. 1.1 Topics Architecture Developing a SIP Servlet Application SIP Servlet 1.1 Resource Adaptor Type Hybrid Applications Application Naming Application Router SLEE Resource Adaptor Support Example Applications An architectural overview of Rhino SIP Servlet How to develop applications with Rhino SIP Servlet What s in the Rhino SIP Servlet resource adaptor type How to write hybrid applications How Rhino SIP Servlet manages application naming Rhino SIP Servlet s application router support How to use SLEE resource adaptors in SIP Servlet applications SIP Servlet example applications. Other documentation for the Rhino SIP Servlet including the changelog and links to downloads, can be found on the Rhino SIP Servlet product page. 4

5 2 Architecture Below is a high-level diagram, followed by descriptions, of the main components of Rhino SIP Servlet. Users can provide the items colored yellow, in the SIP Servlet resource adaptor on page 5, container services on page 6 and management tools on page SIP Servlet resource adaptor The SIP Servlet RA is a SLEE resource adaptor providing the core of the Rhino SIP Servlet platform, including: a SIP transport layer for communicating with other SIP nodes on the network mapping of SIP network messages to and from the SIP Servlet API s SipServletRequest and SipServletResponse application selection using the Application Router on page 18 component Proxy, SipSession, and SipApplicationSession implementation management interfaces (MBeans) for configuration and deployment. The RA implements a SLEE resource adaptor type (RA type) that wraps the SIP Servlet 1.1 API. The RA type defines the events and activities that may be used by SLEE services. The SIP Servlet Container Service uses the SIP Servlet RA type when it wraps a servlet application (as described below), but may 5

6 also be used directly by native SLEE applications. See SIP Servlet 1.1 Resource Adaptor Type on page 8 and Hybrid Applications on page Container services The SIP Servlet Container Service is a SLEE service that wraps a SIP Servlet application, for deployment into the SLEE platform. When a SIP Servlet application is deployed, Rhino SIP Servlet generates a new container service that contains the SIP Servlet application, and deploys it in the SLEE. The diagram above shows two services, each of which represents a separate SIP Servlet application. The container service is responsible for providing the runtime environment required by a servlet application. It manages the ServletContext and servlet lifecycle, so is responsible for creating and destroying the servlet application s servlet and listener instances. The service will invoke the appropriate servlet methods when certain events are received from the RA, such as SIP requests or responses, ServletTimer events, SipApplicationSession, or SipSession events. The container services and SIP Servlet RA cooperate to provide a complete SIP Servlet 1.1 environment for servlet applications. 2.3 Management tools You manage Rhino SIP Servlet using JMX MBeans. The distribution includes console commands and Ant tasks for installing and uninstalling servlet applications, and configuring the platform. See the Installation and Administration Guide for details. Limitation: converged container support SIP Servlet 1.1 allows "converged containers" servlet containers that support SIP and HTTP servlets within the same application. Rhino SIP Servlet is not a converged container, it currently only supports SIP servlets. HTTP servlet and converged container support may be added in a future release. 6

7 3 Developing a SIP Servlet Application Developers who are already familiar with writing SIP Servlet applications need not change anything just to use Rhino SIP Servlet. They can continue to develop and test servlet applications using their existing tools, IDEs, and so on. Developers new to SIP Servlet should review the SIP Servlet 1.1 specification ( JSR 289 ) to get started and experiment with Rhino SIP Servlet s example applications. 3.1 Package as a "SAR" file SIP Servlet applications are packaged as a SAR (SIP Servlet ARchive) file, which like other SLEE or Java EE archive file types, is a JAR file containing the application s classes, resources and a deployment descriptor, sip.xml. The SAR file layout looks like this: WEB-INF/sip.xml # Deployment descriptor WEB-INF/classes/... # Application classes (servlets, listeners etc) WEB-INF/lib/... # Third-party libraries (jar files) 3.2 Deploy with console or Ant commands Once an application has been packaged as a SAR file, it can be installed into Rhino SIP Servlet using the install-ss (console) or <sipservlet:install> (Ant) commands. See Application Deployment in the Installation and Administration Guide. Unlike many other servlet containers, a newly-deployed Rhino SIP Servlet application is not automatically activated. Instead, it is deployed as a SLEE service, which requires an extra activation step before the SLEE will begin firing events to the service. You can activate the service using standard rhino-console commands, or the <sipservlet:activate> Ant task. 7

8 4 SIP Servlet 1.1 Resource Adaptor Type A SLEE resource adaptor type (RA Type) is a specification of the SLEE activities on page 8, events on page 9 and interfaces on page 12 that a resource adaptor (RA) implements. Rhino SIP Servlet includes an RA type for the SIP Servlet 1.1 API, which adapts the SIP Servlet API for use by SLEE applications. Developers of pure SIP Servlet applications may skip this section, as the Container services on page 6 hides these details from SIP Servlet applications. This section is useful to those developing Hybrid Applications on page 15 (SLEE applications directly on top of the SIP Servlet RA type). 4.1 Activities The SIP Servlet RA type defines SIP Servlet SipApplicationSession on page page and SipSession on objects as SLEE activities. This means that SBBs may attach to them, use CMP attributes on their activity context interfaces, set timers, or use the Activity Context Naming Facility SipApplicationSession The SIP Servlet creates SipApplicationSession activities automatically when it receives a new initial request for an application. An application can also create a new SipApplicationSession using SipFactory.createApplicationSession(). The SipApplicationSession activity ends when the session becomes invalidated in SIP Servlet 1.1, by: calling SipApplicationSession.invalidate() session expiration invalidate-when-ready is enabled and all SipSessions are ready to invalidate SipSession The SIP Servlet RA type creates SipSession activities when it receives new requests, or when an application sends an outgoing request using the SipFactory.createRequest() methods. SipSession activities end when the session becomes invalidated in SIP Servlet 1.1, by: calling SipSession.invalidate() session expiration invalidate-when-ready is enabled and the SipSession is ready to invalidate (for example, a dialog-ending request has been sent or received). 8

9 4.2 Events The SIP Servlet RA Type defines events that correspond to SIP Servlet s request-and-response callbacks, and also several listener events summarized below. EventTypeID (Name, Vendor, Version) SIP Servlet equivalent.invite, OpenCloud, 1.1 SipServlet.doInvite().ACK, OpenCloud, 1.1 SipServlet.doAck().CANCEL, OpenCloud, 1.1 SipServlet.doCancel().BYE, OpenCloud, 1.1 SipServlet.doBye().OPTIONS, OpenCloud, 1.1 SipServlet.doOptions().REGISTER, OpenCloud, 1.1 SipServlet.doRegister().INFO, OpenCloud, 1.1 SipServlet.doInfo().PRACK, OpenCloud, 1.1 SipServlet.doPrack().UPDATE, OpenCloud, 1.1 SipServlet.doUpdate().MESSAGE, OpenCloud, 1.1 SipServlet.doMessage().SUBSCRIBE, OpenCloud, 1.1 SipServlet.doSubscribe().NOTIFY, OpenCloud, 1.1 SipServlet.doNotify() Description Class An INVITE request was received. An ACK request was received. A CANCEL request was received. A BYE request was received. An OPTIONS request was received. A REGISTER request was received. An INFO request was received. A PRACK request was received. An UPDATE request was received. A MESSAGE request was received. A SUBSCRIBE request was received. A NOTIFY request was received. 9

10 .REFER, OpenCloud, 1.1 SipServlet.doRefer().PUBLISH, OpenCloud, 1.1 SipServlet.doPublish().UNKNOWN, OpenCloud, 1.1 SipServlet.doRequest() A REFER request was received. A PUBLISH request was received. A request with an unrecognized method was received. Use SipServletRequest.ge tmethod() to obtain the method. javax.servlet.sip.sipservletresponse.provisional, A provisional ( ) response was received. OpenCloud, 1.1 SipServlet.doProvisi javax.servlet.sip.sipservletresponse onalresponse() javax.servlet.sip.sipservletresponse.success, OpenCloud, 1.1 SipServlet.doSuccess Response() javax.servlet.sip.sipservletresponse.redirect, OpenCloud, 1.1 javax.sipservlet.dor edirectresponse() javax.servlet.sip.sipservletresponse.error, OpenCloud, 1.1 SipServlet.doErrorRe sponse() javax.servlet.sip.siperrorevent.noackreceived, OpenCloud, 1.1 SipErrorListener.noA ckreceived() javax.servlet.sip.siperrorevent.noprackreceived, OpenCloud, 1.1 SipErrorListener.noP rackreceived() A success ( ) response was received. javax.servlet.sip.sipservletresponse A redirect ( ) response was received. javax.servlet.sip.sipservletresponse An error ( ) response was received. javax.servlet.sip.sipservletresponse An OK response to an earlier INVITE was sent, but the ACK was never received (after 32s). javax.servlet.sip.siperrorevent A reliable provisional response was sent, but the PRACK was never received (after 32s). javax.servlet.sip.siperrorevent javax.servlet.sip.sipapplicationsessionevent.created, A new SipApplicationSession was created. OpenCloud, 1.1 SipApplicationSessio javax.servlet.sip.sipapplicati nlistener.sessioncreated() onsessionevent javax.servlet.sip.sipapplicationsessionevent.created, A new SipApplicationSession was created. OpenCloud, 1.1 SipApplicationSessio javax.servlet.sip. SipApplicat nlistener.sessioncreated() ionsessionevent 10

11 javax.servlet.sip.sipapplicationsessionevent.expired, A SipApplicationSession has expired. OpenCloud, 1.1 SipApplicationSessio javax.servlet.sip.sipapplicati nlistener.sessionexpired() onsessionevent javax.servlet.sip.sipapplicationsessionevent.expired, A SipApplicationSession has expired. OpenCloud, 1.1 SipApplicationSessio javax.servlet.sip. SipApplicat nlistener.sessionexpired() ionsessionevent javax.servlet.sip.sipapplicationsessionevent.readytoinvalidate, A SipApplicationSession has become ready to OpenCloud, 1.1 SipApplicationSessio invalidate. nlistener.sessionreadytoinvalidate() javax.servlet.sip.sipapplicati onsessionevent javax.servlet.sip.sipapplicationsessionevent. ReadyToInvalidate, OpenCloud, 1.1 SipApplicationSessionListener. sessionreadytoinvalidate() javax.servlet.sip.sipsessionevent.created, OpenCloud, 1.1 SipSessionListener.s essioncreated() A SipApplicationSession has become ready to invalidate. javax.servlet.sip. SipApplicat ionsessionevent A new SipSession was created. javax.servlet.sip.sipsessionevent javax.servlet.sip.sipsessionevent.readytoinvalidate, A SipApplicationSession has expired. OpenCloud, 1.1 SipSessionListener.s javax.servlet.sip.sipsessionevent essioncreated() javax.servlet.sip.sipsessionevent.invalidate, OpenCloud, 1.1 SipApplicationSessio nlistener.sessionreadytoinvalidate() javax.servlet.sip.sipsessionevent.invalidate, OpenCloud, 1.1 SipApplicationSessio nlistener. SessionReadyToInvalidate() A SipApplicationSession has become ready to invalidate. javax.servlet.sip.sipsessionevent A SipApplicationSession has become ready to invalidate. javax.servlet.sip.sipsessionevent Some things to note about SIP Servlet events Initial requests and mid-dialog requests have the same event type. The application must distingush between them using SipServletRequest.is Initial(), just as SIP servlets do. All events above are fired on the SipApplicationSession activity. Events that relate to a particular SipSession are still fired on the SipApplica tionsession, but the SipSession can always be retrieved from the event object. The decision to fire all events on the SipApplicationSession was 11

12 made only to avoid scenarios where the same event type could have been fired on either type of activity, depending on what made sense in particular circumstances. Just firing on the SipApplicationSession makes it simpler for the developer to reason about the events. There are no ServletTimer events, as the same functionality is already provided by the SLEE TimerFacility. There are no "session destroyed" events. The SLEE ActivityEndedEvent can be used for the same purpose. SipServletListener.servletInitialized() and the session attribute listeners are not part of this RA type. However they are implemented by the container service when running SIP Servlet applications. 4.3 Interfaces The SIP Servlet RA type specifies these intefaces: SipFactory on page SipSessionsUtil on page and ActivityContextInterface on page. (the SBB Interface), SipFactory The SIP Servlet SipFactory interface is this RA Type s SBB interface. An instance of SipFactory is bound in the SBB s JNDI environment when the SBB declares an RA Type binding in their sbb-jar.xml deployment descriptor: <resource-adaptor-type-binding> <resource-adaptor-type-ref> <resource-adaptor-type-name>sip Servlet RA Type</resource-adaptor-typename> <resource-adaptor-type-vendor>opencloud</resource-adaptor-type-vendor> <resource-adaptor-type-version>1.1</resource-adaptor-type-version> </resource-adaptor-type-ref> <activity-context-interface-factory-name>slee/resources/sipservlet/ activitycontextinterfacefactory</activity-context-interface-factory-name> <resource-adaptor-entity-binding> <resource-adaptor-object-name>slee/resources/sipservlet/provider</ resource-adaptor-object-name> <resource-adaptor-entity-link>slee/resources/sipservlet</resourceadaptor-entity-link> </resource-adaptor-entity-binding> </resource-adaptor-type-binding> In the above example, the SipFactory is bound to the name "slee/resources/sipservlet/provider". An SBB object can retrieve the SipFactory as follows: public abstract class MySipSbb implements Sbb { private SipFactory sipfactory; public void setsbbcontext(sbbcontext context) { 12

13 try { Context env = (Context) new InitialContext().lookup("java:comp/ env"); this.sipfactory = (SipFactory) env.lookup("slee/resources/ sipservlet/provider"); } catch (NamingException e) {... } } } SipSessionsUtil The SipSessionsUtil interface is made available to SBBs using a separate RA Type. To access SipSessionsUtil, SBBs must declare the following RA Type binding (in addition to the SIP Servlet RA Type as shown above): <resource-adaptor-type-binding> <resource-adaptor-type-ref> <resource-adaptor-type-name>sip Servlet-sessionsutil RA Type</resourceadaptor-type-name> <resource-adaptor-type-vendor>opencloud</resource-adaptor-type-vendor> <resource-adaptor-type-version>1.1</resource-adaptor-type-version> </resource-adaptor-type-ref> <resource-adaptor-entity-binding> <resource-adaptor-object-name>slee/resources/sipservlet/ sessionsutilprovider</resource-adaptor-object-name> <resource-adaptor-entity-link>slee/resources/sipservlet</resourceadaptor-entity-link> </resource-adaptor-entity-binding> </resource-adaptor-type-binding> and obtain the reference from JNDI: public abstract class MySipSbb implements Sbb { private SipFactory sipfactory; private SipSessionsUtil sessionsutil; public void setsbbcontext(sbbcontext context) { try { Context env = (Context) new InitialContext().lookup("java:comp/ env"); this.sipfactory = (SipFactory) env.lookup("slee/resources/ sipservlet/provider"); this.sessionsutil = (SipFactory) env.lookup("slee/resources/ sipservlet/sessionsutilprovider"); } catch (NamingException e) {... } } } 13

14 4.3.3 ActivityContextInterface The ActivityContextInterface factory interface for the SIP Servlet RA Type is com.opencloud.sipservlet.ratype.sipservletactivitycontextinterfacefactory : public interface SipServletActivityContextInterfaceFactory { public ActivityContextInterface getactivitycontextinterface(sipsession session) throws UnrecognizedActivityException, FactoryException; public ActivityContextInterface getactivitycontextinterface(sipapplicationsession session) throws UnrecognizedActivityException, FactoryException; } 14

15 5 Hybrid Applications As well as writing pure SIP Servlet applications, developers can use Rhino SIP Servlet to write hybrid applications : SLEE services that use the SIP Servlet RA Type API. This means they can make use of the nice features in the SIP Servlet API (such as built-in proxying), while also using the SLEE component model (SBBs, events, activities, activity contexts, and so on). 5.1 Participating in application selection Hybrid applications can take part in the application-selection process, controlled by the Application Router on page 18. SIP Servlet and hybrid applications can be composed together on the same SIP call. Hybrid applications are normal SLEE services, so are identified by their ServiceID. The Application Router uses application names to refer to the applications it selects. When deploying a hybrid application, the deployer must also manually create an application name on page 16 so that the Application Router can select it. 5.2 Hybrid application example The examples/proxy-hybrid directory in the Rhino SIP Servlet package contains an example SLEE service that uses the SIP Servlet API to implement a simple proxy. Run ant deploy in the examples/proxy-hybrid directory to deploy the service. Note that the service does not perform any SIP registration lookups; it simply forwards requests to the next hop. 15

16 6 Application Naming Applications deployed in a SIP Servlet container are identified using their application name, a string. The application developer or deployer sets the application name in the <app-name> element of the sip.xml deployment descriptor, or by using annotation s name attribute. The container uses the application name as the unique identifier for the application, and the application router uses application names when selecting the applications to run. Rhino SIP Servlet runs on the Rhino SLEE platform, and SIP Servlet applications are deployed as SLEE services. SLEE services are uniquely identified by their ServiceID, an identifier containing service name, vendor, and version strings. When the application router determines the next application to invoke, it returns the application name to the container. But in this case the "container" is the SIP Servlet RA, which must translate the name to a SLEE ServiceID, so that it can trigger the SLEE service containing the servlet application. For this reason, the SIP Servlet RA maintains a table that maps SIP Servlet application names to SLEE ServiceIDs, and vice versa. These mappings are called application name references in the Rhino SIP Servlet documentation. The SIP Servlet RA ensures a one-to-one mapping between application names and ServiceIDs. So it s impossible for more than one application name to map to the same ServiceID, or for more than one ServiceID to map to the same application name. 6.1 Automatic application naming When SIP servlet applications are installed using Rhino SIP Servlet s management commands ( install-ss (console) or <sipservlet:install> (Ant)), the SIP Servlet RA generates a SLEE service that wraps the servlet application. During deployment, the RA automatically creates an application name reference that maps the application name to the new service s ServiceID. 6.2 Manual application naming It s also possible to manually create application name references. This is only required when deploying Hybrid Applications on page 15, which are traditional SLEE services that use the SIP Servlet RA Type. These are deployed using Rhino s normal installation commands, bypassing the SIP Servlet RA s servlet deployment mechanisms. In this case it is necessary to manually setup the application name references, so that the application router can refer to hybrid applications by their servlet application names. If a SLEE service has no application name, it cannot be invoked by the SIP Servlet RA. 16

17 Application name references are managed using the createapplicationnameref, replaceapplicationnameref and removeapplicationnameref console commands, and corresponding Ant tasks. See the Installation and Administration Guide for details and examples. 17

18 7 Application Router SIP Servlet 1.1 specifies the Application Router component. The Application Router is responsible for selecting the SIP Servlet applications that will process an initial request. In other words, it determines how applications are composed. The servlet applications themselves do not have any knowledge of the Application Router, so they can be developed independently, and then composed together at deployment time, by configuring the Application Router for a particular scenario. The Application Router is, by design, a separate component to the SIP Servlet container. This means that users are free to use third-party Application Routers, or write their own. An Application Router may use any criteria for selecting applications, such as source or destination addresses, SIP header fields, time of day, database lookup, and so on. All SIP Servlet 1.1 containers must provide a Default Application Router, which is specified in SIP Servlet 1.1 Appendix C. Rhino SIP Servlet includes a Default Application Router, and users may also deploy their own. 7.1 Default application router The default application router (DAR) supplied with Rhino SIP Servlet implements the behaviour specified in SIP Servlet 1.1 Appendix C. It is configured using the properties file format described in the appendix. Configuration files are installed in the DAR using Rhino SIP Servlet s console or Ant commands. A DAR configuration file is a properties file, where each line begins with a SIP request method (such as INVITE, REGISTER), followed by a list of applications that will process that type of request. For example: REGISTER: ("Registrar", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "0"), ("Presence", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "1") INVITE: ("CallBarring", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "0"), ("LocationServiceProxy", "DAR:From", "ORIGINATING", "", "NO_ROUTE", "1") This says that REGISTER requests will be processed by the "Registrar" application, then the "Presence" application. INVITE requests will trigger the "CallBarring" application, then the LocationServiceProxy" application. (The other arguments are described in SIP Servlet 1.1 Appendix C.) The installed DAR configuration is used for all initial requests; there is no support for conditional or peruser rules. 7.2 Custom application routers A custom application router can be used if more advanced application composition logic is required, such as subscriber lookup, or inspecting SIP header fields. See the Installation and Administration Guide for information on installing custom Application Routers. 18

19 8 SLEE Resource Adaptor Support Servlet applications deployed on Rhino SIP Servlet can use any SLEE Resource Adaptor (RA) deployed in the platform. The SLEE uses RAs to talk to external resources. They may implement any protocol. For example, OpenCloud provides RAs for SIP, HTTP, SS7 (CAP/INAP), Diameter, and many others. SIP Servlet applications running on Rhino SIP Servlet can use these RAs just like any other SLEE application, so servlets are not just limited to communicating using SIP. 8.1 How do applications access the RAs? Servlet applications need to use a subset of the SLEE API to access SLEE RAs. The SLEE specification defines how SLEE applications declare which RAs they need, how events are received from RAs, and how to access an RA s interface to interact with external resources. Rhino SIP Servlet provides the sipservlet-slee API that bridges between the SIP Servlet and SLEE containers. This allows servlet applications to use RAs in the same way as SLEE applications, without leaving the SIP Servlet application environment. The following sections describe how a servlet application can be enhanced to use SLEE RAs: Dependencies on page 20 RA Type Bindings on page 21 Resource Injection on page Activities and Activity Contexts on page Event Handling on page Converged Applications on page SLEE Libraries on page 19

20 9 Dependencies A servlet application using SLEE RAs has the following compile-time dependencies, which may be found under lib/ in the Rhino SIP Servlet distribution. slee-1.1.jar and jta-1.0.1b.jar the JAIN SLEE 1.1 API jars sipservlet-slee- <version>.jar interfaces to bridge between SLEE and SIP Servlet slee-annotations- <version>.jar annotations for declaring which SLEE RA types and events are required by an application. The actual version numbers may vary in different releases, so they are not shown above. The Ant build file common.xml defines the path reference sipservlet.api.classpath, which contains the SIP Servlet 1.1 API and the jars above. If using Ant, your own project can be compiled simply by importing common.xml and using the path reference: <import file="/path/to/rhino-sip-servlet/common.xml"/> </javac> Alternatively, make these jars available as appropriate for your own build environment. At runtime these dependencies are provided by the Rhino SIP Servlet platform, so do not need to be packaged with the servlet application. You will also need to provide the resource adaptor type jars and any other jars required by the particular RA types your application needs. These will usually be found in the distribution package for each RA. The RA types and RAs will be deployed separately in the SLEE, and do not need to be bundled with the servlet application. 20

21 10 RA Type Bindings Before an RA can be used, the application must declare a binding to an RA type. A resource adaptor type (RA type) is a SLEE component that specifies the interface between an RA and SLEE applications. It defines: the event types that may be fired by the RA the types of activities created by the RA the RA interface (a Java interface) that applications may call to use the RA the activity context interface factory interface (see below). When an application declares a binding to an RA type, Rhino ensures that the RA type s classes (and their dependencies) are available in the application s classloader, and any interfaces provided by the RA type are bound into JNDI at locations specified by the application in the binding. The same RA type may be implemented by more than one RA, and there may also be more than one instance of an RA ( RA entity in SLEE terms) deployed at a time. For example, there may be multiple HTTP RA entities deployed, each listening on a different port. So the the application s RA type binding can also specify which RA entity (or entities) it wants to use Package declaration for an application To declare an RA type binding, a servlet application uses annotation on a package. RA Type bindings apply to the entire application, so it makes sense to annotate the same package is declared (if using SIP Servlet annotations), or the top-level package of the application. must only be specified on one package in the application. Here is the package declaration for an example = "example", mainservlet = "HTTP", vendor = "OpenCloud", version = "2.2"), activitycontentinterfacefactoryname = "slee/resources/http/ acifactory", resourceadaptorentitylink = "slee/resources/http", resourceadaptorobjectname = "slee/resources/http/provider") }) package com.example.app; import com.opencloud.sipservlet.slee.annotation.sleeratypes; import javax.servlet.sip.annotation.sipapplication; import javax.slee.annotation.*; 21

22 Here the application is declaring a binding to the OpenCloud HTTP 2.2 RA type. This is an actual RA type, and is included with the example application in examples/http-example/. The various elements that make up the This annotation is the "container" for one or elements. If an application uses several RA types, then they must all be defined inside a element. Order is not significant. The start of an RA type binding declaration. ratype = " ", vendor = " ", version = " ") activitycontentinterfacefactoryname = " " resourceadaptorentitylink = " " resourceadaptorobjectname = " " This attribute specifies the RA type s component ID, a triple of name, vendor, and version strings. All SLEE components are identified in this way. At deploy time, this must match an RA type that is deployed in the SLEE. Optional. This attribute specifies the JNDI object name for the RA type s activity context interface factory interface. This is required if the application wants to attach to activities created by an RA, which is often the case. See [7.4 Activities and Activity Contexts]. Optional. Identifies the link name of an RA entity. This is a reference to an RA entity deployed in the SLEE. The link name may be anything, but must be configured (using SLEE management commands) to point to an actual RA entity in the SLEE before the application is deployed. Optional. This attribute specifies the JNDI object name for the RA interface provided by the RA entity linked to as above. This object implements the RA interface as defined by the RA type. This annotation marks those classes in the application that may receive SLEE events. Servlet and Listener classes may use this annotation

23 @EventMethod Marks an event handler method. The SLEE invokes this method when a matching event is received eventtype = " ", vendor = " ", version = " ") Like other SLEE components, event types are identified by name, vendor, and version. === == Event handler methods As well as the `@EventMethod` annotation, event handler methods must have a particular signature. * They must be public, not-static methods that return `void`. * The method name must be on `<event-name>`. The event name must be a unique name within the servlet application. * The first parameter is the event object. The parameter type is defined by the SLEE event type's definition, usually part of the RA type definition. * The second parameter is the ACI of the activity that the event was fired on. * The last parameter is the `SipApplicationSession` instance that is processing the event. The event handler method can process the event just like a SLEE SBB event handler method. The activity object associated with the event can be obtained using `ActivityContextInterface.getActivity()` on the ACI passed to the event handler method. == Initial events SIP servlet application instances are typically created when a new initial SIP request arrives, which is not associated with any existing `SipSession`. A new `SipSession` and `SipApplicationSession` are created to process the request, and the `SipApplicationSession` will hold any state for the new application instance. It is also possible to trigger a new application instance using events from other SLEE RAs. To do this, the application must declare that one or more event types are _initial events_. This is done by adding the `initialevent=true` attribute to an `@EventMethod` annotation: = "com.opencloud.slee.resources.http.httprequest.get", vendor = "OpenCloud", version = "2.2"), initialevent = true) public void onhttprequest(httprequest request, ActivityContextInterface aci, SipApplicationSession appsession) { log("servlet received HTTP request: " + request); } 23

24 Here this means that an HTTP GET request will create a new `SipApplicationSession` instance. It could then initiate a new `SipSession` with another SIP device, to implement a "click-to-dial" service. Initial events can also enable bxref:converged-applications[converged applications]. :leveloffset!: :ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/ra/sipservlet/ release-1.1.0/release-docs/sipservlet-docs/rhino-sip-servlet-overview-andconcepts/slee-resource-adaptor-support/converged-applications.adoc :here: slee-resource-adaptor-support/ :idprefix: converged-applications :leveloffset: 1 = Converged Applications :sortorder: 760 // DevPortal author: ~jonh Often it is desirable to have initial events be processed by the same application instance. For example, a conferencing service might want to have all calls to the conference address be handled by the same application instance, so the state of all participants can be easily managed in a single `SipApplicationSession`. == Session targeting mechanisms SIP Servlet provides several _session targeting_ mechanisms that allow initial SIP requests to be directed to the same `SipApplicationSession`. The most generic session targeting mechanism is the `@SipApplicationKey` method. The SIP Servlet container invokes a `@SipApplicationKey` method with the initial request, and the method returns a string which identifies a `SipApplicationSession`, creating the session if it doesn't exist. `@SipApplicationKey` only applies to SIP requests, but Rhino SIP Servlet provides an equivalent session targeting mechanism for non-sip initial events. This means that events from different protocols can be directed to the same application instance, enabling converged applications. session targeting To implement session targeting for non-sip events, a servlet application defines a `@SleeApplicationKey` method. This is very similar to `@SipApplicationKey` methods, in that it takes an initial event and returns a string. The string identifies a `SipApplicationSession` instance, which is created automatically if it doesn't already exist. 24

25 TIP: The method is only used for non-sip initial events; SIP events will still use To enable SIP and non-sip initial events to select the same application instance, the application developer just has to ensure that these two methods return the same values for related events. The signature of the method looks like this: public static String anymethodname(object event, Object activity) { } The method must satisfy these properties: * Only one method in the application can be annotated with `@SleeApplicationKey`. * The method must be public and static. * The method may have any name. * The method must return `String`. * The method must have two `Object` parameters, which are the SLEE event and its activity object. The body of the method can do anything, but it should be idempotent. It should inspect the event and activity parameters and extract the required information, such as user IDs or session IDs, to generate the return value. === Default session targeting behaviour If there is no `@SleeApplicationKey` method defined in the application, Rhino SIP Servlet will just create a new `SipApplicationSession` instance for each new non-sip activity. :leveloffset!: :ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/ra/sipservlet/ release-1.1.0/release-docs/sipservlet-docs/rhino-sip-servlet-overview-andconcepts/slee-resource-adaptor-support/slee-libraries.adoc :here: slee-resource-adaptor-support/ :idprefix: slee-libraries :leveloffset: 1 = SLEE Libraries :sortorder: 770 // DevPortal author: ~jonh Servlet applications may also use any library components deployed in the SLEE. Like RA type bindings, library bindings are declared using annotations on a package within the application: 25

26 [source,java] = "guava", vendor = "com.google.guava", version = = "protobufjava", vendor = "com.google.protobuf", version = "2.5.0")), }) package com.example.app; import com.opencloud.sipservlet.slee.annotation. ; import javax.slee.annotation. ; Here the application has declared a dependency on two other libraries. These libraries must be deployed in the SLEE before the servlet application can deploy. NOTE: Use of SLEE libraries is purely optional; servlet applications can also just put their dependencies in + `WEB-INF/lib` in their SAR file. SLEE libraries may be useful if they are shared by many applications on the same SLEE platform. :leveloffset!: :ocdoc_current_file: /mnt/volume-01/jenkins/workspace/product/ra/sipservlet/ release-1.1.0/release-docs/sipservlet-docs/rhino-sip-servlet-overview-andconcepts/example-applications.adoc :here: :idprefix: example-applications :leveloffset: 1 = Example Applications :sortorder: 800 // DevPortal author: ~ben Your Rhino SIP Servlet installation comes with example applications, in the `examples/` directory. Each subdirectory under `examples/` holds a self-contained SIP Servlet application, with source code and Ant deployment scripts. Running `ant` inside an example application's directory executes the default `deploy` build target, which builds the application and deploys it into the SLEE. Once deployed, the application can be tested using your preferred SIP testing tools, such as or sourceforge.net/projects/sipsak.berlios/[sipsak], or SIP softphones such as or WARNING: You must gxref:rhino-sip-servlet-installation-and-administrationguide/installing-rhino-sip-servlet[deploy a Rhino SIP Servlet RA entity] before attempting to install the example applications. 26

27 Below are descriptions of the sample applications: bxref:#code-sipservletservices-code[sipservlet-services], bxref:#code-proxy-hybrid-code[proxyhybrid] and bxref:#code-http-example-code[http-example]. == sipservlet-services [cols="1h,5a"] === What it does Implements some typical SIP services: * Registrar * Back-to-back user agent (B2BUA) & Proxy * Presence. How to configure * Only one of the B2BUA or Proxy servlets should be enabled at a time. * The B2BUA servlet is enabled by default. * To enable the Proxy servlet, uncomment the `<servlet-mapping>` element for `proxy-servlet` in the deployment descriptor, and comment out the corresponding `b2b-proxy-servlet` element. * Use the env-entry "`localdomains`" to specify a comma-separated list of domain names that the proxy and B2BUA consider to be local. If these servlets receive a request with a Request-URI containing a SIP identity (a.k.a. _address of record_) that is within one of these domains, the servlets lookup the SIP identity in the registration database to find a registered contact address. If no entry is found, an error response is returned to the caller. The registration database is populated by the Registrar servlet when SIP clients send REGISTER requests to register their current contact address. The application's deployment descriptor can be found at `resources/web-inf/ sip.xml`. Database it uses An embedded (in-process) Derby database to store SIP registrations; created automatically during deployment. === == proxy-hybrid NOTE: This is an example *hybrid application* -- a SLEE service that uses the SIP Servlet 1.1 RA Type, and uses the SIP Servlet Proxy interface to implement a simple proxy. [cols="1h,5a"] === What it does Implements a _very simple_ proxy; does not attempt to lookup registered SIP identities, so it can only forward requests to their next hop. 27

28 How to configure Edit the service's SBB deployment descriptor: `resources/meta-inf/sbbjar.xml`. _The environment entries_ `proxyrecordroute` _and_ `proxysupervised` _are applied to the_ `Proxy` _instances that are created when processing initial requests._ === == http-example NOTE: This is an example of a servlet application using a bxref:sleeresource-adaptor-support[slee Resource Adaptor] to communicate using another protocol, in this case HTTP. [cols="1h,5a"] === What it does A simple proxy that also uses the HTTP RA to make an HTTP request. Also processes incoming HTTP requests as initial events. How to configure No configuration required. === :leveloffset!: 28