001: /**
002: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
003: * Unpublished - rights reserved under the Copyright Laws of the United States.
004: * Copyright © 2003 Sun Microsystems, Inc. All rights reserved.
005: * Copyright © 2005 BEA Systems, Inc. All rights reserved.
006: *
007: * Use is subject to license terms.
008: *
009: * This distribution may include materials developed by third parties.
010: *
011: * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
012: *
013: * Module Name : JSIP Specification
014: * File Name : Router.java
015: * Author : Phelim O'Doherty
016: *
017: * HISTORY
018: * Version Date Author Comments
019: * 1.1 19/12/2002 Phelim O'Doherty Initial version
020: * 1.2 16/06/2005 Phelim O'Doherty Deprecated getNextHops and replaced
021: * with getNextHop.
022: * M. Ranganathan Worked out details and clarified behavior.
023: * Sarit Galanos
024: * Jeroen van Bemmel
025: *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
026: */package javax.sip.address;
027:
028: import javax.sip.SipException;
029: import javax.sip.message.Request;
030: import java.util.ListIterator;
031:
032: /**
033: * The Router interface may be implemented by the application to provide custom
034: * routing logic. It is used to determine the next hop for a given request.
035: *
036: * <p>For backwards compatibility reasons, the default behavior of the stack is
037: * to consult the application provided Router implementation for all requests
038: * outside of a dialog. This is controlled through the stack property
039: * <code>javax.sip.USE_ROUTER_FOR_ALL_URIS</code> which defaults to <code>true</code>
040: * when not set.
041: *
042: * <p>This specification recommends to set the stack property
043: * <code>javax.sip.USE_ROUTER_FOR_ALL_URIS</code> to
044: * <code>false</code>. This will cause the stack to only consult the application
045: * provided Router implementation for requests with a non-SIP URI as request URI
046: * (such as tel: or pres:) and without Route headers. This enables an application
047: * to implement DNS lookups and other resolution algorithms
048: *
049: * <p>When <code>javax.sip.USE_ROUTER_FOR_ALL_URIS</code> is set to
050: * <code>false</code>, the next hop is determined according to the following algorithm:
051: * <ul>
052: * <li> If the request contains one or more Route headers, use the URI of the
053: * topmost Route header as next hop, possibly modifying the request in
054: * the process if the topmost Route header contains no lr parameter(See Note below))
055: * <li> Else, if the property <code>javax.sip.OUTBOUND_PROXY</code> is set, use its
056: * value as the next hop
057: * <li> Otherwise, use the request URI as next hop. If the request URI is not a SIP
058: * URI, call {@link javax.sip.address.Router#getNextHop(Request)} provided by the application.
059: * </ul>
060: *
061: * <p><b>Note:</b> In case the topmost Route header contains no 'lr' parameter
062: * (which means the next hop is a strict router), the implementation will perform
063: * 'Route Information Postprocessing' as described in RFC3261 section 16.6 step 6
064: * (also known as "Route header popping"). That is, the following modifications will be
065: * made to the request:
066: * <ol>
067: * <li>The implementation places the Request-URI into the Route header
068: field as the last value.
069: <li>The implementation then places the first Route header field value
070: into the Request-URI and removes that value from the Route
071: header field.
072: * </ol>
073: * Subsequently, the request URI will be used as next hop target.
074: *
075: * <p>The location (classname) of the user-defined Router object is supplied in the
076: * Properties object passed to the
077: * {@link javax.sip.SipFactory#createSipStack(Properties)} method upon creation
078: * of the SIP Stack object.
079: * The Router object must accept a SipStack as an argument to the constructor in
080: * order for the Router to access attributes of the SipStack
081: * The constructor of an object implementing the Router interface must be
082: * <code>RouterImpl(SipStack sipStack, String outboundProxy) {}</code>
083: * <p>
084: * The routing policy can not be changed dynamically, i.e. the SipStack needs to be
085: * deleted and re-created.
086: * Outbound proxy should be passed to the
087: * {@link javax.sip.SipFactory#createSipStack(Properties)} method upon creation
088: * of the SIP Stack object.
089: *
090: * <p><b>Application Notes</b><br/>
091: *
092: * <p>A UAC application which desires to use a particular outbound
093: * proxy should prepend a Route header with the URI of that proxy (and 'lr' flag if
094: * appropriate).
095: * Alternatively, it may achieve the same result by setting the OUTBOUND_PROXY
096: * property (although the Route header approach is more flexible and therefore RECOMMENDED)
097: *
098: * <p>A proxy application may either rewrite the request URI (if the proxy is
099: * responsible for the domain), or prepend a Route header.
100: *
101: *
102: * @author BEA Systems, NIST
103: * @version 1.2
104: */
105:
106: public interface Router {
107:
108: /**
109: * Gets the Outbound Proxy parameter of this Router, this method may return
110: * null if no outbound proxy is defined.
111: *
112: *
113: * @return the Outbound Proxy of this Router.
114: * @see Hop
115: */
116: public Hop getOutboundProxy();
117:
118: /**
119: * Gets the ListIterator of the hops of the default Route.
120: * This method may return null if a default route is not defined.
121: *
122: * @deprecated Since v1.2. This method is replaced with
123: * {@link Router#getNextHop(Request)} method which returns the next
124: * Hop for this request.
125: *
126: */
127: public ListIterator getNextHops(Request request);
128:
129: /**
130: * Gets the next Hop from this Router for the specified request, this
131: * method may return <code>null</code> if a default route is not defined.
132: *
133: * @return the next Hop from this Router for the Request.
134: * @see Hop
135: * @since v1.2
136: *
137: * @throws SipException when there is something wrong with the request
138: */
139: public Hop getNextHop(Request request) throws SipException;
140:
141: }
|