Figure 1. The conference participants speak SIP to the Proxy registrar and RTP to the media server (click the image for a full-size screen shot)
Published on dev2dev (http://dev2dev.bea.com/)
http://dev2dev.bea.com/pub/a/2006/05/media-server.html
See this if you're having trouble printing code examples
Media server control is vital to most SIP-based VOIP applications. This article describes a sample conferencing application built using BEA WebLogic Workshop that leverages BEA WebLogic SIP Server to drive an MSCML-enabled media server from Cantata. Using this basic voice/video conferencing application we can showcase the primitives behind media server control, providing examples that show how to develop SIP servlets using WebLogic Workshop, how to integrate those SIP servlets with Java Page Flows created with WebLogic Workshop, and how to share data between SIP servlets and HTTP servlets.
Before exploring the application, make sure you have access to:
After obtaining access to the media server and identifying multiple systems to serve as SIP conference parties, it is time to set up and to configure WebLogic Workshop and WebLogic SIP Server. Documentation for installing and configuring WebLogic Workshop for use of WebLogic is available here.
Media server control is vital to any SIP-based VOIP application that involves more than two parties communicating in a peer-to-peer fashion. While WebLogic SIP Server can be used for the call control and session management aspects of an application that uses SIP, the actual media itself needs to be brokered by a media server. The following is a list of the kind of tasks a media server typically performs:
This article presents a conferencing application that was written by BEA for the purposes of demonstrating the following:
The application provides a Web front end that allows an admin user to create a conference. After the conference is created, people can call in to this conference using the SIP ID generated by the application. The caller is prompted for a PIN, also generated by the application, and optionally sent via email to the users. The PIN is entered using DTMF, processed by the media server, evaluated by the application, and, if correct, the user is added to the conference. While the conference is in session, participants can be muted, unmuted, and terminated by way of the Web UI. This shows the sharing of information between SIP and HTTP contexts, a key differentiator of WebLogic SIP Server.
Since video conferencing is also supported by the media server, participants in the conference can switch to video at any time.
The full set of use cases can be found in the appendix.
The application consists of three major components:
Figure 1 shows a simple diagram of the application components:
Figure 1. The conference participants speak SIP to the Proxy registrar and RTP to the media server (click the image for a full-size screen shot)
Note that in Figure 1 the requests are proxied to the conferencing application, which manages the sessions with the media server. The conference administrator configures the conference via HTTP using the Web application. State is shared between the Web application and the conferencing application using the Conference Manager
The installation instructions describe how to create a SIP domain using a WebLogic Workshop Template, which enables development of SIP servlets in WebLogic Workshop. This allows you to build a converged HTTP/SIP application using HTTP Java Page Flows (JPFs) and SIP servlets running in the same application. The HTTP presentation layer of this application is implemented with JPFs. The SIP presentation layer is implemented with SIP servlets.
The Java Page Flows and JSPs in the application define a Web UI for handling user authentication, conference creation, monitoring, and management. Each UI function has a corresponding JPF that manages control flow between the JSPs involved.
For the purposes of logical separation, the WebLogic Workshop project is divided into two relevant folders: the Web application folder (WebApp) and the conferencing folder (confapp). The WebApp folder contains HTTP resources, JSPs, and JPFs to handle user authentication, conference creation, monitoring, and management from a Web UI.
|
The conferencing folder contains the com.bea.appserver.conference package, which is the business logic behind the conference itself, including the call flow logic implemented by SIP servlets to accept calls joining the conference, and state control classes for managing the call flows. The class com.bea.appserver.conferencing.ConferenceManager serves as the interface point for the HTTP UI.
An event listener design pattern is utilized to trigger SIP actions from the HTTP side. When a user is disconnected, for example, a SIP INFO message containing an MSCML payload is sent to disconnect the user.
SIP dialog details are handled by the DialogHandler interface, and two implementations of the interface are provided for SIP client and SIP server. By encapsulating SIP dialog state as a finite state machine in separate business logic, the SIP servlet programming is greatly simplified. This brings back memories of the HTTP servlet world before the advent of MVC-based technologies such as Struts and JPF. In the near future one can imagine industry leaders driving extensions to JSP, Struts, and JPF to include SIP-based presentation layers. Until then, it's important to properly manage this in your SIP servlet application.
Figure 2 shows a simple object diagram for the confapp section of the application:
Figure 2. Object diagram of the confapp application (click the image for a full-size screen shot)
Note that SIP call flow logic is abstracted away from the business logic of managing a conference. SIP dialogs that are initiated by the UI are signaled by calling a method on the conferee, which makes a call to a DialogHandler as part of its state change logic. Likewise, SIP dialogs that are initiated by an incoming request to the com.bea.appserver.conferencing.ConferenceServlet class also go through the state mechanism implemented in the DialogHandler. By maintaining their own internal state, the DialogHandlers are able to easily implement SIP call flows.
The rich features of the Snowshore IP Media Server, such as playing an announcement and controlling a conference, are driven through MSCML, an XML-based protocol delivered in the body of SIP messages. This application forms MSCML to play announcements, and to set up and tear down conferences. It also parses MSCML from the media server to collect DTMF digits that serve as conference IDs and PINs. While this application is MSCML-specific, I'll be writing further articles on how to follow with other media server standards, and how to interoperate with media servers in a more abstract, cross-platform way.
If you're under a time constraint, then the simplest and least elegant approach is to provide template XML in a Java String object for each discrete media server operation performed by the application. At run-time, the application simply performs keyword substitution in order to dynamically configure the operation:
public void announceConferee(Conferee user) {
// Here we will not change the state of the conference
// We will simply instruct the conference server to play the prompt
String command = "<mediaservercontrol version="1.0">";
command += "<request>";
command += "<play>";
command += "<prompt>";
command += "<audio url="" + Conferee.baseDir + user.getRecordedName()
+ "">";
command += "<audio url="" + Conferee.JOIN_PROMPT + "">";
command += "</audio>";
command += "</audio>";
command += "</prompt>";
command += "</play>";
command += "</request></mediaservercontrol>";
SipServletRequest req = dialogHandler.session.createRequest("INFO");
try {
req.setContent(command.getBytes(), "application/mediaservercontrol+xml");
req.send();
} catch (Exception e) {
e.printStackTrace();
}
}
As media operations get more complex and parsing MSCML messages from the media server is required, it becomes necessary to expand our toolset and to provide an abstraction layer for media server control. A good start is to use an XML binding framework such as XMLBeans, leveraging the publicly available XML schema files for the media server control language in question. In this example, MSCML is used, and the XML schema is available here. When the XML control language is encompassed in XMLBeans, more complex tasks such as parsing a SIP INFO message with an XML payload attached become manageable. This code uses the classes generated by XMLBeans to parse the DTMF digits returned from the media server to the application server:
// Now get the content
try {
String content = new String((byte[]) req.getContent());
// First parse the MSCML response
MediaServerControlDocument doc =
MediaServerControlDocument.Factory.parse(content);
MediaServerControl control = doc.getMediaServerControl();
ResponseType resp = control.getResponse();
String digits = resp.getDigits();
myState = new Connected();
notifyListeners(DialogHandler.AUTHORIZATION_EVENT, digits);
return myState;
} catch (Exception e) {
e.printStackTrace();
}
Now that the XML layer is abstracted, you can create a control API for generic media server control. Stay tuned for future articles on this topic.
|
Special attention should be paid to the best practices used in the application. In the interests of time and simplicity, not all best practices are implemented here. Moreover, the SIP servlet specification is fairly young and some best practices are still in development. However, detail was paid to the following key practices:
ConferenceManager class in the com.bea.appserver.conferencing package. This enables both SIP and HTTP servlets to refer to the same objects, establishing SIP/HTTP convergence.sip.xml file explicitly refuses to route SIP REGISTER requests, therefore acknowledging that the SIP servlet may be deployed alongside an existing registrar. In fact, the registrar and proxy functionality are provided separately. This hints that SIP servlets should be granular, modular, and logically separated to ensure optimal flexibility in service creation and deployment.The following items discussed in this article can be downloaded:
This article presents a sample application that illustrates converged HTTP/SIP application development with WebLogic SIP Server and WebLogic Workshop, media server interoperability with WebLogic SIP Server, and best practices around building SIP-based applications when considering multiple presentation media and divergent media standards. I hope you enjoy the sample, and I look forward to your comments.
The following use cases are implemented by the application. I also include links to diagrams showing the associated SIP call flows.
Jeff Bean is a Technical Manager working for the BEA Global Alliances Group. He has 9 years of IT experience as a software developer, professional services consultant, and systems engineer.
Sudhrity Mondal is a Senior Principal Architect working for BEA Global Alliances Group. He has 14 years of industry experience and specializes in enterprise integration solutions.
Marcelo Oliveira is a Software Engineer currently working for Cisco Systems in the Emerging Markets Business Unit.
Return to dev2dev.
