The SipXrest container - a restful service container for exporting REST interfaces to sipXecs call control services
As sipXecs grows to integrate with other products, there is a need to export call control services using a web services model so that these services may be invoked by other components and from other products. An example of such a service would be the third party call controller. Call control services are traditionally written in sipXecs as stand alone processes. SipXrest does not aim to supplant this model. Rather, what we aim to do is to provide a web services interface to interact with such call control services that are useful to export for business integration purposes. Web services (and recently REST-based services)are exported by sipXconfig for configuration functions. We aim to do something similar for call control functions. This has worked well thus far by placing such integration code into sipxconfig. SipXconfig thus exports the third party call controller as a REST service in SIPXECS 4.0. However, as the number of these services grows, so do the associated problems of putting every bit of call control integration functionality into sipXconfig. As the complexity of the product grows, so does the number of such services and hence so do the number of integration issues.
...
SipXrest is a simple (almost trivial) converged container. (It does not aim to be a re-invention of the JAIN-SLEE or anything nearly that complicated.) There is a single SIP stack and a single HTTP server that is shared by all the plugins that run in sipXrest. SipXrest provides no service isolation of plugins ( they all use the same classloader ) and provides only very simple lifecycle management. Plugin authors are expected to be well mannered and not trod on each other's static data. Services are created (instantiated) when they are loaded. Services may initiate SIP signaling via the SIP Service bean that is shared by all such services bundled as part of the service container. Each service may define its own security policy and HTTP authentication method for interaction with the outside world. SipXrest will access the validusers.xml account database and take care of HTTP and SIP request authentication. A simple SipHelper class is provided to the SipListner part of the service (if one exists) and exposes a subset of the JAIN-SIP SipProvider functionality. This allows plugins to create SIP protocol objects such as SIP Transactions and SIP Dialogs. The supported SIP signaling model is dialog stateful. Each Plugin may have a single SIP endpoint. The goal is to simplify the task of building such converged services while allowing them to co-exist in a single JVM and constraining them to a single style of SIP service ( i.e. the SIP UA). No SIP proxy or SIP back to back user agent function is supported.
How to write a plugin
A plugin is a Jar file. It is placed in the directory ${prefix}/share/java/sipXecs/sipXrest/plugin. Each plugin has a file : plugin.xml that indicates the behavior of the plugin,
its main ( Plugin ) class and other aspects of its behavior.
...
sip-convergence-name : This is the "convergence name" of the service. This field is relevant if the Dialog that instantiates the service will be instantiated by
an out of Dialog inbound INVITE (i.e. runs as a UAS). The userName part of the request URI is used to identify the appropriate service to instantiate. If the SIP service is not triggered \by an incoming SIP request (i.e works as a UAC) you can leave the field blank.
The Plugin Class
The main plugin class must extend the org.sipfoundry.sipxrest.Plugin abstract class. The abstract methods of this abstract class that must be implemented are :
...
Note that we have cleanly separated deployment and security policy issues from what the plugin itself is supposed to be doing, thus liberating the mind of the programmer to indulge in creative activity. If your plugin does not need sip stack support thats all there is to it.
Plugins that need SIP stack support
Life gets a bit more complicated when your plugin needs SIP support. SipXrest bundles a JAIN-SIP stack instance. Each plugin can have a SipListener class that extends the abstract org.sipfoundry.sipxrest.AbstractSipListener class (unlike JAIN-SIP this is not an interface).
...
The SIP support in the container will be evolved as needs dictate.
Port and process management
The whole container has a single SIP port, one HTTP port and one HTTPS port. These must be allocated by sipxconfig. The container is hence suitable for services that are structured as simple endpoints or plain HTTP services without SIP signaling requiremnts. We do not envision building back to back user agents that live in this container.