EchoServlet Tutorial

Checking the Operation

Once deploying the SIP application, you can test its operation.

Check <servlet-mapping> settings in the sip.xml file to see that filter conditions of the SIP application in SIP Servlet Engine and those in this sample do not overlap. When you use sip-demo, all MESSAGE requests are configured to be forwarded to the "chat" servlet. You must comment out this part or reconfigure it so that only particular users are sent to the Echo servlet.

Figure 4 shows an OKISoftphone screen appeared when MESSAGE is sent. Figure 5 shows the SIP sequence. Figure 6 shows results in captured packets.

Chat Session Establishment

At the beginning of a chat, the sender side sends the MESSAGE with its empty body to establish the chat session. The receiver terminal responds to this with a 302 and the sender side sends the message with its body to the Contact.

Chat Session Completion

At the end of a chat, the sender side sends the MESSAGE containing only the SIP URI of the sender.

Chat Message Sending

In normal message sending, the sender sends the MESSAGE containing the SIP URI of the sender on the first line, followed by the message body on the subsequent lines and : at the end.

You can see from the specification, Figure 5 and 6 that each message belongs to one of the following types.

F1 and F2

Chat Session Establishment

F3 - F6

Chat Message Sending Messages from F3 to F6 comprise a group for sending and receiving. Every time a message is sent from OKISoftphone, the four messages are carried over the network

F7 and F8

Chat Session Completion

Figure 4: OKISoftphone Chat Screen

Figure 5: Sequence Diagram

Figure 6: SIP Messages

[F1]

MESSAGE sip:echo@act2343.eoa.telcom.oki.co.jp SIP/2.0
Via: SIP/2.0/UDP 172.21.164.217:5060;branch=z9hG4bK75db1c40
Max-Forwards: 70
To: sip:echo@act2343.eoa.telcom.oki.co.jp
From: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=172891200
Call-ID: 79131c40-7b82800ca5d44a37805b1d246a09575f@act2865
CSeq: 1 MESSAGE
Allow: INVITE,ACK,CANCEL,BYE,INFO,MESSAGE,SUBSCRIBE,NOTIFY
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp
Content-Type: text/plain
Content-Length: 0

[F2]

SIP/2.0 302 Moved Temporarily
Call-ID: 79131c40-7b82800ca5d44a37805b1d246a09575f@act2865
CSeq: 1 MESSAGE
From: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=172891200
To: <sip:echo@act2343.eoa.telcom.oki.co.jp>;tag=jtag-3f4be5da-514a-4dff-b755-bf4de59c1d9f
Via: SIP/2.0/UDP 172.21.164.217:5060;branch=z9hG4bK75db1c40
Contact: sip:act2343.eoa.telcom.oki.co.jp:5060
Content-Length: 0
Server: OKI CenterStage AP V2.0
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp

[F3-a]

MESSAGE sip:act2343.eoa.telcom.oki.co.jp:5060 SIP/2.0
Via: SIP/2.0/UDP 172.21.164.217:5060;branch=z9hG4bK60091c40
Max-Forwards: 70
To: sip:echo@act2343.eoa.telcom.oki.co.jp
From: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=140647488
Call-ID: 26651c40-b2dd0e09b02b475e872cb593ffd7a608@act2865
CSeq: 1 MESSAGE
Allow: INVITE,ACK,CANCEL,BYE,INFO,MESSAGE,SUBSCRIBE,NOTIFY
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp
Content-Type: text/plain
Content-Length: 51

sip:fukuda445@act2343.eoa.telcom.oki.co.jp\r\n
abcdef:

[F4-a]

SIP/2.0 200 OK
Call-ID: 26651c40-b2dd0e09b02b475e872cb593ffd7a608@act2865
CSeq: 1 MESSAGE
From: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=140647488
To: <sip:echo@act2343.eoa.telcom.oki.co.jp>;tag=jtag-c1fbd9cd-2027-4bae-81d4-a08000141107
Via: SIP/2.0/UDP 172.21.164.217:5060;branch=z9hG4bK60091c40
Content-Length: 0
Server: OKI CenterStage AP V2.0
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp

[F5-a]

MESSAGE sip:172.21.164.217:5060 SIP/2.0
Call-ID: b22ddfd5-9e1d-4469-a315-9d6040ae761f@172.21.164.21
CSeq: 1 MESSAGE
From: <sip:echo@act2343.eoa.telcom.oki.co.jp>;tag=jtag-0e41ae8b-7518-4ea4-b4b7-93861f58bdc7
To: <sip:fukuda445@act2343.eoa.telcom.oki.co.jp>
Via: SIP/2.0/UDP act2343.eoa.telcom.oki.co.jp:5060;branch=z9hG4bK1gdgcs
Contact: <sip:act2343.eoa.telcom.oki.co.jp:5060;transport=udp>
Max-Forwards: 70
Content-Length: 46
Content-Type: text/plain; charset=UTF-8
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp

sip:echo@act2343.eoa.telcom.oki.co.jp\r\n
ABCDEF:

[F6-a]

SIP/2.0 200 Ok
Via: SIP/2.0/UDP act2343.eoa.telcom.oki.co.jp:5060;received=172.21.164.21;branch=z9hG4bK1gdgcs
To: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=1736711233
From: sip:echo@act2343.eoa.telcom.oki.co.jp;tag=jtag-0e41ae8b-7518-4ea4-b4b7-93861f58bdc7
Call-ID: b22ddfd5-9e1d-4469-a315-9d6040ae761f@172.21.164.21
CSeq: 1 MESSAGE
Allow: INVITE,ACK,CANCEL,BYE,INFO,MESSAGE,SUBSCRIBE,NOTIFY
Content-Length: 0

[F3-b]

MESSAGE sip:act2343.eoa.telcom.oki.co.jp:5060 SIP/2.0
Via: SIP/2.0/UDP 172.21.164.217:5060;branch=z9hG4bK60461c47
Max-Forwards: 70
To: sip:echo@act2343.eoa.telcom.oki.co.jp
From: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=1420958791
Call-ID: 16eb1c47-47c2929079fa4a5c9ef7cea6e9a59c96@act2865
CSeq: 1 MESSAGE
Allow: INVITE,ACK,CANCEL,BYE,INFO,MESSAGE,SUBSCRIBE,NOTIFY
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp
Content-Type: text/plain
Content-Length: 51

sip:fukuda445@act2343.eoa.telcom.oki.co.jp\r\n
ijklmn:

[F4-b]

SIP/2.0 200 OK
Call-ID: 16eb1c47-47c2929079fa4a5c9ef7cea6e9a59c96@act2865
CSeq: 1 MESSAGE
From: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=1420958791
To: <sip:echo@act2343.eoa.telcom.oki.co.jp>;tag=jtag-3951db36-1fb4-4676-8967-ed6ee4cfba20
Via: SIP/2.0/UDP 172.21.164.217:5060;branch=z9hG4bK60461c47
Content-Length: 0
Server: OKI CenterStage AP V2.0
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp

[F5-b]

MESSAGE sip:172.21.164.217:5060 SIP/2.0
Call-ID: 4390970c-4fdf-4bd0-84a9-837697b55406@172.21.164.21
CSeq: 1 MESSAGE
From: <sip:echo@act2343.eoa.telcom.oki.co.jp>;tag=jtag-f5539851-7474-4c37-8022-bcb9c50b52b7
To: <sip:fukuda445@act2343.eoa.telcom.oki.co.jp>
Via: SIP/2.0/UDP act2343.eoa.telcom.oki.co.jp:5060;branch=z9hG4bK4w7ch7
Contact: <sip:act2343.eoa.telcom.oki.co.jp:5060;transport=udp>
Max-Forwards: 70
Content-Length: 46
Content-Type: text/plain; charset=UTF-8
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp

sip:echo@act2343.eoa.telcom.oki.co.jp\r\n
IJKLMN:

[F6-b]

SIP/2.0 200 Ok
Via: SIP/2.0/UDP act2343.eoa.telcom.oki.co.jp:5060;received=172.21.164.21;branch=z9hG4bK4w7ch7
To: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=1256266824
From: sip:echo@act2343.eoa.telcom.oki.co.jp;tag=jtag-f5539851-7474-4c37-8022-bcb9c50b52b7
Call-ID: 4390970c-4fdf-4bd0-84a9-837697b55406@172.21.164.21
CSeq: 1 MESSAGE
Allow: INVITE,ACK,CANCEL,BYE,INFO,MESSAGE,SUBSCRIBE,NOTIFY
Content-Length: 0

[F7]

MESSAGE sip:act2343.eoa.telcom.oki.co.jp:5060 SIP/2.0
Via: SIP/2.0/UDP 172.21.164.217:5060;branch=z9hG4bK175f1c4c
Max-Forwards: 70
To: sip:echo@act2343.eoa.telcom.oki.co.jp
From: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=333126732
Call-ID: 6a401c4c-50812d60621c4d869e53942c154a6001@act2865
CSeq: 1 MESSAGE
Allow: INVITE,ACK,CANCEL,BYE,INFO,MESSAGE,SUBSCRIBE,NOTIFY
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp
Content-Type: text/plain
Content-Length: 42

sip:fukuda445@act2343.eoa.telcom.oki.co.jp

[F8]

SIP/2.0 200 OK
Call-ID: 6a401c4c-50812d60621c4d869e53942c154a6001@act2865
CSeq: 1 MESSAGE
From: sip:fukuda445@act2343.eoa.telcom.oki.co.jp;tag=333126732
To: <sip:echo@act2343.eoa.telcom.oki.co.jp>;tag=jtag-4f623ef6-4292-433d-b3f0-e53c3718534f
Via: SIP/2.0/UDP 172.21.164.217:5060;branch=z9hG4bK175f1c4c
Content-Length: 0
Server: OKI CenterStage AP V2.0
X-Chat-Id: 359629bbcfd8070224632.fukuda445@act2343.eoa.telcom.oki.co.jp

Appendix 1: Description of EchoServlet Program

As described earlier, EchoServlet is an application that converts a received message from OKISoftphone to upper case and sends it back.

List 4 shows the source code of the Echo servlet.

List 4: EchoServlet.java

