Maintains server-wide knowledge of routes to any node.
Routes are only concerned with node addresses. Destinations are packet handlers (typically of the three following types):
- Session - A local or remote session belonging to the server's domain. Remote sessions may be possible in clustered servers.
- Chatbot - A chatbot which will have various packets routed to it.
- Transport - A transport for foreign server domains. Foreign domains may be hosted in the same server JVM (e.g. virutal hosted servers, groupchat servers, etc).
In almost all cases, the caller should not be concerned with what handler is associated with a given node. Simply obtain the packet handler and deliver the packet to the node, leaving the details up to the handler.
Routes are matched using the stringprep rules given in the XMPP specification. Wildcard routes for a particular name or resource is indicated by a null. E.g. routing to any address at server.com should set the name to null, the host to 'server.com' and the resource to null. A route to the best resource for user@server.com should indicate that route with a null resource component of the XMPPAddress. Session managers should add a route for both the generic user@server.com as well as user@server.com/resource routes (knowing that one is an alias for the other is the responsibility of the session or session manager).
In order to accomodate broadcasts, you can also do partial matches by querying all 'child' nodes of a particular node. The routing table contains a forest of node trees. The node tree is arranged in the following heirarchy:
- forest - All nodes in the routing table. An XMPP address with host, name, and resource set to null will match all nodes stored in the routing table. Use with extreme caution as the routing table may contain hundreds of thousands of entries and iterators will be produced using a copy of the table for iteration safety.
- domain root - The root of each node tree is the server domain. An XMPP address containing just a host entry, and null in the name and resource fields will match the domain root. The children will contain both the root entry (if there is one) and all entries with the same host name.
- user branches - The root's immediate children are the user branches. An XMPP address containing just a hast and name entry, and null in the resource field will match a particular user branch. The children will contain both the user branch (if there is one) and all entries with the same host and name, ignoring resources. This is the most useful for conducting user broadcasts. Note that if the user branch is located on a foreign server, the only route returned will the server-to-server transport.
- resource leaves - Each user branch can have zero or more resource leaves. A partial match on an XMPP address with values in host, name, and resource fields will be equivalent to the exact match calls since only one route can ever be registered for a particular. See getBestRoute() if you'd like to search for both the resource leaf route, as well as a valid user branch for that node if no leaf exists.
Note: it is important that any component or action affecting routes update the routing table immediately.
@author Iain Shigeoka