Skip to main content

Re: SIP Outbound first draft of use cases

  • From: Nitzan Nissim < >
  • To:
  • Subject: Re: SIP Outbound first draft of use cases
  • Date: Mon, 8 Apr 2013 18:18:48 +0300
  • List-id: <>

I have created a document based on Jean's that includes comments on the
currently suggest API and the examples, as well as suggestions for
enhancement of the API.

The suggested API is meant not to replace the current proposal, but serve
as an addition, to allow a mode of operation where the container performs
more of the NAT traversal tasks of RFC 5626 automatically.
The API in Jean's document is still good for any application that wants
more control over the process and the messages.

The advantages I see in this sort of enhancement :
1. For the average application composer, the NAT traversal feature can be
done more easily this way, without them having to know all of the many
details of RFC 5626. Still some knowledge would be required, but maybe we
can summarize it in the JSR itself to make the implementation process less

2. Providing a generic methods like persistFlow (shown in the doc) can
potentially give the container the flexibility to add support to any future
updates to the RFC under the covers, without the application having to
change its code

3. Providing helper method to remove some of the boilerplate code the app
would be required to write otherwise

4. A standard "right" way (or recommended way) of doing things defined in
the JSR and implemented by the containers consistently, can help the user
to avoid making mistakes (e.g. forgetting a parameter, or placing it
wrongly), and can also promote unity of standard implementation  across
different platforms

I have left out ideas for helper methods provided to assist with some other
parts of the spec, especiallly around flow and registration redundancy (i.e
sections 4.  "User Agent Procedures" outbound-proxy-set helper, and 7.
"Authoritative Proxy Procedures" flow failover helper), but if the group
finds handling this worth considering, we can try working on a suggestion.

(See attached file: SuggestionsForEnhancementOfTheOutboundAPI.pdf)


From:   Jean Deruelle 
< >
To:     jsr359-experts 
< >,
Date:   03/04/2013 04:22 PM
Subject:        Re: SIP Outbound first draft of use cases

I updated the proposal with regard to the prior discussion the EG had over
conf. Updates are the following :
Consistency with setOutboundItnterface for set/getFlow methods
removal of cancelKeepAlive
removal of period parameter in sendKeepalives
Text on retrieval of a flow in a distributed env.
Added the Flow sipFactory.getFlow(String flowToken)

I'm not sure about the usage of Flow in setFlow as it seems to introduce a
little bit more code for the application developer on one hand but on the
other hand offer consistency in terms of API I guess. Did we have a quorum
on using Flow in setFlow() ? If not can other EG members vote up their
preference ?
Keith, I'm not sure what the difference is between an encoder that the
application will have to register with the container or implement an
interface vs the use of annotations which is the trend in JSRs recently and
what we are tending to as well with CDI integration ?
If it was because of using Flow in setFlow, one can still retrieve the Flow
through Flow sipFactory.getFlow(flowToken) and annotations will be called
similar to the encoder.
I kept the annotations so far and would like to see who in the EG has a
preference for one or the other ?