001: package com.oki.sip.tutorial;
002:
003: import java.io.*;
004: import javax.servlet.*;
005: import javax.servlet.sip.*;
006: import com.oki.sip.equips.signal.BasicSipServlet;
007:
008: public class EchoServlet extends BasicSipServlet {
009:
010:     public void init() throws ServletException {
011:         super.init();
012:     }
013:
014:     /**
015:      * Method invoked upon receiving MESSAGE method.
016:      */
017:     protected void doMessage(SipServletRequest req)
018:         throws ServletException, IOException
019:     {
020:         if(req.getContentLength() == 0) {
021:             initChat(req);
022:             return;
023:         }
024:
025:         // Retrieves information from request
026:         String msg = (String) req.getContent();
027:
028:         // Isolates sender information (msender) from message body (mbody).
029:         String msender = null;
030:         String mbody = null;
031:         int index = msg.indexOf("\r\n");
032:         if(index > 0) {
033:             msender = msg.substring(0, index);
034:             mbody = msg.substring(index + 2);
035:             if(mbody.endsWith(":"))
036:                 mbody = mbody.substring(0, mbody.length() - 1);
037:         } else {
038:             msender = msg.trim();
039:             mbody = null;
040:         }
041:
042:         if(mbody == null) {
043:             terminateChat(req);
044:         } else {
045:             sendChat(req, mbody);
046:         }
047:     }
048:
049:     /**
050:      * Method that establishes new chat session.
051:      */
052:     private void initChat(SipServletRequest req)
053:         throws IOException, ServletException
054:     {
055:         SipServletResponse res = createResponse(req, 302);
056:
057:         res.setAddressHeader("Contact", getLocalContact(req));
058:         res.send();
059:         invalidateAppSession(res);
060:     }
061:
062:     /**
050:      * Method that sends messages to chat session.
064:      */
065:     private void sendChat(SipServletRequest req, String mbody)
066:         throws IOException, ServletException
067:     {
068:         Address remote = req.getFrom();
069:         Address local = req.getTo();
070:         String chatID = req.getHeader("X-Chat-Id");
071:
072:         // Sends 200 response.
073:         SipServletResponse res = createResponse(req, 200);
074:         res.send();
075:         invalidateAppSession(res);
076:
077:         // Creates message body.
078:         String emsg = local.getURI().toString() + "\r\n" + mbody.toUpperCase() + ":";
079:
080:         // Gets destination contact information from location management.
081:         SipURI remoteURI = (SipURI) remote.getURI();
082:         Address contact = (Address) getLocation().getContacts(remoteURI, null).get(0);
083:
084:         // Create SIP request.
085:         SipApplicationSession appSession = getSipFactory().createApplicationSession();
086:         SipServletRequest req2 = initiateRequest(appSession,
087:                                                  "MESSAGE",
088:                                                  local,
089:                                                  remote);
090:         req2.setContent(emsg, "text/plain; charset=UTF-8");
091:         req2.setHeader("X-Chat-Id", chatID);
092:         req2.setRequestURI((SipURI) contact.getURI());
093:
094:         // Sends SIP request.
095:         req2.send();
096:     }
097:
098:     /**
099:      * Method that discards chat session.
100:      * 200 response.
101:      */
102:     private void terminateChat(SipServletRequest req)
103:         throws IOException
104:     {
105:         SipServletResponse res = createResponse(req, 200);
106:         res.send();
107:         invalidateAppSession(res);
108:     }
109:
110:     /**
111:      * Method that handles response to MESSAGE sent form SIP servlet.
112:      */
113:     protected void doResponse(SipServletResponse res)
114:         throws IOException, ServletException
115:     {
116:         if(res.getStatus() >= 200)  // If last response,
117:             invalidateAppSession(res);
118:     }
119:
120:     /**
121:      * Method that creates contact information from SipServletRequest.
122:      */
123:     private Address getLocalContact(SipServletRequest req)
124:         throws ServletParseException
125:     {
126:         StringBuffer sb = new StringBuffer();
127:         sb.append("sip:");
128:         sb.append(req.getLocalAddr());
129:         if(req.getLocalPort() > 0) {
130:             sb.append(":");
131:             sb.append(req.getLocalPort());
132:         }
133:
134:         return getSipFactory().createAddress(sb.toString());
135:     }
136:
137:     /**
138:      * Method that creates response that is a copy of X-Chat-Id header.
139:      */
140:     private SipServletResponse createResponse(SipServletRequest req, int code) {
141:         SipServletResponse res = req.createResponse(code);
142:         String chatID = req.getHeader("X-Chat-Id");
143:         if(chatID != null)
144:             res.setHeader("X-Chat-Id", chatID);
145:
146:         return res;
147:     }
148:
149:     /**
150:      * Method that disables AP session.
151:      */
152:     private void invalidateAppSession(SipServletResponse res) {
153:         SipSession session = res.getSession();
154:         SipApplicationSession appSession = session.getApplicationSession();
155:         appSession.invalidate();
156:     }
157: }

The following describes the operation of the program.

The init method specifies initialization parameter settings (<init-param>) in the sip.xml file. This program only initializes its parent class since it has no initialization parameters. (Line 11)

An implementation of the SipServlet init method of SIP Servlet API 1.0 has a bug. Normally, an HTTP servlet can invoke the init method on the parent class without explicitly calling super.init(). In SipServlet, this call is not executed.

Next, invoke the doMessage() method that describes operations of the program body. (Line 17). This method is called each time the SIP servlet container receives a MESSAGE request.

Appendix 2: Collaboration with CenterStage-NS

In the preceding sections, you have deployed your application on SIP Servlet Engine, directly connected the engine, and performed validation. These steps are suitable in the development phase. But in the production phase you normally make Sip Servlet Engine work with CenterStage-NS. In this case, requests from a client are delivered to a SIP Servlet Engine application through CenterStage-NS.

It is recommend that you use NumberMap as a means of sending messages from a client to SIP Servlet Engine via CenterStage-NS. Using NumberMap, you can register multiple destinations with a single SIP URI (specifically, its user part) and specify SIP Servlet Engines in list form. CenterStage-NS performs regular health checks on these servers. If one server fails, you can automatically select any available application server.

For information about collaboration with CenterStage-NS, see the administrators guide.

   protected void doOptions(SipServletRequest req)
       throws ServletException, IOException
   {
       // Sends 200 response.
       SipServletResponse res = req.createResponse(200);
       res.send();
   }

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

 <!DOCTYPE sip-app
    PUBLIC "-//Java Community Process//DTD SIP Application 1.0//EN"
    "http://www.jcp.org/dtd/sip-app_1_0.dtd">

 <sip-app>
   <display-name>SIP Servlet Tutorial</display-name>

   <servlet>
     <servlet-name>echo</servlet-name>
     <servlet-class>com.oki.sip.tutorial.EchoServlet02</servlet-class>
     <load-on-startup/>
   </servlet>

   <servlet-mapping>
     <servlet-name>echo</servlet-name>
     <pattern>
       <or>
         <and>
           <equal>
             <var>request.to.uri.user</var>
             <value>0123456</value>
           </equal>
           <equal>
             <var>request.method</var>
             <value>MESSAGE</value>
           </equal>
         </and>
         <and>
           <equal>
             <var>request.method</var>
             <value>OPTIONS</value>
           </equal>
         </and>
       </or>
     </pattern>
   </servlet-mapping>
   <session-config>
     <session-timeout>1</session-timeout>
   </session-config>
 </sip-app>

 <!-- Define filter -->
 <filter classname="com.oki.sip.engine.security.BlockingFilter"/>
 <filter classname="com.oki.sip.engine.security.WLSSecurityManagerFilter">
   <filter-param>
     <param-name>trustedHost</param-name>
     <param-value>siplb.oki.co.jp,172.22.0.3,172.22.0.4</param-value>
   </filter-param>
 </filter>

 <configurationparameters>
   <scope>
     <name>NumberMappingRules</name>
     <Entry>
       <TelNumber>0123456</TelNumber>
       <IPAddress>172.21.164.21</IPAddress>
     </Entry>
   </scope>
 </configurationparameters>

 $ su ops                  [Become OpS user]
 Password: ***             [OpS use password]
 % hltmon stop             [Stop health check]
 % cnf rld                 [Execute reload command]
 Start......
 Configuration Reloaded.
 End........
 % hltmon start            [Start health check]
 % exit                    [Exit OpS user]

 $ su ops                  [Become OpS user]
 Password: ***             [OpS use password]
 % get number-map        [Command to display NumberMap settings]
 Prefix          IP Address
 ======          ==========
 0123456         172.21.164.21

 % get mgc-route         [Command to get status of destination]
 IP Address              Status
 ==========              ======
 172.21.164.21            UP

 % cnf get ServerInfo ServerNames  [Command to get config value]
 Start......
 Scope: ServerInfo
 Name : ServerNames
 Value: act2343.eoa.telcom.oki.co.jp,dm1.oii.oki.co.jp,172.21.164.21
 End........