How it works?

The Seam 2 core is mostly independent of HTTP Servlets and JSF. Basically we install a controller Sip Servlet and session listeners to control the context assignment for incoming SIP messages and reproduce the Seam lifecycle completely. When a SIP message arrives, we raise Seam events to notify the Seam components subscribed to receive the SIP events.

The Media Server events occur in the context of a SIP session and are treated in a similar way as the SIP events. You just subscribe methods with @Observer and process them as regular Media Server listener notifications.

The setup is straightforward - just add the controller servlet to your Seam application in a Sip Servlets container and it's ready to go. For now you can start with the sample application.

Theoretically this technique can work on any JSR289-compliant container that supports JBoss Seam, but it is only tested on Mobicents Sip Servlets 0.8 and higher with JBoss Application Server 4.2.3 and Seam 2.1.x.

Example

This is simple SIP service which responds to an INVITE and counts the number of messages per session. There is a session-scoped counter, which is incremented on every message. Note how you can subscribe methods to SIP events. You can subscribe as many methods as you like in any Seam component, they all will be notified.

@Name("simpleSeamSipService")
@Scope(ScopeType.STATELESS)
@Transactional
public class SimpleSeamSipService {
    @Logger Log log;
    @In SessionMessageCounter sessionMessageCounter;
    
    public void inc() {
        sessionMessageCounter.increment();
        log.info("Processed SIP messages " 
                + sessionMessageCounter.getMessages());
    }
    
    @Observer("INVITE")
    public void doInvite(SipServletRequest request) 
    throws Exception {
        inc();
        request.createResponse(180).send();
        Thread.sleep(100);
        request.createResponse(200).send();
    }
    
    @Observer("ACK")
    public void doAck(SipServletRequest request) 
    throws Exception {
        inc();
    }
    
    @Observer({"REGISTER","BYE"})
    public void doRegister(SipServletRequest request) 
    throws Exception {
        inc();
        request.createResponse(200).send();
    }
}

You should keep in mind that the Seam events are application-wide. If you need cross-application messaging use JMS. Seam would help a lot with JMS too.

And this is the SIP-session scoped component:

@Name("sessionMessageCounter")
@Startup
@Scope(ScopeType.SESSION)
public class SessionMessageCounter {
    private int messages;
    
    public int getMessages() {
        return messages;
    }
    
    public void increment() {
        messages++;
    }
}

Actually, this component is created and stored in every Seam session, no matter if it's SIP or HTTP. This is a bit inefficient, but has some advantages. Ultimately we would want to have a separate SipSession and SipApplicationSession scopes in Seam and we will probably get there with the user-defined scopes in Web Beans (JSR 299) or a newer version of Seam.

It is useful to know that you can always inject the current SipSession. This is particularly useful when processing Media Events. Media Events by default do not have a SipSession association, but the Seam Telco Framework work it out. To inject a SipSession simply do this:

@In SipSession sipSession; // note that this will not be available in HTTP context(sessions). it is only available in SIP or Media context.

Similarly you can inject the SipFactory if you need it:

@In SipFactory sipFactory; // This is available from any context HTTP, SIP or Media.

Making calls from a Web Page

There is nothing special here, you just make some action that creates a sip request and send it. Note how the SipFactory is available from the web context without any special configuration.

@Name("callAction")
@Scope(ScopeType.STATELESS)
@AutoCreate
public class CallAction {
	@Logger 
	private static Log log;
	@In SipFactory sipFactory;

	public void dialParticipant(final CallParticipant participant) {
		SipApplicationSession appSession = sipFactory.createApplicationSession();
		Address from = sipFactory.createAddress("here@localhost");
		Address to = sipFactory.createAddress(participant.getUri());
		URI requestURI = sipFactory.createURI(participant.getUri());
		SipServletRequest request = sipFactory.createRequest(appSession, 
					"INVITE", from, to);
		request.setRequestURI(requestURI);
		request.send();
		log.info("Calling " + to);
	}
}

.. of course, you can call this action programatically or directly from a JSF template like this:

<h:commandLink value="Dial" action="#{callAction.dialParticipant(someParticipant)}"/>

