routeadvertisement.java

jxta平台的开发包

/*
 *
 * $Id: RouteAdvertisement.java,v 1.39 2006/01/13 18:06:14 bondolo Exp $
 *
 * Copyright (c) 2001 Sun Microsystems, Inc.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:
 *       "This product includes software developed by the
 *       Sun Microsystems, Inc. for Project JXTA."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA"
 *    must not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact Project JXTA at http://www.jxta.org.
 *
 * 5. Products derived from this software may not be called "JXTA",
 *    nor may "JXTA" appear in their name, without prior written
 *    permission of Sun.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL SUN MICROSYSTEMS OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of Project JXTA.  For more
 * information on Project JXTA, please see
 * <http://www.jxta.org/>.
 *
 * This license is based on the BSD license adopted by the Apache Foundation.
 */


package net.jxta.protocol;

import java.io.InputStream;
import java.io.ByteArrayInputStream;
import java.util.Enumeration;
import java.util.Iterator;
import java.util.Vector;

import net.jxta.document.AdvertisementFactory;
import net.jxta.document.ExtendableAdvertisement;
import net.jxta.id.ID;
import net.jxta.id.IDFactory;
import net.jxta.peer.PeerID;
import net.jxta.peergroup.PeerGroupID;
import net.jxta.endpoint.EndpointAddress;

/**
 * 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:
 *
 * <pre> Dest
 *       hop 1
 *       hop 2
 *       hop 3
 *       ....
 *       hop n
 *</pre>
 *
 * <p/>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
 *
 * <p/>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 net.jxta.protocol.PeerAdvertisement
 * @see net.jxta.protocol.AccessPointAdvertisement
 *
 **/
public abstract class RouteAdvertisement extends ExtendableAdvertisement implements Cloneable {
    
    public static final String DEST_PID_TAG = "DstPID";

    /**
     *  Destination address
     **/
    private PeerID  destPeer = null;
    
    /**
     *  Destination address
     **/
    private AccessPointAdvertisement dest = null;
    
    /**
     *  Semi-ordered list of alternative hops to the destination.
     *
     *  <p/><ul>
     *      <li>Each item is an {@link AccessPointAdvertisement}.</li>
     *  </ul>
     **/
    private Vector hops = new Vector();
    private transient ID hashID = null;
    
    /**
     *  {@inheritDoc}
     */
    public Object clone() {
        try {
            return super.clone();
        } catch( CloneNotSupportedException impossible ) {
            throw new Error( "Object.clone() threw CloneNotSupportedException", impossible );
        }
    }
    
    /**
     * makes a copy of a route advertisement
     * that only contains PID not endpoint addresses
     *
     * @return object clone route advertisement
     **/
    public Object cloneOnlyPIDs() {
        RouteAdvertisement a;
        try {
            a = (RouteAdvertisement) super.clone();
            a.setDestEndpointAddresses(new Vector());
        } catch (CloneNotSupportedException impossible) {
            return null;
        }
        
        // deep copy of the hops
        Vector clonehops = getVectorHops();
        int size = clonehops.size();
        for (int i = 0; i < size; ++i) {
            clonehops.set( i, ((AccessPointAdvertisement) clonehops.get(i)).clone() );
        }
        
        a.setHops( clonehops );
        
        return a;
    }   
    
    /**
     * Compare if two routes are equals. Equals means
     * the same number of hops and the same endpoint addresses
     * for each hop and the destination
     *
     * @param target  the route to compare against
     * @return boolean true if the route is equal to this route otherwise false
     */
    public boolean equals(Object target) {
        
        if( this == target ) {
            return true;
        }
        
        if( !(target instanceof RouteAdvertisement)) {
            return false;
        }
        
        RouteAdvertisement route = (RouteAdvertisement) target;

        // check each of the hops
        // routes need to have the same size
        if (hops.size() != route.size()) {
            return false;
        }
        
        int index = 0;
        for (Enumeration e = route.getHops(); e.hasMoreElements();) {
            AccessPointAdvertisement hop = (AccessPointAdvertisement) e.nextElement();
            if (!hop.equals((AccessPointAdvertisement) hops.elementAt(index++))) {
                return false;
            }
        }
 
        if (dest == null && route.getDest() == null)
            return true;
        
        if (dest == null || route.getDest() == null)
            return false;
        
        // chek the destination
        return dest.equals(route.getDest());
    }
    
    /**
     *  Returns the identifying type of this Advertisement.
     *
     * @return String the type of advertisement
     **/
    public final static String getAdvertisementType() {
        return "jxta:RA" ;
    }
    
    /**
     * {@inheritDoc}
     **/
    public final String getBaseAdvType() {
        return getAdvertisementType();
    }
    
