JXTA

net.jxta.protocol
Class RouteAdvertisement

java.lang.Object
  extended by net.jxta.document.Advertisement
      extended by net.jxta.document.ExtendableAdvertisement
          extended by net.jxta.protocol.RouteAdvertisement
All Implemented Interfaces:
Cloneable

public abstract class RouteAdvertisement
extends ExtendableAdvertisement
implements Cloneable

Advertisement used to represent a route to a peer. Routes are represented in a generic manner as a sequence of hops to reach the destination. Each hop represent a potential relay peer in the route:

 Dest
       hop 1
       hop 2
       hop 3
       ....
       hop n
 

A route can have as many hops as necessary. Hops are implicitly ordered starting from the hop with the shortest route to reach the destination. If a peer cannot reach directly the dest, it should try to reach in descending order one of the listed hops. Some hops may have the same physical distance to the destination. Some hops may define alternative routes.

The destination and hops are defined using a AccessPointAdvertisements.

See Also:
PeerAdvertisement, AccessPointAdvertisement

Field Summary
static String DEST_PID_TAG
           
 
Constructor Summary
RouteAdvertisement()
           
 
Method Summary
 void addDestEndpointAddress(EndpointAddress addr)
          Add the specified endpoint address to destination peer.
 void addDestEndpointAddresses(List<EndpointAddress> addrs)
          Add all of the specified endpoint addresses to destination peer.
 void addDestEndpointAddresses(Vector<String> addresses)
          Deprecated. Use #addDestEndpointAddresses(List) instead.
static void cleanupLoop(RouteAdvertisement route, PeerID localPeer)
          Remove loops from the route advertisement by shortcutting cycle from the route
 void clearDestEndpointAddresses()
          Clears all endpoint addresses associated with the destination peer.
 RouteAdvertisement clone()
          
 RouteAdvertisement cloneOnlyPIDs()
          makes a copy of a route advertisement that only contains PID not endpoint addresses
 boolean containsHop(PeerID pid)
          Check if the route contains the following hop
 String display()
          Generate a string that displays the route information for logging or debugging purpose
 boolean equals(Object target)
          Compare if two routes are equals.
static String getAdvertisementType()
          Returns the identifying type of this Advertisement.
 String getBaseAdvType()
          Returns the base type of this advertisement hierarchy.
 AccessPointAdvertisement getDest()
          Deprecated. Because this method unsafely exposes destination AccessPointAdvertisement it will be removed.
 List<EndpointAddress> getDestEndpointAddresses()
          Returns the endpoint addresses of the destination peer in their preferred order.
 PeerID getDestPeerID()
          Returns the route destination Peer ID
 AccessPointAdvertisement getFirstHop()
          Returns the AccessPointAdvertisement of first hop.
 AccessPointAdvertisement getHop(PeerID pid)
          Return a hop from the list of hops.
 Enumeration<AccessPointAdvertisement> getHops()
          returns the list of hops
 ID getID()
          Returns an ID which identifies this Advertisement as uniquely as possible.
 AccessPointAdvertisement getLastHop()
          Returns the access point for the last hop.
 Vector<AccessPointAdvertisement> getVectorHops()
          returns the list of hops
 boolean hasALoop()
          check if the route has a loop
 int hashCode()
          
static RouteAdvertisement newRoute(PeerID destPid, PeerID firsthop, Vector<AccessPointAdvertisement> hops)
          construct a new route

WARNING hops may be MODIFIED.

 AccessPointAdvertisement nextHop(PeerID currentHop)
          Return the hop that follows the specified currentHop.
 void removeDestEndpointAddress(EndpointAddress addr)
          Remove the specified endpoint address to destination peer.
 void removeDestEndpointAddresses(Collection<EndpointAddress> addrs)
          Remove the specified endpoint addresses from destination peer.
 void removeDestEndpointAddresses(Vector<String> addresses)
          Deprecated. Use removeDestEndpointAddresses(Collection).
 boolean removeHop(PeerID pid)
          Remove a hop from the list of hops.
 void setDest(AccessPointAdvertisement ap)
          Sets the access point of the destination.
 void setDestEndpointAddresses(Vector<String> ea)
          Deprecated. Use addDestEndpointAddress(EndpointAddress) instead.
 void setDestPeerID(PeerID pid)
          Sets the route destination peer id.
 void setFirstHop(AccessPointAdvertisement ap)
          Sets the AccessPointAdvertisement for the first hop.
 void setHops(Vector<AccessPointAdvertisement> newHops)
          Sets the list of hops associated with this route.
 void setLastHop(AccessPointAdvertisement ap)
          Sets the AccessPointAdvertisement of the last hop.
 int size()
          return the length of the route