This is just a button that will call the action when clicked. Keep in mind that almost all Java Web Frameworks are based on top of HTTP Servlets, including JSF, GWT and those on top of them. Thus, the code is equivalent to initiating a call from HTTP servlet. We do not obtain the SipFactory and the application session in the recommended way from the JSR-289 spec in this case, because this method can be called from within Web Context, SIP Context or Media Context. The JSR-289 recommended way is meant for Web Context only as it expects HttpSession object to be available at all times. Injecting the SipFactory from the Seam IoC makes it more generic and fool-proof. If you don't plan to call this dialParticipant method from SIP or Media Context you can also do this, but there is generally no benefit, even though it is recommended by JSR-289:

// Don't use this because we might call it from SIP context (faces context not available outside HTTP context)!
FacesContext context = FacesContext.getCurrentInstance();
ConvergedHttpSession session = (ConvergedHttpSession) context.getExternalContext().getSession(false);

Media Support

The Media events from Mobicents Media Server also work in concert with the rest of the framework. All Media events occur in the context of a SipSession and you can use the Sip Session to share state between the Media and SIP events. The Media events are carried in the same classes as the events from MSC API. It is highly recommended to get familiar with MSC API before reading the rest of the document. You can learn more about MSC API in the official Mobicents documentation. Basically the Seam Telco Framework installs it's own listeners for all Media objects (connections, links and endpoints) that are used in the context of a call (SipSession), then the listener callbacks are transalted into Seam events and delivered in the call context (SipSession context).

@Observer("mediaEvent")
public void mediaEvent(MediaEvent mediaEvent) {}

@Observer("connectionCreated")
public void doConnectionEvent(MsConnectionEvent connectionEvent) {}

@Observer("connectionDisconnected")
public void doConnectionEvent(MsConnectionEvent connectionEvent) {}

@Observer("connectionFailed")
public void doConnectionEvent(MsConnectionEvent connectionEvent) {}

@Observer("connectionHalfOpen")
public void doConnectionEvent(MsConnectionEvent connectionEvent) {}

@Observer("connectionModeRecvOnly")
public void doConnectionEvent(MsConnectionEvent connectionEvent) {}

@Observer("connectionOpen")
public void doConnectionEvent(MsConnectionEvent connectionEvent) {}

@Observer("connectionModeSendRecv")
public void doConnectionEvent(MsConnectionEvent connectionEvent) {}

@Observer("connectionModeSendOnly")
public void doConnectionEvent(MsConnectionEvent connectionEvent) {}

// Media Link Events

@Observer("linkConnected")
public void doLinkEvent(MsLinkEvent linkEvent) {}

@Observer("linkCreated")
public void doLinkEvent(MsLinkEvent linkEvent) {}

@Observer("linkDisconnected")
public void doLinkEvent(MsLinkEvent linkEvent) {}

@Observer("linkFailed")
public void doLinkEvent(MsLinkEvent linkEvent) {}

@Observer("modeFullDuplex")
public void doLinkEvent(MsLinkEvent linkEvent) {}

@Observer("modeHalfDuplex")
public void doLinkEvent(MsLinkEvent linkEvent) {}

// Notification events (for DTMF and others)

@Observer("mediaEvent")
public void doMediaEvent(MediaEvent mediaEvent) {}


// Since STF 2.1 if you application doesn't handle a media exception, this event is raised
// similarly to the core Seam exception handling for out-of-context exceptions.

@Observer("org.mobicents.media.unhandledException")
public void doUnhandledException(Exeption exception) {}

(DEPRECATED since STF 2.1, use linkConnected instead) @Observer("storeLinkConnected") // This event is fired after the MediaSessionStore is initialized with the MsConnection
public void doLinkEvent(MsLinkEvent linkEvent) {}

(DEPRECATED since STF 2.1, use connectionOpen instead) @Observer("storeConnectionOpen") // This event is fired after the MediaSessionStore is initialized with the MsLink
public void doConnectionEvent(MsConnectionEvent connectionEvent) {}

@Observer("DTMF") // Fired when we are listening for DTMF in the current SipSession context
public void doDTMF(String digit) {}

@Observer("announcementComplete") // Fired when the announcement in the current SipSession context is complete
public void doAnnouncementComplete() {}

@Observer("announcementFailed") // Fired when the announcement in the current SipSession context has failed
public void doAnnouncementFailed() {}

