8 Sample Application

A non-trivial example application, called TimeBomb, is included in the examples/timeBomb directory of the development kit. This application allows two parties to talk for at most 5 seconds. TimeBomb is a back-to-back user agent application which, prior to timing out, modifies the Request-URI of the outgoing INVITE and then acts transparently.

/***********************************************************************
*                                                                      *
*               This software is part of the ECharts package           *
*                  Copyright (c) 2006-2009 AT&T Corp.                  *
*                      and is licensed under the                       *
*                  Common Public License, Version 1.0                  *
*                            by AT&T Corp.                             *
*                                                                      *
***********************************************************************/
package examples.timeBomb;

import java.util.Properties;
import javax.servlet.ServletContext;

import org.echarts.servlet.sip.*;
import org.echarts.servlet.sip.messages.*;
import org.echarts.servlet.sip.machines.*;

/** Example machine that places B2BUA call, then tears down call 5 seconds
*  after call is connected.
*/

public machine TimeBombFSM  {
<*
    FeatureBox box;
    SipPort    caller;
    SipPort    callee;
*>

    /** Used when this FSM is specified as machineClassName by EChartsSipServlet
    */
    public TimeBombFSM(FeatureBox box, Properties servletProps, ServletContext context) {
            this.box    = box;
            this.caller = box.createSipPort("caller");
            this.callee = box.createSipPort("callee");
    }

    /** Initially, place a B2BUA call using a simple RequestModifier.
     */
    initial state CALL : B2buaSafeFSM(box, caller, callee, box.getDefaultModifier());

    /** Once the call is CONNECTED, we want to start the timer.
     */
    transition CALL.ACTIVE.INITIAL_INVITE.SUCCESS --> TICKING;

    /** While the timer is running, behave transparently.
     */
    state TICKING : TransparentFSM(caller, callee);

    /** After 5 sec in TICKING state, end calls by going to terminal state.
     */
    transition TICKING - delay(5000) -> END;

    /** Terminal state: simple state with no outgoing transitions.
     */
    state END;

    /** If the B2BUA reaches a terminal state before CONNECTED, then end execution.
     */
    transition CALL.TERMINAL --> END;

    /** If the call ends normally before the timer fires, end execution.
     */
    transition TICKING.TERMINAL --> END;
}

The TimeBomb application makes use of several other general-purpose ECharts machines, either directly or indirectly, also included in the ECharts for SIP Servlets development kit.

As you can see, by reusing the B2BUA logic it becomes a simple matter to provide default B2BUA behavior (which handles SIP errors setting up the call, CANCEL messages sent by the caller, re-INVITEs, etc.) while specifying an override for non-default behavior.

8.1 Building and Testing the Sample

The TimeBomb application directory structure, build files and deployment descriptors were created using the appgen tool described in Section 7. In this example we will show how to build the application and test it using the KitCAT test framework included with the E4SS development kit.

Prior to building the sample, change to the test subdirectory and then modify build.properties and env.properties as desired. In particular, you should modify the ext.classpath property in env.properties to include the two jar files necessary to build the example. The first jar file includes the classes defined in the javax.servlet package. The second jar file includes the classes defined in the javax.servlet.sip package. These jar files are included with any SIP servlet container. You must also either modify the edk.home property to point to your ECharts for SIP Servlets development kit location, or set the EDK_HOME environment variable to point to its location.

To build the sample type ant fatsar. This will build a war file with the name specified in build.properties. This war file can be deployed to your JSR 289-compliant container (for information on configuring a container to use E4SS, see Appendix A).

Prior to testing the sample, modify the file test.properties as necessary. Then to test the sample, type ant test. This will run the application test cases defined in test/src/testcases/examples/timeBomb/test/TimeBombFSMTest.java. For more information on application testing see Section 6.

Assuming E4SS logging is configured for your container (see Appendix A), then the application’s log will contain a complete record of the SIP messages input and output by the application as well as a transcription of the transitions that fired during the execution of the application’s ECharts machine.

8.2 Generating Documentation

To generate javadoc documentation for the example, you need to install the open source graphviz package, available from the graphviz.org website. This package is used to generate a graphical representation of application machines and integrates them with the javadoc pages. Then enter the command ant javadoc. This will generate the documentation in the doc/api directory. See the ECharts User Manual [2] for more information related to generating and viewing javadoc documentation generated this way.