On Thu, Mar 21, 2013 at 10:14 AM, Lewis, Keith 
< >
  I was asked for some example code to illustrate the use of my proposed

  For the standard encoding I am suggesting that setFlow should take a Flow
  object. The following shows the Edge Proxy "CALLING" case. there is one
  new line of code.

  doInvite(SipServletRequest request) {
   Address route = request.getPoppedRoute();
   String flowToken = ((SipURI)route.getURI()).getParameter(“flow”);
   Flow flow = sipFactory.decodeFlowToken(flowToken);
   Proxy proxy = request.getProxy();
   ProxyBranch proxyBranch = proxy.createBranch(<URI to proxy to>)
   proxyBranch.getRequest().setFlow(flow); // container uses that flow for
  all subsequent requests


  If the developer want to use a custom encoding method they would write
  two methods.

  String encodeFlowToken(Flow flow);
  Flow decodeFlowToken(String flowToken);

  The encode method would get the local and remote URI and combine them to
  form the token.

  The decode method would reconstitute the local and remote URI from the
  flow token and then call SipFactory.createFlow(localURI, remoteURI) to
  create the corresponding flow.

  The container would not call these methods and so they would not need to
  be annotated.
  The decode method would be called in place of sipFactory.decodeFlowToken.
  The encode method would be used in place of Flow.getToken().
  For example in the edge proxy doRegister method if "encoder" is an object
  providing the custom encoding we would have :-

  pathURI.setParameter("flow", encoder.encodeFlowToken(flow));


  On Wed, Mar 20, 2013 at 3:51 PM, Lewis, Keith 
< >

   for symmetry I suggest that setFlow should also take a Flow object.

   We could define 2 new methods on SipFactory to create Flow objects

   Flow decodeFlowToken(String flowToken);
   Flow createFlow(SipURI localURI, SipURI remoteURI);

   The first method is for use by an edge proxy that uses the standard flow
   token encoding.

   The second method is for apps that chose to do their own flow token
   When an edge proxy gets a token it would use its own decoding method to
   get a local and remote URI.
   It would then create a flow object that it could use with setFlow.

   We would not need the annotations.


   On Wed, Mar 20, 2013 at 3:31 PM, Jean Deruelle 
< >
     Makes sense indeed it looks cleaner, I made the modifications.
     One question I'm still pondering also is whether to retrieve and set
     the Flow on SIPServletMessage vs SipSession since a Flow can span
     multiple messages it would be similar to setOutboundInterface where
     all messages sent on a particular session would be sent over the same
     flow. This would reduce some boilerplate code for setting the flow
     before sending each message out. On the other hand if on a particular
     session one would like to send a set of messages over a particular
     flow and another set of messages on another flow, this would probably
     not be possible. Thoughts ? (we can go over them in the call today)


     On Wed, Mar 20, 2013 at 6:56 AM, binod pg 
< >
      +1 for the Flow interface.

      - Binod.

      On 3/20/2013 10:39 AM, Jonas Borjesson wrote:
        Hey guys,

        I think I may have mentioned this before but I like the idea of
        actually having a Flow interface. The reason being that you could
        all the methods on the Flow-interface directly and as such maintain
        context. E.g., Flow.sendKeepAlice(long period) would be more
        than SipServletMessage.sendKeepAlive(String flow, long period).
        it was briefly touched upon by Binod and as pointed out by Jean
        is nothing that stops a user from using the
        SipServletMessage.sendKeepAlive to trigger a keep alive on any flow
        the system. However, is it the correct way to access a Flow? Even
        though possible to access any flow through this method, is this
        something we should encourage? What happens if two different
        SipServletMessages call sendKeepAlive on the same flow token? With
        different periods? Who wins? It is after all only a single flow so
        me it doesn't quite make sense that this is allowed. On the other
        hand, one could argue that there is nothing stopping anyone from
        calling Flow.sendKeepAlive-twice either so perhaps a moot point...

        Also, there is still a need for a decodeFlow but instead of
        a SipURI[] where people will always have to remember if the local
        comes first or was it the remote? By returning a Flow interface
        decodeFlow and adding getLocalURI and getRemoteURI I think it will
        clearer to the user what's going on.

        Finally, looking at the FlowListener.flowFailed(FlowEvent), the
        FlowEvent is essentially the Flow-interface so unless there are
        information that could be worth passing along with the event
        the reason to why the flow failed?) then perhaps just returning the
        Flow-interface? If additional information is appropriate in the
        that I would suggest to keep the FlowEvent but have getFlow()
        return a
        Flow instead.


        On Tue, Mar 19, 2013 at 8:16 AM, Jean Deruelle <
          Hi Keith,

          Please see my comments below


          On Tue, Mar 19, 2013 at 3:17 PM, Lewis, Keith <

           This looks good to me.

           On the issue of allowing the developer to choose the encoding
           scheme the
           annotated methods this look useful but I wanted to check whether
           I have
           correctly understood them.

           I suppose that encodeFlow will be used to determine what will be
           by the call of getFlow. This is a flow token encoded from the
           address/port and the local address/port. I suppose that the
           intention is to
           retrieve these from the message passed as a parameter. Should
           the parameter
           be of type SipServletMessage?

           If decodeFlow is doing the reverse operation then I would have
           that it should take a String as a paramater (the flow token). It
           would then
           need to return a remote address/port and a local address/port. I
           that these are represented in the SipURI as discussed in some

          Your understanding is correct. I made the modifications to the
          methods to take a SipServletMessage and String indeed. For the
          return type I modified it to an array of SipURI to take into
          account the
          local and remote.

           An alternative would be to use InetSocketAddress objects to
           represent the
           local/remote address/port as follows

           String encodeFlow(InetSocketAddress localSocket,

           InetSocketAddress[] decodeFlow(String flowToken); // result[0] =
           localSocket, result[1] = remoteSocket

           I don't feel strongly about which solution should be used.

          I don't have a strong feeling neither except that the container
          could just
          replace the requestURI or Route Header with the SipURI directly
          having to compute it from INetSocketAddress and allow the
          application to
          pass parameters to the container if hints are necessary for
          vendor specific
          extensions are needed to support specific encoding/decoding
          mechanisms (but not sure if that would be a real use case). Also
          transport in SipURI might be useful for UA listening on the same
          port for
          different transports (TCP and UDP on port 5060 by example) to
          select the
          correct flow based on the transport ?


           On Thu, Mar 14, 2013 at 5:20 PM, Jean Deruelle <
             Hi all,

             Based on the earlier discussions, I created a document

             outlining the single app case scenarios where a SIP Servlet
             would have to deal with SIP Outbound and how the code could
             look like. This
             is up for discussion and doesn't cater to app composition yet
             which is a
             TODO after discussion on this draft.


           Note: The information contained in this message may be
           privileged and
           and protected from disclosure. If the reader of this message is
           not the
           recipient, or an employee or agent responsible for delivering
           this message
           to the
           intended recipient, you are hereby notified that any
           distribution or
           copying of this communication is strictly prohibited. If you
           have received
           communication in error, please notify us immediately by replying
           to the
           message and
           deleting it from your computer. Thank you. Thrupoint, Inc.

  Note: The information contained in this message may be privileged and
  and protected from disclosure. If the reader of this message is not the
  recipient, or an employee or agent responsible for delivering this
  message to the
  intended recipient, you are hereby notified that any dissemination,
  distribution or
  copying of this communication is strictly prohibited. If you have
  received this
  communication in error, please notify us immediately by replying to the
  message and
  deleting it from your computer. Thank you. Thrupoint, Inc.

Attachment: SuggestionsForEnhancementOfTheOutboundAPI.pdf
Description: Adobe PDF document

Re: SIP Outbound first draft of use cases

Jean Deruelle 04/03/2013

Re: SIP Outbound first draft of use cases

binod pg 04/03/2013

Re: SIP Outbound first draft of use cases

Jean Deruelle 04/10/2013

Re: SIP Outbound first draft of use cases

Nitzan Nissim 04/08/2013
Please Confirm