@Observer("audioFailed") // Fired when there is a problem with audio
public void doAudioFailed() {}

You can handle these events and relate them to a sip session simply by injecting the SipSession object and you can store or read state from there as shown in the example below. We are reusing the MSC API objects with the exception of MediaEvent where the notification message is wrapped and carries more information than the original event structure. You can see the demo for more details. And generally the best way to learn it is by playing with the examples, where more useful utility classes have been developed (the media framework demo in particular)

Here is an example conference application using the most common functions:

 
@Name("conference")
@Scope(ScopeType.STATELESS)
public class Conference {
	@Logger Log log;
	@In MediaController mediaController;
	@In SipSession sipSession;
	
	@In(scope=ScopeType.APPLICATION, required=false)
	@Out(scope=ScopeType.APPLICATION, required=false)
	String conferenceEndpointName;
	
	@Observer("INVITE")
	public void doInvite(SipServletRequest request) throws Exception {
		String sdp = new String((byte[]) request.getContent());
		request.createResponse(180).send();
		sipSession.setAttribute("inviteRequest", request);
		if (conferenceEndpointName == null)
			conferenceEndpointName = "media/trunk/Conference/$";
		mediaController.createConnection(conferenceEndpointName).modify("$",
				sdp);
	}

	@Observer("connectionOpen")
	public void doConnectionOpen(MsConnectionEvent event) throws IOException {
		conferenceEndpointName = event.getConnection().getEndpoint()
				.getLocalName();
		SipServletRequest request = (SipServletRequest) sipSession
				.getAttribute("inviteRequest");
		SipServletResponse response = request.createResponse(200);
		response.setContent(event.getConnection().getLocalDescriptor(),
				"application/sdp");
		response.send();
	}

	@Observer( { "BYE", "REGISTER" })
	public void sayOK(SipServletRequest request) throws Exception {
		request.createResponse(200).send();
               // Since STF 2.1 - no need to release MsConnection and MsLink objects stored in the mediaSessionStore.
               // They are cleaned up automatically.
	}

}

• IVRHelper - executes managed MSC-API opertaions. The events and the results from these operations will be delivers as Seam Events.
  

• MediaEventDispatcher - dispatches common MSC-API Media events and produces finer-grained events like DTMF or announcement complete/failed. It also stores useful DTMF stacks accumulated in Media Objects.

• IVRHelperManager - central place for all IVRHelpers in the application. Very frequently you need to manipulate not your own context, but some other Sip Session. In this case you can lookup the other Sessions's IVRHelper and to IVR opertaions there. A typical case would be if you are disconnecting the current session and want to play an announcement to some other user that you have left the call and you are no longer busy or similar function.

• MediaSessionStore - Each Sip Session will have exactly one instance of this class. Here we store the Media objects associated with the SipSession. We make some attempts to fill in the objects automatically, but it is recommended that you set them manually.

• MediaController - Media controller is a low-level per-SipSession entity responisble for the audio RTP stream associated with the SipSession. It corresponds to the MsEndpoint MSC API, but in a Seam-managed way. From here you can contruct the audio path (or the chain of endpoints) that the RTP will pass through for processing). You can construct MsLink or MsConnection objects from here that are under Seam Telco Framework management. When a MsLink or MsConnection is under Telco Framework management the events produced from these objects will be passed as Seam events and can be captured byt subscribing methods with the @Observer annotation. You don't have to install your own listeners, the framework will do that for you. Avoid creating MsLinks and MsConnections with the MSC-API methods when possible.

• MediaControllerManager - This is a central repository of all MediaControllers for all SipSessions. You can lookup other SipSessions's MediaControllers to manipulate them similarly to to how you would do with IVRHelperManager.

• MediaEvent - This is a structure that carries information associated with an event produced by the Media Server. The MsNotifyEvent is the original event and the rest are just the related objects for the event - the link is the MsLink or the MsConnection object where the event occured. The endpoint is the endpoint where the event occured. And of course the SipSession is the the SIP session where the event occured.

• To see a complete example in a single file you can see our Media Demo in Google Code.
• To see a bigger application you can check out our IPBX project.

Download

 Grab the latest binary directly from the JBoss Maven2 repository (or configure your maven project to references it).

