contrib/psg/src/peersim/core/Linkable.java

   1 /*
   2  * Copyright (c) 2003-2005 The BISON Project
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU Lesser General Public License version 2 as
   6  * published by the Free Software Foundation.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11  * GNU Lesser General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU Lesser General Public License
  14  * along with this program; if not, write to the Free Software
  15  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  16  *
  17  */
  18
  19 package peersim.core;
  20
  21
  22 /**
  23 * Instances of classes implementing this interface can form networks (graphs)
  24 * in the simulator framework.
  25 * The interface is similar to one of a container (containing neighbors),
  26 * only the types of the contained elements have to be {@link Node}.
  27 * The neighbor collection is defined in a random access list style, but
  28 * it must follow the contract of a set too (elements must be unique).
  29 * <p>
  30 * Also note that there is no possibility to remove elements from the
  31 * neighbor set. This is because removal is usually costly and it does not make
  32 * sense in the context of our applications,
  33 * where this interface is used for 1) initialization and 2)
  34 * providing an interface for other protocols for accessing the neighbor list.
  35 * Protocols that manage links remove, refresh, etc their link set internally
  36 * or through custom methods.
  37 * Therefore it would only put an unnecessary burden on implementors.
  38 */
  39 public interface Linkable extends Cleanable {
  40
  41
  42         /**
  43         * Returns the size of the neighbor list.
  44         */
  45         public int degree();
  46
  47         /**
  48         * Returns the neighbor with the given index. The contract is that
  49         * listing the elements from index 0 to index degree()-1 should list
  50         * each element exactly once if this object is not modified in the
  51         * meantime. It throws an IndexOutOfBounds exception if i is negative
  52         * or larger than or equal to {@link #degree}.
  53         */
  54         public Node getNeighbor(int i);
  55
  56         /**
  57         * Add a neighbor to the current set of neighbors. If neighbor
  58         * is not yet a neighbor but it cannot be added from other reasons,
  59         * this method should not return normally, that is, it must throw
  60         * a runtime exception.
  61         * @return true if the neighbor has been inserted; false if the
  62         *    node is already a neighbor of this node
  63         */
  64         public boolean addNeighbor(Node neighbour);
  65
  66         /**
  67         * Returns true if the given node is a member of the neighbor set.
  68         */
  69         public boolean contains(Node neighbor);
  70
  71         /**
  72         * A possibility for optimization. An implementation should try to
  73         * compress its internal representation. Normally this is called
  74         * by initializers or other components when
  75         * no increase in the expected size of the neighborhood can be
  76         * expected.
  77         */
  78         public void pack();
  79 }
  80