static boolean stichRoute(RouteAdvertisement newRoute, RouteAdvertisement firstLeg)
          Alter the given newRoute (which does not start from here) by using firstLeg, a known route to whence it starts from.
static boolean stichRoute(RouteAdvertisement newRoute, RouteAdvertisement firstLeg, PeerID localPeer)
          Alter the given newRoute (which does not start from here) by using firstLeg, a known route to whence it starts from.
 
Methods inherited from class net.jxta.document.ExtendableAdvertisement
getDocument, handleAttribute, handleElement
 
Methods inherited from class net.jxta.document.Advertisement
getAdvType, getIndexFields, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

DEST_PID_TAG

public static final String DEST_PID_TAG
See Also:
Constant Field Values
Constructor Detail

RouteAdvertisement

public RouteAdvertisement()
Method Detail

newRoute

public static RouteAdvertisement newRoute(PeerID destPid,
                                          PeerID firsthop,
                                          Vector<AccessPointAdvertisement> hops)
construct a new route

WARNING hops may be MODIFIED.

Parameters:
destPid - destination
firsthop - first hop node ID
hops - routes
Returns:
the new route

clone

public RouteAdvertisement clone()

Overrides:
clone in class Advertisement

cloneOnlyPIDs

public RouteAdvertisement cloneOnlyPIDs()
makes a copy of a route advertisement that only contains PID not endpoint addresses

Returns:
object clone route advertisement

equals

public boolean equals(Object target)
Compare if two routes are equals. Equals means same destination with the same endpoint addresses and thee same number of hops and the same endpoint addresses for each hop.

Overrides:
equals in class Object
Parameters:
target - the route to compare against
Returns:
boolean true if the route is equal to this route otherwise false

hashCode

public int hashCode()

Overrides:
hashCode in class Object

getAdvertisementType

public static String getAdvertisementType()
Returns the identifying type of this Advertisement.

Returns:
String the type of advertisement

getBaseAdvType

public final String getBaseAdvType()
Returns the base type of this advertisement hierarchy. Typically, only the most basic advertisement of a type will implement this method and declare it as final.

Specified by:
getBaseAdvType in class ExtendableAdvertisement
Returns:
String the base type of advertisements in this hierarchy.

getID

public ID getID()
Returns an ID which identifies this Advertisement as uniquely as possible. This ID is typically used as the primary key for indexing of the Advertisement within databases.

Each advertisement sub-class must choose an appropriate implementation which returns canonical and relatively unique ID values for it's instances. Since this ID is commonly used for indexing, the IDs returned must be as unique as possible to avoid collisions. The value for the ID returned can either be:

For Advertisement types which normally return non-ID.nullID values no ID should be returned when asked to generate an ID while the Advertisement is an inconsistent state (example: uninitialized index fields). Instead IllegalStateException should be thrown.

Specified by:
getID in class Advertisement
Returns:
An ID that relatively uniquely identifies this advertisement or ID.nullID if this advertisement is of a type that is not normally indexed.

getDestPeerID

public PeerID getDestPeerID()
Returns the route destination Peer ID

Returns:
peerID of the destination of the route

setDestPeerID

public void setDestPeerID(PeerID pid)
Sets the route destination peer id.

Parameters:
pid - route destination peerID

getDest

@Deprecated
public AccessPointAdvertisement getDest()
Deprecated. Because this method unsafely exposes destination AccessPointAdvertisement it will be removed.

Returns the destination access point. This does NOT copy the AccessPointAdvertisement.

Returns:
AccessPointAdvertisement of the destination peer.

setDest

public void setDest(AccessPointAdvertisement ap)
Sets the access point of the destination. This does NOT copy the AccessPointAdvertisement.

Parameters:
ap - AccessPointAdvertisement of the destination peer

addDestEndpointAddresses

@Deprecated
public void addDestEndpointAddresses(Vector<String> addresses)
Deprecated. Use #addDestEndpointAddresses(List) instead.

Add a new list of EndpointAddresses to the Route Destination access point

Parameters:
addresses - vector of endpoint addresses to add to the destination access point. Warning: The vector of endpoint addresses is specified as a vector of String. Each string representing one endpoint address.

clearDestEndpointAddresses

public void clearDestEndpointAddresses()
Clears all endpoint addresses associated with the destination peer.


addDestEndpointAddress

public void addDestEndpointAddress(EndpointAddress addr)
Add the specified endpoint address to destination peer.

Parameters:
addr - EndpointAddress to add.

addDestEndpointAddresses

public void addDestEndpointAddresses(List<EndpointAddress> addrs)
Add all of the specified endpoint addresses to destination peer.

Parameters:
addrs - EndpointAddresses to add.

removeDestEndpointAddress

public void removeDestEndpointAddress(EndpointAddress addr)
Remove the specified endpoint address to destination peer.

Parameters:
addr - EndpointAddress to add.

