org.mobicents.javax.servlet.sip
Interface ProxyExt

public interface ProxyExt

Interface Extension that adds extra features to the JSR 289 Proxy interface.
It adds the following capabilities :

• Allows for applications to set a timeout on 1xx responses as JSR 289 defines a timeout only for final responses.
• Allows for applications to set the outbound interface based on SipURI, to allow routing based on transport protocol as well.
• Allows for applications to terminate an established session by sending BYE requests in both directions as specified in 3GPP TS 24.229 section 5.2.8.1.2. It is not RFC3261 complient behaviour as SIP proxies SHOULD NOT originate SIP requests, and should therefore be used with caution.

Here is some sample code to show how it can be used :

        import java.io.IOException;
        import java.util.ArrayList;
        import javax.servlet.ServletException;
        import javax.servlet.sip.Proxy;
        import javax.servlet.sip.ProxyBranch;
        import javax.servlet.sip.SipFactory;
        import javax.servlet.sip.SipServlet;
        import javax.servlet.sip.SipServletRequest;
        import javax.servlet.sip.URI;
        
        import org.mobicents.javax.servlet.sip.ProxyBranchListener;
        import org.mobicents.javax.servlet.sip.ProxyExt;
        import org.mobicents.javax.servlet.sip.ResponseType;
 
        public class ProxySipServlet extends SipServlet implements ProxyBranchListener {
  
        protected void doInvite(SipServletRequest request) throws ServletException,
                        IOException {
 
                if(!request.isInitial()){
                        return;
                }
                        
                SipFactory sipFactory = (SipFactory) getServletContext().getAttribute(SIP_FACTORY);
                Proxy proxy = request.getProxy();
                proxy.setParallel(false);
                // set the timeout for receiving a final response
                proxy.setProxyTimeout(5);
                // set the timeout for receiving a 1xx response
                ((ProxyExt)proxy).setProxy1xxTimeout(1);                                
                proxy.setRecordRoute(true);
                ArrayList uris = new ArrayList();
                URI uri1 = sipFactory.createAddress("sip:receiver@127.0.0.1:5057").getURI();            
                URI uri2 = sipFactory.createAddress("sip:second-receiver@127.0.0.1:5056").getURI();
                uris.add(uri2);
                uris.add(uri1);
  
                proxy.proxyTo(uris);            
  }
        
        /**
         * Called if no 1xx and no final response has been received with a response type of INFORMATIONAL
         * Called if no 2xx response has been received with a response type of FINAL
         *\/
        public void onProxyBranchResponseTimeout(ResponseType responseType,
                        ProxyBranch proxyBranch) {
                logger.info("onProxyBranchResponseTimeout callback was called. responseType = " + responseType + " , branch = " + proxyBranch + ", request " + proxyBranch.getRequest() + ", response " + proxyBranch.getResponse());
        }
 

Since:

1.3

Author:

jean.deruelle@gmail.com

Method Summary

int	getProxy1xxTimeout() The current value of the overall proxy 1xx timeout value.
void	setOutboundInterface(SipURI outboundInterface) In multi-homed environment this method can be used to select the outbound interface and port number and transport to use for proxy branches.
void	setProxy1xxTimeout(int timeout) This is the amount of time, in seconds, the container waits for an informational response when proxying.
void	storeTerminationInformation(boolean store) Enable (or disable) the storing of routing information required to terminate a proxy using terminateSession.
void	terminateSession(SipSession session, int calleeResponseCode, String calleeResponseText, int callerResponseCode, String callerResponseText) Terminates an established session by sending BYE requests in both directions.

Method Detail

setProxy1xxTimeout

void setProxy1xxTimeout(int timeout)

This is the amount of time, in seconds, the container waits for an informational response when proxying.

• If the proxy is sequential, when the timer expires and no 1xx response nor final response has been received, the container CANCELs the current branch and proxies to the next element in the target set.
• If the proxy is parallel, then this acts as the upper limit for the entire proxy operation resulting in equivalent of invoking cancel() if the the proxy did not complete during this time, which means that neither an informational response nor a final response was not sent upstream.

Parameters:

timeout - new search 1xx timeout in seconds

Throws:

IllegalArgumentException - if the container cannot set the value as requested because it is too high, too low or negative

Since:

1.3

getProxy1xxTimeout

int getProxy1xxTimeout()

The current value of the overall proxy 1xx timeout value. This is measured in seconds.

Returns:

current value of proxy timeout in seconds.

Since:

1.3

setOutboundInterface

void setOutboundInterface(SipURI outboundInterface)

In multi-homed environment this method can be used to select the outbound interface and port number and transport to use for proxy branches. The specified address must be the address of one of the configured outbound interfaces. The set of SipURI objects which represent the supported outbound interfaces can be obtained from the servlet context attribute named javax.servlet.sip.outboundInterfaces. The port is interpreted as an advice by the app to the container. If the port of the socket address has a non-zero value, the container will make a best-effort attempt to use it as the source port number for UDP packets, or as a source port number for TCP connections it originates. If the port is not available, the container will use its default port allocation scheme. Invocation of this method also impacts the system headers generated by the container for this Proxy, such as the Record-Route header (getRecordRouteURI()), the Via and the Contact header. The IP address, port and transport parts of the SipURI are used to construct these system headers.

Parameters:

outboundInterface - the sip uri representing the outbound interface to use when forwarding requests with this proxy

Throws:

NullPointerException - on null sip uri

IllegalArgumentException - if the sip uri is not understood by the container as one of its outbound interface

Since:

1.4

storeTerminationInformation

void storeTerminationInformation(boolean store)
                                 throws IllegalStateException

Enable (or disable) the storing of routing information required to terminate a proxy using terminateSession. This must be called before a success final response has arrived.

Parameters:

store - true to store information for termination, false to return to default behaviour

Throws:

IllegalStateException - if the proxy session has been established

Since:

1.6

terminateSession

void terminateSession(SipSession session,
                      int calleeResponseCode,
                      String calleeResponseText,
                      int callerResponseCode,
                      String callerResponseText)
                      throws IllegalStateException,
                             IOException

Terminates an established session by sending BYE requests in both directions. This is required to implement 3GPP TS 24.229 section 5.2.8.1.2. It is not RFC3261 complient behaviour as SIP proxies SHOULD NOT originate SIP requests, and should therefore be used with caution. To enable this behaviour storeTerminationInformation(true) must be called before a success final response is received.

Parameters:

session - The SipSession to terminate

calleeResponseCode - SIP response code to include in a Reason header in BYE sent to original call recipient. Must be in the range 300-699.

calleeResponseText - SIP response text to include in BYE sent to original call recipient. If null, no reason header will be used.

callerResponseCode - SIP response code to include in a Reason header in BYE sent to original caller. Must be in the range 300-699.

callerResponseText - SIP response text to include in BYE sent to original caller. If null, no reason header will be used.

Throws:

IllegalStateException - if the proxy session is not yet established or storeTerminationInformation not called before session was established.

IOException - if a transport error occurs when trying to send this request

Since:

1.6