sip.address.Router Maven / Gradle / Ivy

/**
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 * Unpublished - rights reserved under the Copyright Laws of the United States.
 * Copyright ? 2003 Sun Microsystems, Inc. All rights reserved.
 * Copyright ? 2005 BEA Systems, Inc. All rights reserved.
 *
 * Use is subject to license terms.
 *
 * This distribution may include materials developed by third parties.
 *
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *
 * Module Name   : JSIP Specification
 * File Name     : Router.java
 * Author        : Phelim O'Doherty
 *
 *  HISTORY
 *  Version   Date      Author              Comments
 *  1.1     19/12/2002  Phelim O'Doherty    Initial version
 *  1.2     16/06/2005  Phelim O'Doherty    Deprecated getNextHops and replaced
 *                                          with getNextHop.
 *              M. Ranganathan      Worked out details and clarified behavior.
 *              Sarit Galanos
 *              Jeroen van Bemmel
 *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 */
package javax.sip.address;

import javax.sip.SipException;
import javax.sip.message.Request;
import java.util.ListIterator;

/**
 * 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:
 * 

 *  If the request contains one or more Route headers, use the URI of the
 *      topmost Route header as next hop, possibly modifying the request in
 *      the process if the topmost Route header contains no lr parameter(See Note below))
 * 
 Else, if the property javax.sip.OUTBOUND_PROXY is set, use its
 *      value as the next hop
 * 
 Otherwise, use the request URI as next hop. If the request URI is not a SIP
 *      URI, call {@link javax.sip.address.Router#getNextHop(Request)} provided by the application.
 * 
 *
 * 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:
 * 

 * The implementation places the Request-URI into the Route header
            field as the last value.
   
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
 * {@link javax.sip.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
 * {@link javax.sip.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
 * @version 1.2
 */

public interface Router {


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


    /**
     * Gets the ListIterator of the hops of the default Route.
     * This method may return null if a default route is not defined.
     *
     * @deprecated Since v1.2. This method is replaced with
     * {@link Router#getNextHop(Request)} method which returns the next
     * Hop for this request.
     *
     */
    public ListIterator getNextHops(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.
     *
     * @return the next Hop from this Router for the Request.
     * @see Hop
     * @since v1.2
     *
     * @throws SipException when there is something wrong with the request
     */
    public Hop getNextHop(Request request) throws SipException;



}