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.

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.

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:

java.lang.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:

java.lang.NullPointerException - on null sip uri

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

Since:

1.4