Project 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

This type of advertisement is used to represent a route to a destination peer in the JXTA virtual network. 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 route

The destination and hops are defined using an AccessPoint Advertisement as JXTA PeerIDs with a list of optional endpoint addresses. The endpoint addresses defined the physical endpoint addresses that can be used to reach the corresponding hop. The PeerID information is required. The endpoint address information is optional.

See Also:
PeerAdvertisement, AccessPointAdvertisement

Constructor Summary
RouteAdvertisement()
           
 
Method Summary
 void addDestEndpointAddresses(Vector addresses)
          add a new list of EndpointAddresses to the Route Destination access point
 void addEndpointAddressToHop(PeerID pid, EndpointAddress addr)
          Add a new endpointaddress to a hop
static void cleanupLoop(RouteAdvertisement route, PeerID localPeer)
          Remove loops from the route advertisement by shortcuting cycle from the route
 Object clone()
          
 Object 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()
          Returns the destination access point
 Vector getDestEndpointAddresses()
          Return the endpoint addresses of the destination
 PeerID getDestPeerID()
          Returns the route destination Peer ID
 AccessPointAdvertisement getFirstHop()
          Returns the access point for the first hop
 AccessPointAdvertisement getHop(int index)
          Return hop of the route at location index in the hops list
 AccessPointAdvertisement getHop(PeerID pid)
          return a hop from the list of hops
 Enumeration getHops()
          returns the list of hops
 ID getID()
          Returns a unique ID suitable for indexing of this Advertisement.
 AccessPointAdvertisement getLastHop()
          Returns the access point for the last hop
 Vector getVectorHops()
          returns the list of hops
 boolean hasALoop()
          check if the route has a loop
static RouteAdvertisement newRoute(PeerID destPid, PeerID firsthop, Vector hops)
          construct a new route

WARNING hops may be MODIFIED.

static RouteAdvertisement newRoute(PeerID destPid, Vector hops)
          construct a new route, all hops are in the hops parameter.
 AccessPointAdvertisement nextHop(PeerID pid)
          get the nexthop after the given hop
 void removeDestEndpointAddresses(Vector addresses)
          remove a list of EndpointAddresses from the Route Destination access point
 void removeEndpointAddressToHop(PeerID pid, EndpointAddress addr)
          remove an endpointaddress to a hop
 boolean removeHop(PeerID pid)
          remove a hop from the list of hops
 void replaceHop(AccessPointAdvertisement ap)
          replace a hop from the list of hops
 void setDest(AccessPointAdvertisement ap)
          Sets the access point of the destination
 void setDestEndpointAddresses(Vector ea)
          Set the route destination endpoint addresses
 void setDestPeerID(PeerID pid)
          Sets the route destination peer id
 void setFirstHop(AccessPointAdvertisement ap)
          Sets the access point for the first hop
 void setHops(Vector hopsAccess)
          sets the list of hops associated with this route
 void setLastHop(AccessPointAdvertisement ap)
          Sets the access point for 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, handleElement
 
Methods inherited from class net.jxta.document.Advertisement
getAdvType, getIndexFields, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RouteAdvertisement

public RouteAdvertisement()
Method Detail

clone

public Object clone()

Overrides:
clone in class Advertisement

cloneOnlyPIDs

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

Returns:
object clone route advertisement

getAdvertisementType

public static final 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 a unique ID suitable for indexing of this Advertisement.

The ID is supposed to be unique and is not guaranteed to be of any particular subclass of ID. Each class of advertisement is responsible for the choice of ID to return. The value for the ID returned can either be:

Since this ID is normally used for indexing, the IDs returned must be as unique as possible to avoid collisions.

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: unitialized index fields). Instead java.lang.IllegalStateException should be thrown.

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

getDest

public AccessPointAdvertisement getDest()
Returns the destination access point

Returns:
AccessPointAdvertisement

setDest

public void setDest(AccessPointAdvertisement ap)
Sets the access point of the destination

Parameters:
ap - AccessPointAdvertisement of the destination peer

getHops

public Enumeration getHops()
returns the list of hops

Returns:
Enumeration list of hops as AccessPointAdvertisement

getVectorHops

public Vector getVectorHops()
returns the list of hops

Returns:
Vectorlist of hops as AccessPointAdvertisement

setHops

public void setHops(Vector hopsAccess)
sets the list of hops associated with this route

Parameters:
hopsAccess - Enumeration of hops as AccessPointAdvertisement The vector of hops is specified as a vector of AccessPoint advertisement.

addDestEndpointAddresses

public void addDestEndpointAddresses(Vector addresses)
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.

removeDestEndpointAddresses

public void removeDestEndpointAddresses(Vector addresses)
remove a list of EndpointAddresses from the Route Destination access point

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

getFirstHop

public AccessPointAdvertisement getFirstHop()
Returns the access point for the first hop

Returns:
AccessPointAdvertisement first hop

setFirstHop

public void setFirstHop(AccessPointAdvertisement ap)
Sets the access point for the first hop

Parameters:
ap - AccessPointAdvertisement of the first hop

getLastHop

public AccessPointAdvertisement getLastHop()
Returns the access point for the last hop

Returns:
AccessPointAdvertisement last hop

setLastHop

public void setLastHop(AccessPointAdvertisement ap)
Sets the access point for the last hop

Parameters:
ap - AccessPointAdvertisement of the last hop

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

setDestEndpointAddresses

public void setDestEndpointAddresses(Vector ea)
Set the route destination endpoint addresses

Parameters:
ea - vector of endpoint addresses. Warning: The vector of endpoint addresses is specified as a vector of String. Each string representing one endpoint address.

getDestEndpointAddresses

public Vector getDestEndpointAddresses()
Return the endpoint addresses of the destination

Returns:
vector of endpoint addresses. Warning: The vector of endpoint addresses is specified as a vector of String. Each string representing one endpoint address.

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

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 pid)
get the nexthop after the given hop

Parameters:
pid - 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

replaceHop

public void replaceHop(AccessPointAdvertisement ap)
replace a hop from the list of hops

Parameters:
ap - accesspointadvertisement of the hop to replace

addEndpointAddressToHop

public void addEndpointAddressToHop(PeerID pid,
                                    EndpointAddress addr)
Add a new endpointaddress to a hop

Parameters:
pid - id of the hop
addr - new endpoint address to add

removeEndpointAddressToHop

public void removeEndpointAddressToHop(PeerID pid,
                                       EndpointAddress addr)
remove an endpointaddress to a hop

Parameters:
pid - id of the hop
addr - new endpoint address to remove

equals

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

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

getHop

public AccessPointAdvertisement getHop(int index)
Return hop of the route at location index in the hops list

Parameters:
index - in the list of hops
Returns:
hop AccessPointAdvertisement of the hops

newRoute

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

WARNING hops may be MODIFIED.


newRoute

public static RouteAdvertisement newRoute(PeerID destPid,
                                          Vector hops)
construct a new route, all hops are in the hops parameter.


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,


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


cleanupLoop

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


JXTA J2SE