/* * * $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();