sjero.net Git - linphone/blob - p2pproxy/dependencies-src/jxse-src-2.5/api/src/net/jxta/protocol/AccessPointAdvertisement.java

   1 /*
   2  * Copyright (c) 2001-2007 Sun Microsystems, Inc.  All rights reserved.
   3  *
   4  *  The Sun Project JXTA(TM) Software License
   5  *
   6  *  Redistribution and use in source and binary forms, with or without
   7  *  modification, are permitted provided that the following conditions are met:
   8  *
   9  *  1. Redistributions of source code must retain the above copyright notice,
  10  *     this list of conditions and the following disclaimer.
  11  *
  12  *  2. Redistributions in binary form must reproduce the above copyright notice,
  13  *     this list of conditions and the following disclaimer in the documentation
  14  *     and/or other materials provided with the distribution.
  15  *
  16  *  3. The end-user documentation included with the redistribution, if any, must
  17  *     include the following acknowledgment: "This product includes software
  18  *     developed by Sun Microsystems, Inc. for JXTA(TM) technology."
  19  *     Alternately, this acknowledgment may appear in the software itself, if
  20  *     and wherever such third-party acknowledgments normally appear.
  21  *
  22  *  4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA" must
  23  *     not be used to endorse or promote products derived from this software
  24  *     without prior written permission. For written permission, please contact
  25  *     Project JXTA at http://www.jxta.org.
  26  *
  27  *  5. Products derived from this software may not be called "JXTA", nor may
  28  *     "JXTA" appear in their name, without prior written permission of Sun.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
  31  *  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  32  *  FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SUN
  33  *  MICROSYSTEMS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  34  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  35  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
  36  *  OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  37  *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  38  *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  39  *  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40  *
  41  *  JXTA is a registered trademark of Sun Microsystems, Inc. in the United
  42  *  States and other countries.
  43  *
  44  *  Please see the license information page at :
  45  *  <http://www.jxta.org/project/www/license.html> for instructions on use of
  46  *  the license in source files.
  47  *
  48  *  ====================================================================
  49  *
  50  *  This software consists of voluntary contributions made by many individuals
  51  *  on behalf of Project JXTA. For more information on Project JXTA, please see
  52  *  http://www.jxta.org.
  53  *
  54  *  This license is based on the BSD license adopted by the Apache Foundation.
  55  */
  56
  57 package net.jxta.protocol;
  58
  59
  60 import java.util.Collection;
  61 import net.jxta.document.ExtendableAdvertisement;
  62 import net.jxta.endpoint.EndpointAddress;
  63 import net.jxta.peer.PeerID;
  64
  65 import java.util.Enumeration;
  66 import java.util.List;
  67 import java.util.Vector;
  68
  69
  70 /**
  71  * Provides a simple association of a {@code PeerID} to an ordered list of
  72  * {@code EndpointAddress} entries. Each {@code EndpointAddress} defines one
  73  * Message Transport address by which the peer may be reached. The addresses
  74  * are sorted in the preferred order (which may refer to performance, cost,
  75  * efficiency, etc.) which they should be used.
  76  * <p/>
  77  * The Access Point Advertisement is most commonly used as part of other
  78  * Advertisements such as {@code RouteAdvertisement}.
  79  *
  80  * @see net.jxta.protocol.PeerAdvertisement
  81  * @see net.jxta.protocol.RouteAdvertisement
  82  */
  83 public abstract class AccessPointAdvertisement extends ExtendableAdvertisement implements Cloneable {
  84
  85     /**
  86      * The peer id of the peer with these endpoints. May be {@code null}
  87      * if the APA is used as a sub-element of a structure in which the context
  88      * peerid is already known.
  89      */
  90     private PeerID pid = null;
  91
  92     /**
  93      * The EndpointAddresses associated with the specified peer in preferred
  94      * order.
  95      * <p/>
  96      * <ul>
  97      * <li>Values are, sadly, {@link java.lang.String} of
  98      * {@link net.jxta.endpoint.EndpointAddress}.</li>
  99      * </ul>
 100      */
 101     private Vector<String> endpointAddresses = new Vector<String>();
 102
 103     /**
 104      * {@inheritDoc}
 105      * <p/>
 106      * <p/>Make a deep copy.
 107      */
 108     @Override
 109     public AccessPointAdvertisement clone() {
 110         try {
 111             AccessPointAdvertisement a = (AccessPointAdvertisement) super.clone();
 112
 113             a.setPeerID(getPeerID());
 114             a.addEndpointAddresses(endpointAddresses);
 115
 116             return a;
 117         } catch (CloneNotSupportedException impossible) {
 118             throw new Error("Object.clone() threw CloneNotSupportedException", impossible);
 119         }
 120     }
 121
 122     /**
 123      * {@inheritDoc}
 124      * <p/>
 125      * Equals means the same PID and the same endpoint addresses.
 126      */
 127     @Override
 128     public boolean equals(Object target) {
 129
 130         if (this == target) {
 131             return true;
 132         }
 133
 134         if (!(target instanceof AccessPointAdvertisement)) {
 135             return false;
 136         }
 137
 138         AccessPointAdvertisement ap = (AccessPointAdvertisement) target;
 139
 140         if ((null == getPeerID()) && (null != ap.getPeerID())) {
 141             return false;
 142         }
 143
 144         if ((null != getPeerID())) {
 145             if (!getPeerID().equals(ap.getPeerID())) {
 146                 return false;
 147             }
 148         }
 149         if (endpointAddresses.size() != ap.endpointAddresses.size()) {
 150             return false;
 151         }
 152
 153         // XXX 20061127 bondolo This eventually should be an ordered comparison.
 154
 155         for (String anEA : endpointAddresses) {
 156             if (!ap.endpointAddresses.contains(anEA)) {
 157                 return false;
 158             }
 159         }
 160
 161         return true;
 162     }
 163
 164     /**
 165      * {@inheritDoc}
 166      */
 167     @Override
 168     public int hashCode() {
 169         if (null != pid) {
 170             return pid.hashCode();
 171         } else {
 172             // force all incomplete advertisements to hash to the same place.
 173             return 1;
 174         }
 175     }
 176
 177     /**
 178      * Returns the identifying type of this Advertisement.
 179      *
 180      * @return String the type of advertisement
 181      */
 182     public static String getAdvertisementType() {
 183         return "jxta:APA";
 184     }
 185
 186     /**
 187      * {@inheritDoc}
 188      */
 189     @Override
 190     public final String getBaseAdvType() {
 191         return getAdvertisementType();
 192     }
 193
 194     /**
 195      * Gets the PeerID for this access point.
 196      *
 197      * @return PeerID The peer id associated with the endpoint addresses or
 198      *         {@code null} if no peer has been directly associated.
 199      */
 200     public PeerID getPeerID() {
 201         return pid;
 202     }
 203
 204     /**
 205      * Sets the PeerID for this access point.
 206      *
 207      * @param pid The peer id associated with the endpoint addresses or
 208      *            {@code null} if no peer is directly associated.
 209      */
 210     public void setPeerID(PeerID pid) {
 211         this.pid = pid;
 212     }
 213
 214     /**
 215      *  Add all of the provided EndpointAddresses.
 216      *
 217      *  @param addrs Add all of the specified endpoint addresses.
 218      */
 219     public void addEndpointAddresses(List<EndpointAddress> addrs) {
 220         for (EndpointAddress addr : addrs) {
 221             addEndpointAddress(addr);
 222         }
 223     }
 224
 225     /**
 226      *  Clears all EndpointAddresses.
 227      */
 228     public void clearEndpointAddresses() {
 229         endpointAddresses.clear();
 230     }
 231
 232     /**
 233      *  Remove the specified EndpointAddress.
 234      *
 235      *  @param addr EndpointAddress to remove.
 236      */
 237     public void removeEndpointAddress(EndpointAddress addr) {
 238         endpointAddresses.remove(addr.toString());
 239     }
 240
 241     /**
 242      *  Remove the specified EndpointAddresses.
 243      *
 244      *  @param addrs EndpointAddresses to remove.
 245      */
 246     public void removeEndpointAddresses(Collection<EndpointAddress> addrs) {
 247         for (EndpointAddress addr : addrs) {
 248             endpointAddresses.remove(addr.toString());
 249         }
 250     }
 251
 252     /**
 253      * Returns the endpoint addresses associated with this access point.
 254      *
 255      * @return The endpoint addresses associated with this access point
 256      *         represented as {@link java.lang.String}.
 257      */
 258     public Enumeration<String> getEndpointAddresses() {
 259         return endpointAddresses.elements();
 260     }
 261
 262     /**
 263      * Returns the vector of endpoint addresses associated with this access
 264      * point. The result is a vector of endpoint addresses represented as
 265      * {@code String}. <strong>The Vector contains the "live" data of this
 266      * advertisement. It should be modified only with great care.</strong>
 267      *
 268      * @return The endpoint addresses associated with this access point
 269      *         represented as {@link java.lang.String}.
 270      * @deprecated Returning the Vector is dangerous and unwise. This feature
 271      *             will be removed.
 272      */
 273     @Deprecated
 274     public Vector<String> getVectorEndpointAddresses() {
 275         return endpointAddresses;
 276     }
 277
 278     /**
 279      * Sets the list of endpoint addresses associated with this access point.
 280      *
 281      * @param addresses Vector of EndpointAddresses represented as
 282      *                  {@link java.lang.String}. <b>The Vector is not copied!</b>
 283      * @deprecated This method causes the AccessPointAdvertisement to reference
 284      *             the provided array. This means that subsequent changes to the array will
 285      *             alter the endpoint addresses which are part of the
 286      *             {@code AcccessPointAdvertisement}.
 287      */
 288     @Deprecated
 289     public void setEndpointAddresses(Vector<String> addresses) {
 290         endpointAddresses = addresses;
 291     }
 292
 293     /**
 294      * Add a new list of EndpointAddresses to the access point.
 295      *
 296      * @param addresses List of EndpointAddresses represented as
 297      *                  {@link java.lang.String}.
 298      *
 299      * @deprecated Use {@link #addEndpointAddresses(List)} instead.
 300      */
 301     @Deprecated
 302     public void addEndpointAddresses(Vector<String> addresses) {
 303         for (String toAdd : addresses) {
 304             addEndpointAddress(toAdd);
 305         }
 306     }
 307
 308     /**
 309      * Add a new EndpointAddresses to the access point
 310      *
 311      * @param address An EndpointAddress
 312      */
 313     public void addEndpointAddress(EndpointAddress address) {
 314         String toAdd = address.toString();
 315
 316         if (!endpointAddresses.contains(toAdd)) {
 317             endpointAddresses.add(toAdd);
 318         }
 319     }
 320
 321     /**
 322      * add a new EndpointAddresses to the access point
 323      *
 324      * @param address EndpointAddress represented as {@link java.lang.String}.
 325      */
 326     public void addEndpointAddress(String address) {
 327         if (!endpointAddresses.contains(address)) {
 328             endpointAddresses.add(address);
 329         }
 330     }
 331
 332     /**
 333      * remove a list of EndpointAddresses from the access point
 334      *
 335      * @param addresses List of EndpointAddresses represented as
 336      *                  {@link java.lang.String}.
 337      */
 338     public void removeEndpointAddresses(List<String> addresses) {
 339         endpointAddresses.removeAll(addresses);
 340     }
 341
 342     /**
 343      * return number of endpoint addresses
 344      *
 345      * @return size number of endpointAddress in the hop
 346      */
 347     public int size() {
 348         return endpointAddresses.size();
 349     }
 350
 351     /**
 352      * Check if the EndpointAddress is already associated with this access point
 353      *
 354      * @param addr endpoint address to check
 355      * @return true if the EndpointAddress is already associated with this access point
 356      */
 357     public boolean contains(EndpointAddress addr) {
 358         return endpointAddresses.contains(addr.toString());
 359     }
 360
 361     /**
 362      * Generate a string that displays an access point
 363      * information for logging or debugging purpose
 364      *
 365      * @return String return a string containing the access point advertisement
 366      */
 367     public String display() {
 368         StringBuilder routeBuf = new StringBuilder();
 369
 370         routeBuf.append("PID=");
 371
 372         PeerID peerId = getPeerID();
 373
 374         if (peerId == null) {
 375             routeBuf.append("<null>");
 376         } else {
 377             routeBuf.append(peerId.toString());
 378         }
 379
 380         Enumeration e = getEndpointAddresses();
 381
 382         while (e.hasMoreElements()) {
 383             routeBuf.append("\n Addr=").append(e.nextElement());
 384         }
 385         return routeBuf.toString();
 386     }
 387 }