routerqueue.java

JAVA版的蚂蚁算法(Ant Colony Optimization Algorithms)

package dk.itu.nulx30.networkModel;

import dk.itu.nulx30.networkModel.exceptions.IllegalQueueCapacityException;
import dk.itu.nulx30.networkModel.exceptions.RouterQueueEmptyException;
import dk.itu.nulx30.networkModel.exceptions.RouterQueueFullException;

/**
 * Class RouterQueue represents the buffers used by the routers in the network.
 * An outputQueue contains a reference to the <code>Wire</code> object that
 * it uses to send packages over. An input Queue contains no reference to a Wire
 * object but is implicitly connected to all incomming wires.
 * A <code>RouterQueue</code> has a <code>maxCacity</code> that indicates how
 * many packages it can buffer. When a RouterQueue is full and an attempt
 * to insert a package into that RouterQueue is performed, the RouterQueue
 * throws a <code>RouterQueueFullException</code>
 * A RouterQueue contains no references to <code>NetworkPackage</code> objects,
 * merely a counter that keeps track of how many packages are currently in the
 * queue.
 * 
 * @author Mikkel Bundgaard
 * @author Troels C. Damgaard
 * @author Federico Decara
 * @author Jacob Wahl Winther
 */
public class RouterQueue {
  /** Maximum capacity of this queue*/
  private int maxCapacity;
  /** Current capacity of this queue, cannot be externaly modified*/
  private int currentCapacity;
  /**
   * The router that uses this RouterQueue, once this is set, it cannot be
   * modified.
   */
  private Router usedBy;

  /**
   * The <code>Wire</code> that contains the reference to the target Router
   * once this is set, it cannot be modified.
   * A <code>null</code> value indicates that this RouterQueue is an inputQueue
   */
  private Wire wire;

  /**
   * Class constructor for constructing a RouterQueue used as an outputQueue
   *
   * @param r   The router that uses this <code>RouterQueue</code>
   * @param w   The wire this <code>RouterQueue</code> uses.
   * @param mc  The maximum capacity of <code>RouterQueue</code>
   */
  public RouterQueue( Router r, Wire w, int mc) {
    maxCapacity = mc;
    usedBy = r;
    wire = w;
  }

  /**
   * Class constructor for constructing a RouterQueue used as an inputQueue
   *
   * @param r   The router that uses this <code>RouterQueue</code>
   * @param mc  The maximum capacity of <code>RouterQueue</code>
   */
  public RouterQueue( Router r, int mc ) {
    this( r, null, mc ); 
  }

  /**
   * Returns the index of the target router, connected to the <code>Wire</code>
   * object
   *
   * @return null if RouterQueue is a inputQueue else the index of the target Router
   */
  public int getTargetIndex() {
    return wire.getTarget().getIndex();
  }

  /**
   * Returns the wire that is used by RouterQueue
   *
   * @return reference to Wire object used by RouterQueue.
   */
  public Wire getWire() {
    return wire;
  }

  /**
   * Return the index of the router which <code>this</code> RouterQueue is
   * used by.
   *
   * @return the index of the router which this RouterQueue is used by
   */
  public int getRouterIndex() {
    return usedBy.getIndex();
  }

  /**
   * Returns the maximum capacity of this <code>RouterQueue</code>
   *
   * @return integer value that represents the maximum capacity of
   * <code>RouterQueue</code>
   */
  public int getMaxCapacity() {
    return maxCapacity;
  }

  /**
   * Returns the delay of this <code>RouterQueue</code>
   *
   * @return the delay of this <code>RouterQueue</code>
   */
  public double getDelay() {
    if ( wire != null ) { // this is an outputqueue
      return wire.getDelay() * currentCapacity;
    }
    else {// this is an inputqueue
      return usedBy.getDelay() * currentCapacity;
    }
  }

  /**
   * Returns the capacity of this <code>RouterQueue</code>
   *
   * @return the capacity of this <code>RouterQueue</code>
   */
  public int getCurrentCapacity() {
    return currentCapacity;
  }

  /**
   * Set the maximum capacity of the <code>routerQueue</code>
   *
   * @param     newMaxCapacity the new maximum capacity for RouterQueue
   *
   * @exception IllegalQueueCapacityException thrown if newMaxCapacity is
   * smaller than currentCapacity, since this results in a undefined package
   * loss
   */
  public void setMaxCapacity( int newMaxCapacity )
                                          throws IllegalQueueCapacityException {
    if ( newMaxCapacity < currentCapacity ) {
      throw new IllegalQueueCapacityException( "RouterQueue used by " +
        usedBy.getIndex() +
        " was assigned a maximum value that is smaller than the current value." );
    }
    maxCapacity = newMaxCapacity;
  }

  /**
   * Adds a package to the <code>RouterQueue</code>.
   *
   * @exception RouterQueueFullException a <code>RouterQueueFullException</code>
   *            is thrown if the queue is full
   */
  public void addPackage() throws RouterQueueFullException {
    if ( currentCapacity == maxCapacity ) {
      if ( wire == null ) { // This is a input queue
        throw new RouterQueueFullException( "Input RouterQueue in router: " +
          usedBy.getIndex() + "was full and package was lost" );
      }
      else {
        throw new RouterQueueFullException( "Output RouterQueue in router: " +
          usedBy.getIndex() + "connecting to " + wire.getTarget().getIndex() +
          "was full and package was lost" );
      }
    }
    currentCapacity++;
  }

  /**
   * Removes a package from the <code>RouterQueue</code>.
   *
   * @exception RouterQueueEmptyException <code>RouterQueueEmptyException</code>
   *            is thrown if the queue is empty.
   */
  public void removePackage() throws RouterQueueEmptyException {
    if ( currentCapacity == 0 ) {
      throw new RouterQueueEmptyException( "Package could not be removed from "
                + getRouterIndex() );
    }
    currentCapacity--;
  }

  /**
   * Returns <code>true</code> if the queue's capacity is full otherwise
   * <code>false</code>.
   *
   * @return <code>true</code> if the queue's capacity is full otherwise false.
   */
  public boolean isFull() {
    return ( currentCapacity == maxCapacity );
  }
}