In order to understand the features and capabilities of the Jiplet Container, you must read the entire howto sequentially, not just the topics you need to know more about. This is because one topic may refer to a previous topic.
- What is a Jiplet?
- What is a jiplet application and how does it get deployed?
- What is a jiplet container?
- Which one should I use – the standalone jiplet container or jiplet container running as a JBOSS service?
- What kind of system do I need for installing the jiplet container server?
- How does a jiplet container compare with a Java servlet container?
- What kind of scoped variables are supported?
- How does the jiplet container handle SIP message authentication and authorization requirements?
- Does the jiplet container support the SIP proxy functionality?
- Does the jiplet container support naming services like many servlet containers?
- What are some of the differences between a jiplet container and a servlet container?
- How does it compare with other SIP development tools?
- How do jiplet applications work in a service provider (or hosting) model?
- How is the jiplet approach suitable for integrating SIP applications with the J2EE environment?
- How does one go about developing and deploying a Jiplet application?
- How does a sysadmin manage jiplet applications?
- What kind of tools does the jiplet container come with?
- How do I submit a request for a new feature?
Jiplet is short for Java Sip Servlet. A jiplet is a Java class that resides inside a “container” and handles SIP messages from other SIP user agents – SIP phones and other SIP servers. In concept, it is very similar to a Java Servlet. A java servlet enables developers to create server-side applications that can be accessed from the web using a web browser. Similarly, a jiplet enables developers to create server-side voice over IP (VOIP) applications that can be accessed from SIP phones and other SIP devices. SIP is one of the most popular VOIP protocols. Examples of SIP server-side applications include (1) a SIP PBX, (2) a SIP call center, (3) a SIP location server, etc. In short, you can create custom SIP applications for your company or your customers.
To create a SIP application using the jiplet technology, application developers create one or more jiplet classes and deploy them into a jiplet container. The Jiplet Container is an open-source server-side application from CafeSip.org that can host one or more such jiplet applications. Developers create jiplet applications by using the Jiplet API provided in the form of Java class libraries along with standard Java class libraries, packaging the classes into deployable bundles and deploying them into the jiplet container. In concept, it is very similar to a Java servlet where application developers create a Java application and deploy it into a servlet container like Tomcat, Jetty or JBOSS.
If you understand the Java servlet technology, you will follow this concept very easily.
A jiplet application (also referred to as a context) consists of one or more jiplet classes that work together in order to provide a SIP service. An example of such a service is a SIP call center that maintains a queue of operators, routes calls to the operators and manages the queue. For simple applications only one jiplet is needed, but for more complex applications, the feature may require multiple jiplets each handling a particular function. As an example, for a PBX application, one jiplet provides the proxy server function and another provides the presence server functions.
A jiplet container is an open-source server software from CafeSip.org that can “host” one or more jiplet applications. That is, one ore more jiplets can be plugged in (deployed) to the container. Once deployed, the jiplet container instantiates the jiplet classes and provides the run-time environment. When a SIP message or event occurs, the container passes on the event/message to the jiplet object based on a configurable selection criteria. In that sense, the jiplet container server is a container for the jiplet applications. The jiplet container can host multiple applications or contexts which are completely isolated from each other – each application runs in its own space and does not interact with any other application running in the container.
Application deployment involves the following:
- Package the jiplet classes/descriptors into a directory or package them into a single archive file (called SIP archive or SPR for short – equivalent of WAR in servlet terminology).
- Copy the package into a well-known deployment directory and re-start the jiplet container program. Alternatively, use the Jiplet Console management application that comes with the jiplet container to deploy the package. This approach does not require the container to be re-started.
The jiplet container is an open-source server application from CafeSip.org where jiplet applications can be deployed. The jiplet container listens for SIP messages on configured ports and when a message is received, the container hands it over to a jiplet based on configured jiplet-selection criteria. The container also provides other services to jiplet applications including the following:
- Support for multiple jiplet applications that are isolated from each other.
- Timer services.
- Scoped variables.
- API for proxying SIP messages.
- SIP event forwarding between jiplets.
- Logging and tracing.
- Tunable security for jiplet contexts.
- Management of jiplets using JMX and a web-based user interface.
- Container-managed authenitcation and authorization including pluggable authentication realms.
It is very similar in concept to a servlet container like Tomcat, Jetty, etc. The jiplet container can run in two modes:
- Standalone jiplet container: In this mode, you can install and run the jiplet container as a standalone Java application. No additional software is needed and it is simpler to setup and operate.
- Jiplet container as a JBOSS service: In this mode, the jiplet container is run as a service inside the JBOSS server. JBOSS is a very popular open-source implementation of the J2EE technology. In this mode, the jiplet container is managed by JBOSS and jiplet applications can easily access other J2EE components like EJBs, JMS services, web services and servlet/JSP services. The SIP archive or SPR files can be deploying using standard JBOSS-supported deployment techniques. In addition, the jiplet applications can be archived into an Enterprise Archive (EAR). EAR files are deployed using the standard JBOSS deployment method.
You can install the jiplet container in either mode.
Which one should I use – the standalone jiplet container or jiplet container running as a JBOSS service?
It depends on your requirements and the jiplet applications that you are going to deploy. The standalone jiplet container application is easier to install and does not require any knowledge of the JBOSS server. The JBOSS server is a full-fledged J2EE container and therefore requires a good understanding of J2EE concepts. In addition, you will need to know how to install, configure and setup the JBOSS server. Also, the standalone jiplet container may require less memory resources and may run better on a smaller computer. However, if you have figured this out or are already familiar with JBOSS and have a high-end system, in our opinion, the JBOSS service is a better option.
More importantly, the jiplet container is nothing but a container for jiplet application(s). A jiplet application may use J2EE entities like EJBs for some of its functionalities. If that is the case, it may be more efficient to use the jiplet container running as a JBOSS service. In upcoming releases, we may add additional features to the JBOSS service that may not be available for the standalone application.
The jiplet container is a 100% pure Java application. Therefore, it can be run in any system that supports Java. This includes most platforms including Microsoft Windows, Linux, Solaris, Mac, other UNIX flavors, etc. The jiplet container can be run in one of two modes:
- Standalone Java application: In this mode, all you need is a Java 1.4 or higher runtime environment (JRE) installed on your computer. The jiplet container comes in a ZIP package that is extracted into a directory of your choice. It can be configured to run as a Linux/Unix or Windows service, and shell scripts have been provided for both environments. For Windows 98, ME, MAC, VMS, etc., you can modify the supplied shell scripts to suit your environment. The container also comes with the Jiplet Console management application. This application consists of a number of Java servlets that can be installed under any Servlet Container. We have tested the application using Apache Tomcat. Note that the installation of the Jiplet Console is optional. However, if you don’t install it, you do not get many of the features that come with the Jiplet Container.
- J2EE service: In this mode, the jiplet container is installed as a J2EE service. You will need a JBOSS J2EE server in order to run jiplet container in this mode. You can obtain a copy of JBOSS from http://www.jboss.org. The jiplet container service archive (SAR) file can be downloaded and deployed using standard JBOSS deployment procedures. JBOSS runs on Linux, Windows, UNIX and other platforms. In this mode, it is easier to create jiplet applications that use J2EE features like JNDI,EJB, etc.
They are very similar in concept. A servlet container hosts one or more servlet contexts (applications) that handle HTTP messages from web browsers. Similarly, a jiplet container hosts one or more jiplet contexts (applications) that handle SIP messages from SIP phones and other network elements and devices. There is a lot of similarity between the SIP and HTTP protocols and therefore there is a lot of similarity between how a jiplet works and how a servlet works. Likewise there are parallels in the respective containers:
- Like the servlet container, the jiplet container provides a number of additional services to the jiplets. It provides a way to deploy and undeploy jiplet contexts on the fly.
- Like the servlet container, the application is packaged in a deployable bundle and a descriptor file defines the jiplets, mappings and other specifications. For servlets, the descriptor file is called web.xml and for jiplets, it is called jip.xml.
- A jiplet container provides jiplet mapping capabilities similar to servlet containers. When a HTTP message is received by a servlet container, the message is passed on to a servlet based on certain criteria specified by the web.xml file. Similarly, a jiplet container, on receiving a SIP request message, passes the message to a jiplet based on selection criteria specified in the jip.xml file. The servlet container selects a servlet based on the URL whereas the jiplet container selects the jiplet based on the SIP request method and/or header fields.
- A jiplet container supports scoped variables similar to servlet containers. Scoped variables can be added/retrieved/deleted by jiplet applications and are only visible during certain states of the jiplet. For more details, click here.
- A jiplet container supports event forwarding from one jiplet to another similar to the way a servlet container supports forwarding requests between servlets. Event-scope variables are visible to jiplets just like request-scope variables are visible to the servlets.
- A jiplet can print log messages to the container’s logging system similar to how a servlet can print log messages. However, the logging mechanism supported by the jiplet container is more extensive.
- The jiplet container supports security constraints similar to servlet containers. When a SIP request message, the jiplet container automatically authenticates the SIP end points and applies security policy before handing the received request messages to the jiplets. That is, the authentication mechanism specified for SIP messages is handled by the container.
- COMING SOON. A jiplet container will provide the resource name lookup and EJB references similar to a servlet container.
The jiplet container supports the following types of scoped variables:
- Application: can be accessed by any jiplets inside a context similar to the servlet application-scope variables.
- Session: a session identifies a SIP call based on the Call ID field in the message. The variables can be accessed by the jiplets handling the same session. It is similar to the session-scope variables supported by the servlet technology.
- Event: can be accessed by all jiplets that handle a SIP request, response, time-out and timer event. This is similar to request-scope variables in servlets. However, due to the nature of the protocol, it is more extensive in nature compared to a java servlet.
- Transaction: transaction scope variables are visible to jiplets during the lifetime of a SIP transaction. There is nothing equivalent in the servlet world.
- Dialog: dialog scope variables are visible to jiplets during the lifetime of a SIP dialog. There is nothing equivalent in the servlet world.
The jiplet container provides Digest authentication treatment to SIP user agents as specified by RFC 2617. The jiplet container provides authentication and authorization on behalf of the jiplets. This feature is called the Container-Managed Authentication and Authorization (CMAA). The authentication involves validating the user agent using Digest-based authentication as specified by RFC 2617. In addition, the container also determines if a SIP user agent is authorized to deliver SIP request messages to a jiplet based of the privilege level (role) defined for the user agent. This feature allows jiplet applications to concentrate on the business logic instead of having to handle all aspects of SIP protocol including authentication and authorization. Each jiplet application can specify security constraints similar to how servlets specify security constraints. When a SIP request message is received and is selected for deliivery to a jiplet, the container checks the security constraint in order to authenticate the user. If and only if the authentication is successful and the authorization checks pass, the message delivered to the selected jiplets.
As a part of the CMAA, the jiplet container provides protected domains or realms. A realm is basically an user database that contain authentication and authorization information that the jiplet container looks up when a SIP request message is received with appropriate authentication header. The jiplet container supports the concept of pluggable realms. That is, a service provider can easily incorporate customized authentication modules or plugin existing subscriber databases. The jiplet container comes with two database realms that are ready to use:
- Memory Realm: This is a memory-resident database that is read from an XML configuration file on initialization. The configuration file contains user names, password and privilege (role) information.
- JDBC Realm: The authentication information is stored in a JDBC-compliant database and is looked up using SQL queries.
You can create your own realms and deploy them on the fly using deployment mechanisms similar to how jiplet contexts are deployed. From the jiplet console, you can deploy your custom realms.
In addition, a JMX interface is exposed by the jiplet container for providing support for provisioning by external management applications. The JMX interface enables management application to list, create, modify and delete user accounts. The jiplet console already comes with a generic web-based user interface for provisioning user accounts for a given realm. Note: a realm has to support the provisioning interface in order for this to work. The JDBC realm provided with the jiplet container supports provisioning.
Yes, the jiplet container supports the proxy functionality. Proxying SIP request and response messages is a very common function for most server-side SIP applications. The jiplet container provides easy-to-use classes that can be instantiated from a jiplet and used for proxying SIP request and response messages. The SipCommunicator class supports flexible handling of the proxy functions and supports both stateless and stateful proxying. In addition, a standard jiplet called ProxyJiplet is included with the jiplet container packages that enable jiplet applications to handle the functionality without even creating a jiplet class. The ProxyJiplet can be used from any application. It can be configured to support stateful and stateless proxying as well as other other proxy features. You can deploy the ProxyJiplet without having to write any code for most standard proxy functions.
When running as a JBOSS service, the jiplet container supports the naming context, Each jiplet context has its own naming context and any jiplet can use the Java naming API to get an initial context and perform naming operations. The jiplet container also supports <env-entry>, <ejb-ref> and other naming-related elements in the jiplet deployment descriptor similar to those supported by Java servlets.The standalone application does not currently provide an internal JNDI server. This will be done in the upcoming releases. However, jiplet applications can still use external JNDI servers.
The main differences between the jiplet and servlet containers stem from the differences between the SIP and HTTP protocols. HTTP requests are almost always a single request-response transaction whereas SIP messaging may involve a single request with multiple responses. Another major difference is that the SIP server application may need to initiate a transaction unlike the web application which always responds to requests from a HTTP client. To accommodate these differences, there are significant differences between jiplets and servlets.
As we understand, there are multiple approaches to developing SIP server side applications. There are programming libraries available for the C/C++ environment and possibly for other programming languages as well. For the Java programming language, there are a number of options – some of them are proprietary, others are open-source. Through its community license program, Sun Microsystems has made three specifications available and there are various open-source and proprietary implementations. They are:
- JAIN SIP API: Low-level API for creating SIP client and server-side applications. It is a comprehensive API with an open-source implementation from NIST. The jiplet container uses this API as the underlying stack and also exposes many of the classes to the jiplet application.
- SIP Servlet specification: Extends the Java servlet API and is specified by JSR 116. This approach is very similar to jiplets. In fact, a lot of the ideas behind the Jiplet were borrowed from this specification. As far as we know, there are no truly open-source implementations available. We receive lost of emails on how this specification is similar to or different from the jiplet. So, we have created a page that explains it. Click here to read the comparison.
- JAIN SLEE: This approach envisions SIP applications running in the J2EE environment. As far as we know, there are no truly open-source implementations available and is very complex.
We think that the jiplet concept adopts the best practices from all of the above. The jiplet API uses the JAIN-SIP API for implementing SIP messaging, and jiplet developers need to understand the JAIN-SIP API to develop jiplet applications. However, it adds many additional services that the JAIN-SIP API does not provide. Some of these services include:
- Deployment of multiple SIP applications isolated from each other.
- Management of threads.
- Scoped-variables and forwarding events between jiplets.
- Timer service.
- Logging and tracing services.
- Management application infrastructure using JMX.
- Integration with a J2EE container (JBOSS).
- Container-managed authentication and authorization..
Compared to the SIP servlet API, the jiplet lacks some of the capabilities but it provides additional capabilities that the specification does not handle well – namely, the service provider model. This is explained in more details below.
By integrating tightly with the J2EE container, the jiplet container provides full J2EE capabilities to the jiplets very similar to how JAIN-SLEE envisions providing J2EE capabilities to SIP applications.
The jiplet container is designed to be deployed in a service provider environment. There are currently service providers that host web sites for their customers. The customers just provide the content and the service provider provides the Internet infrastructure. The same concept has been extended to provide hosting of custom web applications and services. It is very easy to find service providers offering application hosting using servlet/JSP or other technologies.
We envision that in the near future, there will be service providers that host custom SIP applications from their customers. Customers will create customized SIP applications and service providers will host them using their SIP network infrastructure. For this to work, the following needs to happen:
- The service provider must be able to completely isolate one customer’s application from another.
- The service provider’s infrastructure must be able to apply selection criteria in order to route specific SIP messages to specific customers’ applications.
- The service provider should be able to partition SIP traffic on a per-customer/domain or network basis in order to provide varying quality of service.
- Controlled access to specific resources by the applications using Java security features.
The jiplet container provides many of these features already.
The jiplet container server can run in two modes, the second of which facilitates SIP application/J2EE integration:
- a standalone Java application. In this mode, the jiplet container runs as a standalone Java application that is launched from a shell script. It can also be configured to run as a service (started and stopped by the operating system) in the Linux and Windows environment. The jiplet container comes with a web-based management application for managing contexts. In order to use this application, a servlet container like Tomcat must be running on the system.
- a J2EE service. In this mode, the jiplet environment is integrated with a J2EE server. The jiplet container is started as a service within the J2EE server and, therefore, can be managed by the J2EE management application. The web-based application for managing the jiplets (explained above) is also deployed as a web application inside the J2EE container. In this environment, jiplet applications have access to other J2EE services like EJBs, SOAP services, web services, etc. Currently, the jiplet system has been tested with the JBOSS J2EE server. In the J2EE mode, jiplet applications can also be deployed similar to J2EE web applications or EJBs. In this mode, the jiplet container also supports the dynamic deployment of jiplet application using standard JBOSS deployment technioques. In addition, it also supports the deployment of Enterprise archives (EAR) where multiple J2EE components like EJBS, jiplet contexts, connectors, etc. are bundled together in a single archive and deployed.
First, you need to learn the Java programming language and you must be familiar with the Java servlet architecture. There are many tutorials available on the web on Java servlets. Just search the web to find one. You also need to learn the JAIN-SIP API because you will need to use it from inside the jiplet classes. Next, you need to download the jiplet container binary package and install it as per the installation instructions. The package comes with javadocs that explain the classes available to you. Also read the Jiplet Developer Guide. Next design and code the jiplets using the jiplet development libraries provided and package the files using the standard jar/zip tools or by using the Ant task provided by the jiplet development environment. Finally, deploy the application using either the web-based management console that comes with the jiplet container or by copying the application bundle to a specified directory and re-starting the container.
The jiplet container comes with a web-based management application called the Jiplet Console. Using the console, jiplet applications can be deployed and removed, and application properties can be queried. If applications need to provide additional control, the application developers can create and register JMX MBEANS from within jiplet applications. Java Management Extensions (JMX) is a Java standard for creating management applications and comes with extensive support for developing such applications. MBEANS are java bean classes that can be accessed remotely by management applications. By registering a MBEAN with the jiplet container, jiplet applications provide an interface using which remote management applications can connect to the jiplet application and invoke remote methods. For the standalone jiplet container, the MX4J implementation of JMX is used. When running as a JBOSS service, the JBOSS implementation of JMX is used.
Note that the Jiplet Console is not necessary for deploying/undeploying applications. A jiplet application can be simply dropped into the deploy directory of the jiplet container for the application to be deployed. Similarly, it can be removed by deleting it from the deploy directory. Note that unlike many servlet containers, the jiplet container does not monitor the deploy directory for changes. Therefore, when using this method, the jiplet container has to be restarted in order for it to see the change. This limitation is not there when using the Jiplet Console or when the jiplet container is running as a JBOSS service.
The jiplet container comes with no tools at the moment except for an Ant task to create SPR files from your Ant build file. We do plan to add the following tools in future releases:
- Jiplet IDE plugin for the Eclipse IDE. This IDE plugin will provide standard jiplet templates, create descriptors from Javadoc comments, etc.
- Jiplet Monitor: A monitoring tool for viewing jiplet activities.
SipUnit is another tool from CafeSip.org that you will find very useful if you follow the automated test approach for jiplet application development. SipUnit makes it possible to develop SIP (User Agent) UA-based tests for testing out the jiplet applications created by you.
Please send an email to firstname.lastname@example.org or use the CafeSip bug/enhancement tracking tool. We are open to suggestions and feedback, especially from experienced SIP developers.