JSIP API v1.2
November 2006

javax.sip.address
Interface Router


public interface Router

The Router interface may be implemented by the application to provide custom routing logic. It is used to determine the next hop for a given request.

For backwards compatibility reasons, the default behavior of the stack is to consult the application provided Router implementation for all requests outside of a dialog. This is controlled through the stack property javax.sip.USE_ROUTER_FOR_ALL_URIS which defaults to true when not set.

This specification recommends to set the stack property javax.sip.USE_ROUTER_FOR_ALL_URIS to false. This will cause the stack to only consult the application provided Router implementation for requests with a non-SIP URI as request URI (such as tel: or pres:) and without Route headers. This enables an application to implement DNS lookups and other resolution algorithms

When javax.sip.USE_ROUTER_FOR_ALL_URIS is set to false, the next hop is determined according to the following algorithm:

Note: In case the topmost Route header contains no 'lr' parameter (which means the next hop is a strict router), the implementation will perform 'Route Information Postprocessing' as described in RFC3261 section 16.6 step 6 (also known as "Route header popping"). That is, the following modifications will be made to the request:

  1. The implementation places the Request-URI into the Route header field as the last value.
  2. The implementation then places the first Route header field value into the Request-URI and removes that value from the Route header field.
Subsequently, the request URI will be used as next hop target.

The location (classname) of the user-defined Router object is supplied in the Properties object passed to the SipFactory.createSipStack(Properties) method upon creation of the SIP Stack object. The Router object must accept a SipStack as an argument to the constructor in order for the Router to access attributes of the SipStack The constructor of an object implementing the Router interface must be RouterImpl(SipStack sipStack, String outboundProxy) {}

The routing policy can not be changed dynamically, i.e. the SipStack needs to be deleted and re-created. Outbound proxy should be passed to the SipFactory.createSipStack(Properties) method upon creation of the SIP Stack object.

Application Notes

A UAC application which desires to use a particular outbound proxy should prepend a Route header with the URI of that proxy (and 'lr' flag if appropriate). Alternatively, it may achieve the same result by setting the OUTBOUND_PROXY property (although the Route header approach is more flexible and therefore RECOMMENDED)

A proxy application may either rewrite the request URI (if the proxy is responsible for the domain), or prepend a Route header.

Author:
BEA Systems, NIST

Method Summary
 Hop getNextHop(Request request)
          Gets the next Hop from this Router for the specified request, this method may return null if a default route is not defined.
 java.util.ListIterator getNextHops(Request request)
          Deprecated. Since v1.2. This method is replaced with getNextHop(Request) method which returns the next Hop for this request.
 Hop getOutboundProxy()
          Gets the Outbound Proxy parameter of this Router, this method may return null if no outbound proxy is defined.
 

Method Detail

getOutboundProxy

Hop getOutboundProxy()
Gets the Outbound Proxy parameter of this Router, this method may return null if no outbound proxy is defined.

Returns:
the Outbound Proxy of this Router.
See Also:
Hop

getNextHops

java.util.ListIterator getNextHops(Request request)
Deprecated. Since v1.2. This method is replaced with getNextHop(Request) method which returns the next Hop for this request.

Gets the ListIterator of the hops of the default Route. This method may return null if a default route is not defined.


getNextHop

Hop getNextHop(Request request)
               throws SipException
Gets the next Hop from this Router for the specified request, this method may return null if a default route is not defined.

Returns:
the next Hop from this Router for the Request.
Throws:
SipException - when there is something wrong with the request
Since:
v1.2
See Also:
Hop

JSIP API v1.2
November 2006

If you have any comments, please mail them to JAIN-SIP-INTEREST@java.sun.com after subscribing at http://archives.java.sun.com
Copyright - 2006 BEA Systems and Sun Microsystems