• The latest Mobicents Sip Servlets with JBoss AS 4.2.3 (please do NOT use it with JBoss AS 5.0 for now, since the Media support there is still in technology preview stage)
  
• Install the latest JBoss Tools 3.0 or later in Eclipse 3.4 or the nightly build of JBoss Tools (this is the update site) - you need JBoss Seam, JBoss AS Tools and Richfaces plug-ins as minimum. You must use the nightly builds for Seam 2.1 support. Soon, a new JBoss Developer Studio will be released with official Seam 2.1 support. Be sure to read the documentation of the Seam plugin and the rest of the JBoss Tools plugins.
  
• Get Seam 2.1.1.GA and configure it as Seam runtime in JBoss Tools when asked.
  

• Get the latest binary of sip-servlet-seam-entrypoint.jar and put in the Web App lib folder (under WebContent/WEB-INF/lib)
• You will also need to add the following jars - mobicents-media-server-constants, mobicents-media-server-api, mobicents-media-server-api-local-impl (take them from here). Bascially you want your project to look like the screenshot on the left. Note that the Web App Libraries folder is just an alias of WebContent/WEB-INF/lib folder in your project. If you manually put jars in WebContent/WEB-INF/lib they will appear in Web App Libraries and they will be packaged in your war file. The jars in Referenced Libraries on the other hand are not packaged with the war, they are just used at compilation time, you should NOT put the files mentined above in the Referenced Libraries folder.

• Put this sip.xml in WebContent/WEB-INF/ :
  

<?xml version="1.0" encoding="UTF-8"?>

<sip-app>

   <app-name>PUT_SOME_APPLICATION_NAME_HERE</app-name>
   <display-name>SeamEntryPointApplication</display-name>
   <description>SeamEntryPointApplication</description>
  
   <main-servlet>
       SeamEntryPointServlet
   </main-servlet>

   <servlet>
       <servlet-name>SeamEntryPointServlet</servlet-name>
       <display-name>SeamEntryPointServlet</display-name>
       <description>Seam Entry Point Servlet</description>
       <servlet-class>
           org.mobicents.servlet.sip.seam.entrypoint.SeamEntryPointServlet
       </servlet-class>
       <load-on-startup>1</load-on-startup>
   </servlet>

   <listener>
       <listener-class>
           org.mobicents.servlet.sip.seam.entrypoint.SeamEntryPointServlet
       </listener-class>
   </listener>

</sip-app>

Guidelines

• Do not subscribe methods to SIP and media events in Seam components with SESSION or CONVERSATION scopes! The reason is that each of these SESSION or CONVERSATION scoped components is likely to have multiple instances (depending on the number of the sessions) and they all will be called, which is probably not what you want.
• Always subscribe public methods to SIP and media events. Any other access modifier will cause you method not to be called.
• Whenever you want a Session-scoped component that is shared between HTTP and SIP you can just use the same component name, but assign values from different components responsible for the particular protocol. For example, when you want a shared Identity between SIP and HTTP users, you could simply have a HTTP authenticator and SIP authenticator that initialise the Session0scoped component "user" in both sessions. The rest of the application will not care where it came from (HTTP and SIP).
• Avoid using @Begin and @End for tx or conversation boundaries in SIP components. It won't work. For HTTP components it will work fine.
• Avoid using application-scoped componnets and injecting other components from finer-grained scopes (Session or Method, etc). The injection might not occur properly, because the memober might be flagged as injected already, be sure to test it.
  

Advantages

• All the Seam goodness.
• Development is easier, because you can use the Seam WEB-INF/dev classloader to deploy Seam components faster. Otherwise you have to redeploy the whole war/ear (10-20 secs vs 1-2 secs).
  
• Testing - Seam provides a great framework for testing based on dependency injection and mocking.
• Programming model is practically the same as the one you use for Web apps with Seam and similar to the future Web Beans.
• Potential to integrate with jBPM and JBoss Rules through Seam. (contributors?)

Disadvantages

• It is not standards-based.
• Performance is suffering a bit with Seam.

You can find the entrypoint project and the sample applications in SVN: http://mobicents.googlecode.com/svn/trunk/frameworks/sip-servlets/seam-telco-framework