RoutingTable


1   /**
2    * $RCSfile: RoutingTable.java,v $
3    * $Revision: 1.4 $
4    * $Date: 2005/02/10 20:31:24 $
5    *
6    * Copyright (C) 2004 Jive Software. All rights reserved.
7    *
8    * This software is published under the terms of the GNU Public License (GPL),
9    * a copy of which is included in this distribution.
10   */
11  
12  package org.jivesoftware.messenger;
13  
14  import org.xmpp.packet.JID;
15  
16  import java.util.Iterator  ;
17  
18  /**
19   * <p>Maintains server-wide knowledge of routes to any node.</p>
20   * <p>Routes are only concerned with node addresses. Destinations are
21   * packet handlers (typically of the three following types):</p>
22   * <ul>
23   * <li>Session - A local or remote session belonging to the server's domain.
24   * Remote sessions may be possible in clustered servers.</li>
25   * <li>Chatbot - A chatbot which will have various packets routed to it.</li>
26   * <li>Transport - A transport for foreign server domains. Foreign domains
27   * may be hosted in the same server JVM (e.g. virutal hosted servers, groupchat
28   * servers, etc).</li>
29   * </ul>
30   * <p>In almost all cases, the caller should not be concerned with what
31   * handler is associated with a given node. Simply obtain the packet handler
32   * and deliver the packet to the node, leaving the details up to the handler.</p>
33   * <p/>
34   * <p>Routes are matched using the stringprep rules given in the XMPP specification.
35   * Wildcard routes for a particular name or resource is indicated by a null. E.g.
36   * routing to any address at server.com should set the name to null, the host to
37   * 'server.com' and the resource to null. A route to the best resource for user@server.com
38   * should indicate that route with a null resource component of the XMPPAddress. Session
39   * managers should add a route for both the generic user@server.com as well as
40   * user@server.com/resource routes (knowing that one is an alias for the other
41   * is the responsibility of the session or session manager).</p>
42   * <p/>
43   * <p>In order to accomodate broadcasts, you can also do partial matches by querying
44   * all 'child' nodes of a particular node. The routing table contains a forest of
45   * node trees. The node tree is arranged in the following heirarchy:</p>
46   * <ul>
47   * <li>forest - All nodes in the routing table. An XMPP address with host, name, and resource set
48   * to null will match all nodes stored in the routing table. Use with extreme caution as the
49   * routing table may contain hundreds of thousands of entries and iterators will be produced using
50   * a copy of the table for iteration safety.</li>
51   * <li>domain root - The root of each node tree is the server domain. An XMPP address
52   * containing just a host entry, and null in the name and resource fields will match
53   * the domain root. The children will contain both the root entry (if there is one) and
54   * all entries with the same host name.</li>
55   * <li>user branches - The root's immediate children are the user branches. An
56   * XMPP address containing just a hast and name entry, and null in the resource field
57   * will match a particular user branch. The children will contain both the user branch
58   * (if there is one) and all entries with the same host and name, ignoring resources.
59   * This is the most useful for conducting user broadcasts. Note that if the user
60   * branch is located on a foreign server, the only route returned will the server-to-server
61   * transport.</li>
62   * <li>resource leaves - Each user branch can have zero or more resource leaves. A partial
63   * match on an XMPP address with values in host, name, and resource fields will be equivalent
64   * to the exact match calls since only one route can ever be registered for a particular. See
65   * getBestRoute() if you'd like to search for both the resource leaf route, as well as a valid user
66   * branch for that node if no leaf exists.</li>
67   * </ul>
68   * <p/>
69   * <p>Note: it is important that any component or action affecting routes
70   * update the routing table immediately.</p>
71   *
72   * @author Iain Shigeoka
73   */
74  public interface RoutingTable {
75  
76      /**
77       * <p>Add a route to the routing table.</p>
78       * <p>A single access method allows you to add any of the acceptable
79       * route to the table. It is expected that routes are added and removed
80       * on a relatively rare occassion so routing tables should be optimized
81       * for lookup speed.</p>
82       *
83       * @param node        The route's destination node
84       * @param destination The destination object for this route
85       */
86      void addRoute(JID node, RoutableChannelHandler destination);
87  
88      /**
89       * <p>Obtain a route to a packet handler for the given node.</p>
90       * <p>If a route doesn't exist, the method returns null.</p>
91       *
92       * @param node The address we want a route to
93       * @return The handler corresponding to the route, or null indicating no route exists
94       * @throws NoSuchRouteException If the requested route does not exist
95       */
96      RoutableChannelHandler getRoute(JID node) throws NoSuchRouteException;
97  
98      /**
99       * <p>Obtain all child routes for the given node.</p>
100      * <p>See the class documentation for the matching algorithm of child routes for
101      * any given node. If a route doesn't exist, the method returns an empty iterator (not null).</p>
102      *
103      * @param node The address we want a route to
104      * @return An iterator over all applicable routes
105      */
106     Iterator   getRoutes(JID node);
107 
108     /**
109      * <p>Obtain a route to a handler at the given node falling back to a user branch if no resource leaf exists.</p>
110      * <p>Matching differs slightly from getRoute() which does matching according
111      * to the general matching algorithm described in the class notes. This method
112      * searches using the standard matching rules, and if that does not find a
113      * match and the address name component is not null, or empty, searches again
114      * with the resource set to null (wild card). This is essentially a convenience
115      * for falling back to the best route to a user node when a specific resource
116      * is not available.</p>
117      * <p>For example, consider we're searching for a route to user@server.com/work.
118      * There is no route to that resource but a session is available at
119      * user@server.com/home. The routing table will contain entries for user@server.com
120      * and user@server.com/home. getBestLocalRoute() will first do a search for
121      * user@server.com/work and not find a match. It will then do another search
122      * on user@server.com and find the alias for the session user@server.com/home
123      * (the alias must be maintained by the session manager for the highest priority
124      * resource for any given user). In most cases, the caller doesn't care as long
125      * as they get a legitimate route to the user, so this behavior is 'better' than
126      * the exact matching used in getLocalRoute().</p>
127      * <p>However, it is important to note that sometimes you don't want the best route
128      * to a node. In the previous example, if the packet is an error packet, it is
129      * probably only relevant to the sending session. If a route to that particular
130      * session can't be found, the error should not be sent to another session logged
131      * into the account.</p>
132      * <p/>
133      * <p>If a route doesn't exist, the method returns null.</p>
134      *
135      * @param node The address we want a route to
136      * @return The Session corresponding to the route, or null indicating no route exists
137      * @throws NoSuchRouteException If the requested route does not exist
138      */
139     ChannelHandler getBestRoute(JID node) throws NoSuchRouteException;
140 
141     /**
142      * <p>Remove a route from the routing table.</p>
143      * <p>If a route doesn't exist, the method returns null.</p>
144      *
145      * @param node The address we want a route to
146      * @return The destination object previously registered under the given address, or null if none existed
147      */
148     ChannelHandler removeRoute(JID node);
149 }
150
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags