JXTA

net.jxta.impl.endpoint.router
Class EndpointRouter

java.lang.Object
  extended by net.jxta.impl.endpoint.router.EndpointRouter
All Implemented Interfaces:
EventListener, EndpointListener, MessageReceiver, MessageSender, MessageTransport, MessengerEventListener, Module

public class EndpointRouter
extends Object
implements EndpointListener, MessageReceiver, MessageSender, MessengerEventListener, Module


Nested Class Summary
(package private)  class EndpointRouter.ClearPendingQuery
           
 
Field Summary
static long ASYNC_MESSENGER_WAIT
          how long we are willing to wait for a response from an async getMessenger.
static Integer GET_ROUTE_CONTROL
          MessageTransport Control operation
static int RouteControlOp
           
 
Fields inherited from interface net.jxta.platform.Module
START_AGAIN_PROGRESS, START_AGAIN_STALLED, START_DISABLED, START_OK
 
Constructor Summary
EndpointRouter()
          Default constructor
 
Method Summary
(package private) static PeerID addr2pid(EndpointAddress addr)
          Convert a Router EndpointAddress into a PeerID
(package private)  EndpointAddress addressMessage(Message message, EndpointAddress dstAddress)
          Updates the router element of a message and returns the peerAddress address of the next hop (where to send the message).
 boolean allowsRouting()
          Returns true if the Message Transport can be used by the EndpointRouter.
(package private)  Messenger ensureLocalRoute(EndpointAddress peerAddress, RouteAdvertisement hint)
          Get a Messenger for the specified destination if a direct route is known.
(package private)  Messenger findBestReachableEndpoint(EndpointAddress dest, List<EndpointAddress> mightWork, boolean exist)
          Given a list of addresses, find the best reachable endpoint.
(package private)  Messenger findReachableEndpoint(EndpointAddress destPeerAddress, boolean exist, RouteAdvertisement hint)
          Read the route advertisement for a peer and find a suitable transport endpoint for sending to that peer either directly or via one of the advertised peer router
(package private)  Iterator<EndpointAddress> getAllCachedMessengerDestinations()
          Get all direct route destinations
(package private)  Iterator<ID> getAllRoutedRouteAddresses()
          Get all long route destination addresses
(package private)  BadRoute getBadRoute(EndpointAddress addr)
          get bad route entry
(package private)  Messenger getCachedMessenger(EndpointAddress addr)
          Snoop if we have a messenger
 EndpointService getEndpointService()
          Returns the endpoint service with which this MessageTransport is registered.
(package private)  EndpointAddress getGatewayAddress(EndpointAddress peerAddress, boolean seekRoute, RouteAdvertisement hint)
          Given a peer id, return an address to reach that peer.
 Messenger getMessenger(EndpointAddress addr, Object hint)
          Return a Messenger for sending messages to the specified destination EndpointAddress.
(package private)  RouteAdvertisement getMyLocalRoute()
           
(package private)  Collection<Map.Entry<PeerID,EndpointRouter.ClearPendingQuery>> getPendingQueriesAllDestinations()
          Get all pendingRouteQuery destinations
(package private)  EndpointRouter.ClearPendingQuery getPendingRouteQuery(PeerID peerID)
          get a pending route query info
 String getProtocolName()
          Returns a String containing the name of the protocol used by this MessageTransport.
 EndpointAddress getPublicAddress()
          Returns the EndpointAddress which will be used as the source address for all messages sent by this message sender.
 Iterator<EndpointAddress> getPublicAddresses()
          Returns an Iterator of all of the EndpointAddresses by which this MessageReceiver is reachable.
(package private)  RouteAdvertisement getRoute(EndpointAddress peerAddress, boolean seekRoute)
          Get the routed route, if any, for a given peer id.
(package private)  RouteCM getRouteCM()
          Get the route CM cache Manager
(package private)  Iterator<Map.Entry<ID,RouteAdvertisement>> getRoutedRouteAllDestinations()
          Get all long route destinations
(package private)  RouteResolver getRouteResolver()
          Get the route resolver manager
 void init(PeerGroup group, ID assignedID, Advertisement impl)
          Initialize the module, passing it its peer group and advertisement.
 boolean isConnectionOriented()
          Returns true if the Message Transport is connection oriented (like TCP/IP).
(package private)  boolean isLocalRoute(EndpointAddress peerAddress)
          isLocalRoute is a shallow test.
(package private)  boolean isPendingRouteQuery(PeerID peerID)
          is there a pending route query for that destination
(package private)  boolean isRoutedRoute(PeerID peerID)
          Do we have a long route for that destination
 boolean messengerReady(MessengerEvent event)
          Receives notifications of new messengers being generated by the underlying network transports.
(package private)  boolean newMessenger(MessengerEvent event)
          Call when an asynchronous new messenger is ready.
(package private)  void noMessenger(EndpointAddress logDest)
          Call when an asynchronous new messenger could not be obtained.
(package private) static EndpointAddress pid2addr(ID pid)
          Convert an ID into a Router Endpoint Address
 boolean ping(EndpointAddress addr)
          Deprecated. 
 void processIncomingMessage(Message msg, EndpointAddress srcAddr, EndpointAddress dstAddr)
          This method is invoked by the EndpointService for each incoming message which is addressed to this listener.
(package private)  void removeRoute(PeerID peerID)
          This method is used to remove a route
(package private)  void sendOnLocalRoute(EndpointAddress destination, Message message)
          Send a message to a given logical destination if it maps to some messenger in our messenger pool or if such a mapping can be found and added.
(package private)  void setBadRoute(EndpointAddress addr, BadRoute badRoute)
          set bad route entry
(package private)  boolean setRoute(RouteAdvertisement route, boolean force)
          set new route info
 int startApp(String[] arg)
          Complete any remaining initialization of the module.
 void stopApp()
          Stop a module.
 Object transportControl(Object operation, Object value)
          Pass a transport control object to a message transport.
(package private)  void updateRouteAdv(RouteAdvertisement route)
          check if it is a new route adv
(package private)  void updateRouteAdv(RouteAdvertisement route, boolean force)
          check if it is a new route adv
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ASYNC_MESSENGER_WAIT

public static final long ASYNC_MESSENGER_WAIT
how long we are willing to wait for a response from an async getMessenger. We do not wait long at all because it is non-critical that we get the answer synchronously. The goal is to avoid starting a route discovery if there's a chance to get a direct connection. However, we will still take advantage of the direct route if it is found while we wait for the route discovery result. If that happens, the only wrong is that we used some bandwidth doing a route discovery that wasn't needed after all.

See Also:
Constant Field Values

GET_ROUTE_CONTROL

public static final Integer GET_ROUTE_CONTROL
MessageTransport Control operation


RouteControlOp

public static final int RouteControlOp
See Also:
Constant Field Values
Constructor Detail

EndpointRouter

public EndpointRouter()
Default constructor

Method Detail

getMyLocalRoute

RouteAdvertisement getMyLocalRoute()

isLocalRoute

boolean isLocalRoute(EndpointAddress peerAddress)
isLocalRoute is a shallow test. It tells you that there used to be a local route that worked the last time it was tried.

Parameters:
peerAddress - Address of the destination who's route is desired.
Returns:
true if we know a direct route to the specified address otherwise false.

ensureLocalRoute

Messenger ensureLocalRoute(EndpointAddress peerAddress,
                           RouteAdvertisement hint)
Get a Messenger for the specified destination if a direct route is known.

Parameters:
peerAddress - The peer who's messenger is desired.
hint - A route hint to use if a new Messenger must be created.
Returns:
Messenger for direct route or null if none could be found or created.

sendOnLocalRoute

void sendOnLocalRoute(EndpointAddress destination,
                      Message message)
                throws IOException
Send a message to a given logical destination if it maps to some messenger in our messenger pool or if such a mapping can be found and added.

Parameters:
destination - peer-based address to send the message to.
message - the message to be sent.
Throws:
IOException - if an io error occurs

init

public void init(PeerGroup group,
                 ID assignedID,
                 Advertisement impl)
          throws PeerGroupException
Initialize the module, passing it its peer group and advertisement.

Note: when subclassing one of the existing PeerGroup implementations (which implement Module), it may not be recommended to overload the init method. See the documentation of the PeerGroup class being subclassed.

Specified by:
init in interface Module
Parameters:
group - The PeerGroup from which this Module can obtain services. If this module is a Service, this is also the PeerGroup of which this module is a service.
assignedID - Identity of Module within group. modules can use it as a the root of their namespace to create names that are unique within the group but predictable by the same module on another peer. This is normally the ModuleClassID which is also the name under which the module is known by other modules. For a group it is the PeerGroupID itself. The parameters of a service, in the Peer configuration, are indexed by the assignedID of that service, and a Service must publish its run-time parameters in the Peer Advertisement under its assigned ID.
impl - The implementation advertisement for this Module. It is permissible to pass null if no implementation advertisement is available. This may happen if the implementation was selected by explicit class name rather than by following an implementation advertisement. Modules are not required to support that style of loading, but if they do, then their documentation should mention it.
Throws:
PeerGroupException - This module failed to initialize.

startApp

public int startApp(String[] arg)
Complete any remaining initialization of the module. The module should be fully functional after startApp() is completed. That is also the opportunity to supply arbitrary arguments (mostly to applications).

If this module is a PeerGroup service, it may be invoked several times depending on its return value.

Specified by:
startApp in interface Module
Parameters:
arg - An array of Strings forming the parameters for this Module.
Returns:
int A status indication which may be one of Module.START_OK, Module.START_AGAIN_PROGRESS, Module.START_AGAIN_STALLED, which indicates partial or complete success, or any other value (negative values are recommended for future compatibility), which indicates failure.

stopApp

public void stopApp()
Stop a module. This may be called any time after init() completes and should not assume that startApp() has been called or completed.

The Module cannot be forced to comply, but in the future we might be able to deny it access to anything after some timeout.

Careful that stopApp() could in theory be called before startApp().

Specified by:
stopApp in interface Module

isConnectionOriented

public boolean isConnectionOriented()
Returns true if the Message Transport is connection oriented (like TCP/IP). Indicates that the Message Transport can provide efficient transport of a series of messages to the same destination.

Specified by:
isConnectionOriented in interface MessageSender
Returns:
true if the Message Transport is connection oriented.

allowsRouting

public boolean allowsRouting()
Returns true if the Message Transport can be used by the EndpointRouter. Indicates that the Message Transport can be used in the routing of messages to destinations which are not directly reachable via this transport.

More specifically, this Message Transport will be used to route messages who's final destination is not one of the endpoint addresses available from getReachableEndpointAddresses.

Specified by:
allowsRouting in interface MessageSender
Returns:
true if the protocol can be used by the EndpointRouter

getEndpointService

public EndpointService getEndpointService()
Returns the endpoint service with which this MessageTransport is registered. If it is unregistered then null will be returned.

Specified by:
getEndpointService in interface MessageTransport
Returns:
the EndpointService with which this MessageTransport is registered.

getPublicAddress

public EndpointAddress getPublicAddress()
Returns the EndpointAddress which will be used as the source address for all messages sent by this message sender. This is the "preferred" address to which replies should be sent. This address is not necessarily the best or only address by which the peer may be reached.

The public address may also be for a different message transport.

Specified by:
getPublicAddress in interface MessageSender
Returns:
an EndpointAddress containing the public address for this message receiver.

getPublicAddresses

public Iterator<EndpointAddress> getPublicAddresses()
Returns an Iterator of all of the EndpointAddresses by which this MessageReceiver is reachable. The list is in order of "preference" with the most "preferred" EndpointAddress being at the beginning of the list.

Specified by:
getPublicAddresses in interface MessageReceiver
Returns:
an Iterator of EndpointAddresses.

getProtocolName

public String getProtocolName()
Returns a String containing the name of the protocol used by this MessageTransport. The value will match the "protocol" portion of all EndpointAddress.

Specified by:
getProtocolName in interface MessageTransport
Returns:
a String containing the name of the protocol used by this MessageTransport.

getGatewayAddress

EndpointAddress getGatewayAddress(EndpointAddress peerAddress,
                                  boolean seekRoute,
                                  RouteAdvertisement hint)
Given a peer id, return an address to reach that peer. The address may be for a directly reachable peer, or for the first gateway along a route to reach the peer. If we do not have a route to the peer, we will use the Peer Routing Protocol to try to discover one. We will wait up to 30 seconds for a route to be discovered.

Parameters:
peerAddress - the peer we are trying to reach.
seekRoute - whether to go as far as issuing a route query, or just fish in our cache. when forwarding a message we allow ourselves to mend a broken source-issued route but we won't go as far as seeking one from other peers. When originating a message, on the other end we will aggressively try to find route.
hint - whether we are passed a route hint to be used, in that case that route hint should be used
Returns:
an EndpointAddress at which that peer should be reachable.

ping

@Deprecated
public boolean ping(EndpointAddress addr)
Deprecated. 

Returns true if the specified destination address is reachable via this Message Transport otherwise returns false.

Specified by:
ping in interface MessageSender
Parameters:
addr - Address to ping
Returns:
true if the specified destination address is reachable via this Message Transport otherwise returns false.

messengerReady

public boolean messengerReady(MessengerEvent event)
Receives notifications of new messengers being generated by the underlying network transports.

IMPORTANT: Incoming messengers only. If/when this is used for outgoing, some things have to change:

For example we do not need to send the welcome msg, but for outgoing messengers, we would need to.

Currently, newMessenger handles the outgoing side.

Specified by:
messengerReady in interface MessengerEventListener
Parameters:
event - the new messenger event.
Returns:
true if the listener wants to claim the Messenger. (Normally means that it will not be offered to any other listener).

noMessenger

void noMessenger(EndpointAddress logDest)
Call when an asynchronous new messenger could not be obtained.

Parameters:
logDest - the failed logical destination

newMessenger

boolean newMessenger(MessengerEvent event)
Call when an asynchronous new messenger is ready. (name is not great).

Parameters:
event - the new messenger event.
Returns:
always returns true

getRoute

RouteAdvertisement getRoute(EndpointAddress peerAddress,
                            boolean seekRoute)
Get the routed route, if any, for a given peer id.

Parameters:
peerAddress - the peer who's route is desired.
seekRoute - boolean to indicate if we should search for a route if we don't have one
Returns:
a route advertisement describing the direct route to the peer.

setRoute

boolean setRoute(RouteAdvertisement route,
                 boolean force)
set new route info

Parameters:
route - new route to learn
force - true if the route was obtained by receiving a message
Returns:
true if route was truly new

removeRoute

void removeRoute(PeerID peerID)
This method is used to remove a route

Parameters:
peerID - route to peerid to be removed

processIncomingMessage

public void processIncomingMessage(Message msg,
                                   EndpointAddress srcAddr,
                                   EndpointAddress dstAddr)
This method is invoked by the EndpointService for each incoming message which is addressed to this listener.

Specified by:
processIncomingMessage in interface EndpointListener
Parameters:
msg - Incoming message
srcAddr - Endpoint Address of the source of the message.
dstAddr - Endpoint Address of the destination of the message.

findBestReachableEndpoint

Messenger findBestReachableEndpoint(EndpointAddress dest,
                                    List<EndpointAddress> mightWork,
                                    boolean exist)
Given a list of addresses, find the best reachable endpoint.

Parameters:
dest - destination address.
mightWork - A list of addresses to evaluate reachability.
exist - true if there already are existing messengers for the given destinations but we want one more. It may lead us to reject certain addresses that we would otherwise accept.
Returns:
The endpoint address for which we found a local route otherwise null

findReachableEndpoint

Messenger findReachableEndpoint(EndpointAddress destPeerAddress,
                                boolean exist,
                                RouteAdvertisement hint)
Read the route advertisement for a peer and find a suitable transport endpoint for sending to that peer either directly or via one of the advertised peer router

Parameters:
destPeerAddress - dest address
exist - use existing messengers, avoid creating a new one
hint - route hint
Returns:
a reachable messenger

getMessenger

public Messenger getMessenger(EndpointAddress addr,
                              Object hint)
Return a Messenger for sending messages to the specified destination EndpointAddress.

Specified by:
getMessenger in interface MessageSender
Parameters:
addr - The destination address for which a messenger is requested.
hint - An optional hint for the transport to use when creating the messenger. The format of the hint is specific to each Message Transport and may be null if no hint is provided.
Returns:
a Messenger or null if the destination is not reachable.

addressMessage

EndpointAddress addressMessage(Message message,
                               EndpointAddress dstAddress)
Updates the router element of a message and returns the peerAddress address of the next hop (where to send the message).

Currently, address message is only called for messages that we originate. As a result we will always aggressively seek a route if needed.

Parameters:
message - the message for which to compute/update a route.
dstAddress - the final destination of the route which the message be set to follow.
Returns:
EndpointAddress The address (logical) where to send the message next. Null if there is nowhere to send it to.

transportControl

public Object transportControl(Object operation,
                               Object value)
Pass a transport control object to a message transport.

Specified by:
transportControl in interface MessageTransport
Parameters:
operation - Object that specifies the type of control operation to be performed
value - Object that specifies a value object associated with the control operation
Returns:
returned object

addr2pid

static PeerID addr2pid(EndpointAddress addr)
Convert a Router EndpointAddress into a PeerID

Parameters:
addr - the address to extract peerAddress from
Returns:
the PeerID

pid2addr

static EndpointAddress pid2addr(ID pid)
Convert an ID into a Router Endpoint Address

Parameters:
pid - The ID who's equivalent Endpoint Address is desired.
Returns:
The ID as an EndpointAddress.

updateRouteAdv

void updateRouteAdv(RouteAdvertisement route)
check if it is a new route adv

Parameters:
route - route advertisement

updateRouteAdv

void updateRouteAdv(RouteAdvertisement route,
                    boolean force)
check if it is a new route adv

Parameters:
route - route advertisement
force - enforce the route

isPendingRouteQuery

boolean isPendingRouteQuery(PeerID peerID)
is there a pending route query for that destination

Parameters:
peerID - destination address
Returns:
true or false

getPendingRouteQuery

EndpointRouter.ClearPendingQuery getPendingRouteQuery(PeerID peerID)
get a pending route query info

Parameters:
peerID - destination address
Returns:
pending route query info

isRoutedRoute

boolean isRoutedRoute(PeerID peerID)
Do we have a long route for that destination

Parameters:
peerID - destination address
Returns:
true or false

getCachedMessenger

Messenger getCachedMessenger(EndpointAddress addr)
Snoop if we have a messenger

Parameters:
addr - destination address
Returns:
Messenger

getAllCachedMessengerDestinations

Iterator<EndpointAddress> getAllCachedMessengerDestinations()
Get all direct route destinations

Returns:
Iterator iterations of all endpoint destinations

getRoutedRouteAllDestinations

Iterator<Map.Entry<ID,RouteAdvertisement>> getRoutedRouteAllDestinations()
Get all long route destinations

Returns:
Iterator iterations of all routed route destinations

getAllRoutedRouteAddresses

Iterator<ID> getAllRoutedRouteAddresses()
Get all long route destination addresses

Returns:
Iterator iterations of all routed route addresses

getPendingQueriesAllDestinations

Collection<Map.Entry<PeerID,EndpointRouter.ClearPendingQuery>> getPendingQueriesAllDestinations()
Get all pendingRouteQuery destinations

Returns:
All pending route query destinations

getRouteCM

RouteCM getRouteCM()
Get the route CM cache Manager

Returns:
the route CM cache Manager

getRouteResolver

RouteResolver getRouteResolver()
Get the route resolver manager

Returns:
the route resolver Manager

setBadRoute

void setBadRoute(EndpointAddress addr,
                 BadRoute badRoute)
set bad route entry

Parameters:
addr - of the bad route
badRoute - bad route info

getBadRoute

BadRoute getBadRoute(EndpointAddress addr)
get bad route entry

Parameters:
addr - of the bad route
Returns:
BadRoute bad route info

JXSE