removeDestEndpointAddresses

public void removeDestEndpointAddresses(Collection<EndpointAddress> addrs)
Remove the specified endpoint addresses from destination peer.

Parameters:
addrs - EndpointAddress to add.

removeDestEndpointAddresses

@Deprecated
public void removeDestEndpointAddresses(Vector<String> addresses)
Deprecated. Use removeDestEndpointAddresses(Collection).

Remove a list of EndpointAddresses from the Route Destination access point

Parameters:
addresses - vector of endpoint addresses to remove from the destination access point.

getDestEndpointAddresses

public List<EndpointAddress> getDestEndpointAddresses()
Returns the endpoint addresses of the destination peer in their preferred order.

Returns:
The EndpointAddresses of the destination peer.

setDestEndpointAddresses

@Deprecated
public void setDestEndpointAddresses(Vector<String> ea)
Deprecated. Use addDestEndpointAddress(EndpointAddress) instead.

Set the route destination endpoint addresses

Parameters:
ea - vector of endpoint addresses. Warning: The vector is not copied and is used directly.

getHops

public Enumeration<AccessPointAdvertisement> getHops()
returns the list of hops

Returns:
Enumeration list of hops as AccessPointAdvertisement

getVectorHops

public Vector<AccessPointAdvertisement> getVectorHops()
returns the list of hops

Returns:
Vector list of hops as AccessPointAdvertisement

setHops

public void setHops(Vector<AccessPointAdvertisement> newHops)
Sets the list of hops associated with this route.

Parameters:
newHops - AccessPointAdvertisements which form the hops. The Vector is NOT copied.

containsHop

public boolean containsHop(PeerID pid)
Check if the route contains the following hop

Parameters:
pid - peer id of the hop
Returns:
boolean true or false if the hop is found in the route

getFirstHop

public AccessPointAdvertisement getFirstHop()
Returns the AccessPointAdvertisement of first hop. The AccessPointAdvertisement is not cloned.

Returns:
AccessPointAdvertisement of first hop.

setFirstHop

public void setFirstHop(AccessPointAdvertisement ap)
Sets the AccessPointAdvertisement for the first hop. The AccessPointAdvertisement is not cloned.

Parameters:
ap - AccessPointAdvertisement of the first hop.

getLastHop

public AccessPointAdvertisement getLastHop()
Returns the access point for the last hop. The AccessPointAdvertisement is not cloned.

Returns:
AccessPointAdvertisement last hop.

setLastHop

public void setLastHop(AccessPointAdvertisement ap)
Sets the AccessPointAdvertisement of the last hop. The AccessPointAdvertisement is not cloned.

Parameters:
ap - AccessPointAdvertisement of the last hop.

hasALoop

public boolean hasALoop()
check if the route has a loop

Returns:
boolean true or false if the route has a loop

size

public int size()
return the length of the route

Returns:
int size of the route

nextHop

public AccessPointAdvertisement nextHop(PeerID currentHop)
Return the hop that follows the specified currentHop. The AccessPointAdvertisement is not cloned.

Parameters:
currentHop - PeerID of the current hop
Returns:
ap AccessPointAdvertisement of the next Hop

display

public String display()
Generate a string that displays the route information for logging or debugging purpose

Returns:
String return a string containing the route info

removeHop

public boolean removeHop(PeerID pid)
Remove a hop from the list of hops.

Parameters:
pid - peer id of the hop
Returns:
boolean true or false if the hop is found in the route

getHop

public AccessPointAdvertisement getHop(PeerID pid)
Return a hop from the list of hops.

Parameters:
pid - peer id of the hop
Returns:
AccessPointAdvertisement of the corresponding hop

stichRoute

public static boolean stichRoute(RouteAdvertisement newRoute,
                                 RouteAdvertisement firstLeg)
Alter the given newRoute (which does not start from here) by using firstLeg, a known route to whence it starts from. So that the complete route goes from here to the end-destination via firstLeg. public static boolean stichRoute(RouteAdvertisement newRoute,

Parameters:
newRoute - the new route
firstLeg - the first route
Returns:
true if successful

stichRoute

public static boolean stichRoute(RouteAdvertisement newRoute,
                                 RouteAdvertisement firstLeg,
                                 PeerID localPeer)
Alter the given newRoute (which does not start from here) by using firstLeg, a known route to whence it starts from. So that the complete route goes from here to the end-destination via firstLeg also shortcut the route by removing the local peer.

Parameters:
newRoute - the new route
firstLeg - first hop
localPeer - local PeerID
Returns:
true if successful

cleanupLoop

public static void cleanupLoop(RouteAdvertisement route,
                               PeerID localPeer)
Remove loops from the route advertisement by shortcutting cycle from the route

Parameters:
route - the route advertisement
localPeer - local PeerID

JXSE