Interface RoutingTable
-
- All Known Implementing Classes:
RoutingTableImpl
public interface RoutingTable
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. virtual 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 accommodate 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 hierarchy:
- 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
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description boolean
addClientRoute(org.xmpp.packet.JID route, LocalClientSession destination)
Adds a route to the routing table for the specified client session.void
addComponentRoute(org.xmpp.packet.JID route, RoutableChannelHandler destination)
Adds a route to the routing table for the specified internal or external component.void
addServerRoute(DomainPair route, LocalOutgoingServerSession destination)
Adds a route to the routing table for the specified outgoing server session, or replaces a pre-existing one.void
broadcastPacket(org.xmpp.packet.Message packet, boolean onlyLocal)
Broadcasts the specified message to connected client sessions to the local node or across the cluster.ClientSession
getClientRoute(org.xmpp.packet.JID jid)
Returns the client session associated to the specified XMPP address ornull
if none was found.Collection<ClientSession>
getClientsRoutes(boolean onlyLocal)
Returns collection of client sessions authenticated with the server.Collection<String>
getComponentsDomains()
Returns domains of components hosted by the server.RemotePacketRouter
getRemotePacketRouter()
Returns theRemotePacketRouter
to use for delivering packets to entities hosted in remote nodes of the cluster ornull
if none was set.List<org.xmpp.packet.JID>
getRoutes(org.xmpp.packet.JID route, org.xmpp.packet.JID requester)
Returns the list of routes associated to the specified route address.Collection<String>
getServerHostnames()
Returns a collection with the hostnames of the remote servers that currently may receive packets sent from this server.OutgoingServerSession
getServerRoute(DomainPair pair)
Returns the outgoing server session associated to the specified XMPP address ornull
if none was found.Collection<DomainPair>
getServerRoutes()
int
getServerSessionsCount()
Returns the number of outgoing server sessions hosted in this JVM.boolean
hasClientRoute(org.xmpp.packet.JID jid)
Returns true if a registered user or anonymous user with the specified full JID is currently logged.boolean
hasComponentRoute(org.xmpp.packet.JID jid)
Returns true if an internal or external component is hosting the specified address.boolean
hasServerRoute(DomainPair pair)
Returns true if an outgoing server session exists to the specified remote server.boolean
isAnonymousRoute(org.xmpp.packet.JID jid)
Returns true if an anonymous user with the specified full JID is currently logged.boolean
isLocalRoute(org.xmpp.packet.JID jid)
Returns true if the specified address belongs to a route that is hosted by this JVM.boolean
removeClientRoute(org.xmpp.packet.JID route)
Returns true if a route of a client session has been successfully removed.boolean
removeComponentRoute(org.xmpp.packet.JID route)
Returns true if a route of a component has been successfully removed.boolean
removeServerRoute(DomainPair route)
Returns true if a route to an outgoing server has been successfully removed.void
routePacket(org.xmpp.packet.JID jid, org.xmpp.packet.Packet packet)
Routes a packet to the specified address.default void
routePacket(org.xmpp.packet.JID jid, org.xmpp.packet.Packet packet, boolean fromServer)
Deprecated.Replaced byroutePacket(JID, Packet)
void
setRemotePacketRouter(RemotePacketRouter remotePacketRouter)
Sets theRemotePacketRouter
to use for delivering packets to entities hosted in remote nodes of the cluster.
-
-
-
Method Detail
-
addServerRoute
void addServerRoute(DomainPair route, LocalOutgoingServerSession destination)
Adds a route to the routing table for the specified outgoing server session, or replaces a pre-existing one. When running inside a cluster, this method must be invoked on the cluster node that is actually holding the physical connection to the remote server. Additionally, replacing a pre-existing server session can only occur on the same cluster node as the one that was holding the original session. A runtime exception is thrown when another cluster node attempts to replace the session.- Parameters:
route
- the address associated to the route.destination
- the outgoing server session.
-
addComponentRoute
void addComponentRoute(org.xmpp.packet.JID route, RoutableChannelHandler destination)
Adds a route to the routing table for the specified internal or external component.When running inside of a cluster this message
must
be sent from the cluster node that is actually hosting the component. The component may be available in all or some of cluster nodes. The routing table will keep track of all nodes hosting the component.- Parameters:
route
- the address associated to the route.destination
- the component.
-
addClientRoute
boolean addClientRoute(org.xmpp.packet.JID route, LocalClientSession destination)
Adds a route to the routing table for the specified client session. The client session will be added as soon as the user has finished authenticating with the server. Moreover, when the user becomes available or unavailable then the routing table will get updated again. When running inside of a cluster this messagemust
be sent from the cluster node that is actually holding the client session.- Parameters:
route
- the address associated to the route.destination
- the client session.- Returns:
- true if route was added to the table or false if already present.
-
routePacket
void routePacket(org.xmpp.packet.JID jid, org.xmpp.packet.Packet packet) throws PacketException
Routes a packet to the specified address. The packet destination can be a user on the local server, a component, or a foreign server.When routing a packet to a remote server then a new outgoing connection will be created to the remote server if none was found and the packet will be delivered. If an existing outgoing connection already exists then it will be used for delivering the packet. Moreover, when running inside of a cluster the node that has the actual outgoing connection will be requested to deliver the requested packet.
Packets routed to components will only be sent if the internal or external component is connected to the server. Moreover, when running inside of a cluster the node that is hosting the component will be requested to deliver the requested packet. It will be first checked if the component is available in this JVM and if not then the first cluster node found hosting the component will be used.
Packets routed to users will be delivered if the user is connected to the server. Depending on the packet type and the sender of the packet only available or all user sessions could be considered. For instance,
Messages
andPresences
are only sent to available client sessions whilstIQs
originated to the server can be sent to available or unavailable sessions. When running inside of a cluster the node that is hosting the user session will be requested to deliver the requested packet.- Parameters:
jid
- the recipient of the packet to route.packet
- the packet to route.- Throws:
PacketException
- thrown if the packet is malformed (results in the sender's session being shutdown).
-
routePacket
@Deprecated default void routePacket(org.xmpp.packet.JID jid, org.xmpp.packet.Packet packet, boolean fromServer) throws PacketException
Deprecated.Replaced byroutePacket(JID, Packet)
- Throws:
PacketException
-
hasClientRoute
boolean hasClientRoute(org.xmpp.packet.JID jid)
Returns true if a registered user or anonymous user with the specified full JID is currently logged. When running inside of a cluster a true value will be returned as long as the user is connected to any cluster node. // TODO Should we care about available or not available????- Parameters:
jid
- the full JID of the user.- Returns:
- true if a registered user or anonymous user with the specified full JID is currently logged.
-
isAnonymousRoute
boolean isAnonymousRoute(org.xmpp.packet.JID jid)
Returns true if an anonymous user with the specified full JID is currently logged. When running inside of a cluster a true value will be returned as long as the user is connected to any cluster node.- Parameters:
jid
- the full JID of the anonymous user.- Returns:
- true if an anonymous user with the specified full JID is currently logged.
-
isLocalRoute
boolean isLocalRoute(org.xmpp.packet.JID jid)
Returns true if the specified address belongs to a route that is hosted by this JVM. When running inside of a cluster each cluster node will host routes to local resources. A false value could either mean that the route is not hosted by this JVM but other cluster node or that there is no route to the specified address. UseXMPPServer.isLocal(org.xmpp.packet.JID)
to figure out if the address belongs to tge domain hosted by this server.- Parameters:
jid
- the address of the route.- Returns:
- true if the specified address belongs to a route that is hosted by this JVM.
-
hasServerRoute
boolean hasServerRoute(DomainPair pair)
Returns true if an outgoing server session exists to the specified remote server. The JID can be a full JID or a bare JID since only the domain of the specified address will be used to look up the route.When running inside of a cluster the look up will be done in all the cluster. So as long as a node has a connection to the remote server a true value will be returned.
- Parameters:
pair
- DomainPair that specifies the local/remote server address.- Returns:
- true if an outgoing server session exists to the specified remote server.
-
hasComponentRoute
boolean hasComponentRoute(org.xmpp.packet.JID jid)
Returns true if an internal or external component is hosting the specified address. The JID can be a full JID or a bare JID since only the domain of the specified address will be used to look up the route.When running inside of a cluster the look up will be done in all the cluster. So as long as a node is hosting the component a true value will be returned.
- Parameters:
jid
- JID that specifies the component address.- Returns:
- true if an internal or external component is hosting the specified address.
-
getClientRoute
ClientSession getClientRoute(org.xmpp.packet.JID jid)
Returns the client session associated to the specified XMPP address ornull
if none was found. When running inside of a cluster and a remote node is hosting the client session then a session surrage will be returned.- Parameters:
jid
- the address of the session.- Returns:
- the client session associated to the specified XMPP address or null if none was found.
-
getClientsRoutes
Collection<ClientSession> getClientsRoutes(boolean onlyLocal)
Returns collection of client sessions authenticated with the server. When running inside of a cluster the returned sessions will include sessions connected to this JVM and also other cluster nodes. TODO Prevent usage of this message and change original requirement to avoid having to load all sessions. TODO This may not scale when hosting millions of sessions.- Parameters:
onlyLocal
- true if only client sessions connected to this JVM must be considered.- Returns:
- collection of client sessions authenticated with the server.
-
getServerRoute
OutgoingServerSession getServerRoute(DomainPair pair)
Returns the outgoing server session associated to the specified XMPP address ornull
if none was found. When running inside of a cluster and a remote node is hosting the session then a session surrage will be returned.- Parameters:
pair
- DomainPair that specifies the local/remote server address.- Returns:
- the outgoing server session associated to the specified XMPP address or null if none was found.
-
getServerHostnames
Collection<String> getServerHostnames()
Returns a collection with the hostnames of the remote servers that currently may receive packets sent from this server.- Returns:
- a collection with the hostnames of the remote servers that currently may receive packets sent from this server.
-
getServerRoutes
Collection<DomainPair> getServerRoutes()
-
getServerSessionsCount
int getServerSessionsCount()
Returns the number of outgoing server sessions hosted in this JVM. When running inside of a cluster you will need to get this value for each cluster node to learn the total number of outgoing server sessions.- Returns:
- the number of outgoing server sessions hosted in this JVM.
-
getComponentsDomains
Collection<String> getComponentsDomains()
Returns domains of components hosted by the server. When running in a cluster, domains of components running in any node will be returned.- Returns:
- domains of components hosted by the server.
-
getRoutes
List<org.xmpp.packet.JID> getRoutes(org.xmpp.packet.JID route, org.xmpp.packet.JID requester)
Returns the list of routes associated to the specified route address. When asking for routes to a remote server then the requested JID will be included as the only value of the returned collection. It is indifferent if an outgoing session to the specified remote server exists or not.When asking for routes to client sessions the specified route address could either be a full JID of a bare JID. In the case of a full JID, a single element will be included in the answer in case the specified full JID exists or an empty collection if the full JID does not exist. Moreover, when passing a bare JID a list of full JIDs will be returned for each available resource associated to the bare JID. In any case, only JIDs of
available
client sessions are returned. However, there is an exception with directed presences. Unavailable routes may be returned if and only if the owner of the route sent a directed presence to the requester thus becoming available to the requester. If requester isnull
then only available resources are considered.When asking for routes to components a single element will be returned in the answer only if an internal or external component is found for the specified route address. If no component was found then an empty collection will be returned.
- Parameters:
route
- The address we want a route to.requester
- The address of the entity requesting the routes or null if we don't care about directed presences.- Returns:
- list of routes associated to the specified route address.
-
removeClientRoute
boolean removeClientRoute(org.xmpp.packet.JID route)
Returns true if a route of a client session has been successfully removed. When running inside of a cluster this messagemust
be sent from the cluster node that is actually hosting the client session.- Parameters:
route
- the route to remove.- Returns:
- true if a route of a client session has been successfully removed.
-
removeServerRoute
boolean removeServerRoute(DomainPair route)
Returns true if a route to an outgoing server has been successfully removed. When running inside of a cluster this messagemust
be sent from the cluster node that is actually holding the physical connection to the remote server.- Parameters:
route
- the route to remove.- Returns:
- true if the route was successfully removed.
-
removeComponentRoute
boolean removeComponentRoute(org.xmpp.packet.JID route)
Returns true if a route of a component has been successfully removed. Both internal and external components have a route in the table. When running inside of a cluster this messagemust
be sent from the cluster node that is actually hosting the component.- Parameters:
route
- the route to remove.- Returns:
- true if a route of a component has been successfully removed.
-
setRemotePacketRouter
void setRemotePacketRouter(RemotePacketRouter remotePacketRouter)
Sets theRemotePacketRouter
to use for delivering packets to entities hosted in remote nodes of the cluster.- Parameters:
remotePacketRouter
- the RemotePacketRouter to use for delivering packets to entities hosted in remote nodes of the cluster.
-
getRemotePacketRouter
RemotePacketRouter getRemotePacketRouter()
Returns theRemotePacketRouter
to use for delivering packets to entities hosted in remote nodes of the cluster ornull
if none was set.- Returns:
- the RemotePacketRouter to use for delivering packets to entities hosted in remote nodes of the cluster.
-
broadcastPacket
void broadcastPacket(org.xmpp.packet.Message packet, boolean onlyLocal)
Broadcasts the specified message to connected client sessions to the local node or across the cluster. Both available and unavailable client sessions will receive the message.- Parameters:
packet
- the message to broadcast.onlyLocal
- true if only client sessions connect to the local JVM will get the message.
-
-