    /**
     * {@inheritDoc}
     */
    public synchronized ID getID() {
        if (hashID == null) {
            try {
                // We have not yet built it. Do it now
                // The group id is somewhat redundant since it is already
                // part of the peer ID, but that's the way CodatID want it.
                PeerID pid = dest.getPeerID();
                byte[] seed = getAdvertisementType().getBytes();
                InputStream in = new ByteArrayInputStream(pid.toString().getBytes());                
                hashID = IDFactory.newCodatID((PeerGroupID) pid.getPeerGroupID(), seed, in);
            } catch (Exception ez) {
                return ID.nullID;
            }
        }
        return hashID;
    }
    
    /**
     * Returns the destination access point
     *
     * @return AccessPointAdvertisement
     */
    public AccessPointAdvertisement getDest() {
        return dest;
    }
    
    /**
     * Sets the access point of the destination
     *
     * @param ap AccessPointAdvertisement of the destination peer
     */
    public void setDest(AccessPointAdvertisement ap) {
        this.dest = ap;
        
        if((null != dest) && (null != dest.getPeerID()) ) {
            setDestPeerID( dest.getPeerID() );
        }
    }
    
    /**
     * returns the list of hops
     *
     * @return Enumeration list of hops as AccessPointAdvertisement
     */
    public Enumeration getHops() {
        return hops.elements();
    }
    
    /**
     * returns the list of hops
     *
     * @return Vectorlist of hops as AccessPointAdvertisement
     */
    public Vector getVectorHops() {
        return hops;
    }   
    
    /**
     * sets the list of hops associated with this route
     *
     * @param hopsAccess Enumeration of hops as AccessPointAdvertisement
     * The vector of hops is specified as a vector of AccessPoint
     * advertisement.
     */
    public void setHops(Vector hopsAccess) {
        // It is legal to set it to null but it is automatically converted
        // to an empty vector. The member hops is NEVER null.
        hops = hopsAccess != null ? hopsAccess : new Vector();
    }
    
    /** 
     * add a new list of EndpointAddresses to the Route Destination access
     * point
     *
     * @deprecated Use {@link #getDest()} and modify AccessPointAdvertisement directly.
     *
      *@param 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.
     */
    public void addDestEndpointAddresses(Vector addresses) {
        dest.addEndpointAddresses(addresses);
    }
    
    /**
     * remove a list of EndpointAddresses from the Route Destination
     * access point
     *
     * @deprecated Use {@link #getDest()} and modify AccessPointAdvertisement directly.
     *
     * @param 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.
     */
    public void removeDestEndpointAddresses(Vector addresses) {
        dest.removeEndpointAddresses(addresses);
    }
    
    
    /**
     * Returns the access point for the first hop
     *
     * @return AccessPointAdvertisement first hop
     */
    public AccessPointAdvertisement getFirstHop() {
        if (hops == null || hops.isEmpty())
            return null;
        else
            return (AccessPointAdvertisement) hops.firstElement();
    }
    
    /**
     * Sets the access point for the first hop
     *
     * @param ap AccessPointAdvertisement of the first hop
     *
     */
    public void setFirstHop(AccessPointAdvertisement ap) {
        hops.add(0, ap);
    }
    
    /**
     * Returns the access point for the last hop
     *
     * @return AccessPointAdvertisement last hop
     */
    public AccessPointAdvertisement getLastHop() {
        if (hops == null || hops.isEmpty())
            return null;
        else
            return (AccessPointAdvertisement) hops.lastElement();
    }
    
    /**
     * Sets the access point for the last hop
     *
     * @param ap AccessPointAdvertisement of the last hop
     *
     */
    public void setLastHop(AccessPointAdvertisement ap) {
        hops.addElement(ap);
    }
    
    /**
     * Returns the route destination Peer ID
     *
     * @return peerID of the destination of the route
     */
    public PeerID getDestPeerID() {
        return destPeer;
    }
    
    
    /**
     * Sets the route destination peer id
     *
     * @param pid route destination peerID
     *
     */
    public void setDestPeerID(PeerID pid) {
        destPeer = pid;
        
        if( null != dest )
            dest.setPeerID( pid );
    }
    
    /**
     * Set the route destination endpoint addresses
     *
     * @deprecated Use {@link #getDest()} and modify AccessPointAdvertisement directly.
     *
     * @param ea vector of endpoint addresses. Warning: The vector of endpoint
     * addresses is specified as a vector of String. Each string
     * representing one endpoint address.
     *
     */
    public void setDestEndpointAddresses(Vector ea) {
        dest.setEndpointAddresses(ea);
    }
    
    /**
     * Return the endpoint addresses of the destination
     *
     * @deprecated Use {@link #getDest()} and modify AccessPointAdvertisement directly.
     *
     * @return vector of endpoint addresses as String. <b>This is live data.</b>
     */
    public Vector getDestEndpointAddresses() {
        return dest.getVectorEndpointAddresses();
    }
    
    /**
     * Check if the route contains the following hop
     *
     * @param pid peer id of the hop
     * @return boolean true or false if the hop is found in the route
     */
    public boolean containsHop(PeerID pid) {
        for (Enumeration e = hops.elements(); e.hasMoreElements();) {
            AccessPointAdvertisement hop = (AccessPointAdvertisement)
            e.nextElement();
            PeerID hid = hop.getPeerID();