Class Hub

All Implemented Interfaces:
CondObserver<Condition,Actor>, NamedObjectOps
Direct Known Subclasses:
StorageHub

public class Hub extends Actor
Class modeling a hub. Hubs contain a bicycle-storage area, called the preferred area, with a fixed capacity, and cover a geographic area. There is also a second area called the overflow area. When the preferred area is filled to capacity, new arrivals go to the overflow area. New arrivals may, however, go the overflow area at any time: it represents the immediate vicinity of the preferred area an thus users may go directly to the overflow area as it may be slightly closer to the actual destination.

In addition, workers (instances of HubWorker), may move bicycles from one hub to another. There are several values that control the behavior of workers:

  • the capacity of the hub's preferred area.
  • the lower trigger for the hub.
  • the nominal value for the hub.
  • the upper trigger for the hub.
  • the number of bicycles stored in the preferred area.
  • the number of bicycles stored in the overflow area.
  • a random variable giving the time it takes for a worker to pick up one bicycle from the overflow area.

Finally, each hub has an (X,Y) coordinate and is a member of a user domain and a system domain. Hubs are configured by the method init. There are two listeners that may be added to a hub:

  • HubListener. This is handled automatically for listeners used to notify instances of HubCondition of a change.
  • HubDataListener. This is intended to be used for instrumenting a simulation.
The methods that modify the state of a hub due to users or workers are: The method sendUsers(Hub,int,boolean,Callable) or sendUsers(Hub,int,boolean,RealValuedFunctionTwo,Callable), however, can be used as a higher-level interface for user operations.
  • Field Details

    • bikeCount

      protected int bikeCount
      The bicycle count.
    • overflow

      protected int overflow
      The overflow count.
  • Constructor Details

    • Hub

      public Hub(DramaSimulation sim, String name, boolean intern)
      Constructor.
      Parameters:
      sim - the simulation
      name - the name of this object
      intern - true if this object should be interned in the simulation's name table; false otherwise
  • Method Details

    • getUsrDomain

      public UsrDomain getUsrDomain()
      Get the user domain for this hub.
      Returns:
      this hub's user domain
    • getSysDomain

      public SysDomain getSysDomain()
      Get the system domain for this hub.
      Returns:
      this hub's system domain
    • getX

      public double getX()
      Get this object's X coordinate.
      Returns:
      the X coordinate in units of meters
    • getY

      public double getY()
      Get this object's Y coordinate.
      Returns:
      the Y coordinate in units of meters
    • addHubListener

      public void addHubListener(HubListener listener)
      Add a hub listener to the current object.
      Parameters:
      listener - the listener to add
    • removeHubListener

      public void removeHubListener(HubListener listener)
      Remove a hub listener from the current object.
      Parameters:
      listener - the listener to remove
    • fireHubListeners

      protected void fireHubListeners(int need, int excess, int overflow)
      Notify each hub listener of a change.
      Parameters:
      need - the number of stored bicycles needed to reach this hub's lower trigger
      excess - the number of stored bicycles that have to be removed to reach this hub's upper trigger
      overflow - the number of bicycles stored elsewhere in the this hub
    • addHubDataListener

      public void addHubDataListener(HubDataListener listener)
      Add a hub data listener to the current object.
      Parameters:
      listener - the listener to add
    • removeHubDataListener

      public void removeHubDataListener(HubDataListener listener)
      Remove a hub data listener from the current object.
      Parameters:
      listener - the listener to remove
    • fireHubDataListeners

      protected void fireHubDataListeners(int bikeCount, boolean newBikeCount, int overflowCount, boolean newOverflowCount)
      Notify each hub listener of a change.
      Parameters:
      bikeCount - the new bike count
      newBikeCount - true if the bicycle count has changed during the event that invoked this listener; false otherwise
      overflowCount - the new overflow count
      newOverflowCount - true if the overflow count has changed during the event that invoked this listener; false otherwise
    • init

      public void init(int capacity, int lowerTrigger, int nominal, int upperTrigger, DoubleRandomVariable pickupTime, int count, int overCount, double x, double y, UsrDomain usrDomain, SysDomain sysDomain)
      Initialize this object. Each instance of this object has a preferred location at a specified coordinate with a fixed capacity. The hub allows bicycles to be stored at the preferred location and at other locations in the hub, called the "overflow" area. Users may choose to use the overflow area , but will be assigned to the overflow area when the preferred location is at capacity.

      At the preferred location, there is a nominal value for the number of bicycles and an upper and lower trigger. The nominal value represents the ideal number of bicycles at this hub's preferred location. For values for the number of bicycles at the preferred location that are less extreme than the upper and lower triggers or equal to those values, nothing special is done. Otherwise additional resources may be used to help restore the number of bicycles to a value between the two triggers, and as close to the nominal value as possible.

      Each hub has an X and Y coordinate for its preferred location. These coordinates are used to estimate travel time between two locations when an explicit value is not available, but are available for other purposes (e.g., graphics). Each hub also will be a member of two domains: a user domain and a system domain. The user domain contains only hubs provided for users, and can calculate the time needed to move from one hub to another when traveling by bicycle. By contrast, the system domain contains both hubs provided for users and hubs used to store vehicles used by workers to balance the distribution of bicycles between hubs. The system domain provides the time needed for workers to move between hubs using these vehicles.

      Parameters:
      capacity - a non-negative integer giving the capacity for this hub (the number of bicycles that can be stored at the hub's preferred location)
      lowerTrigger - the lower trigger for the number of bicycles at the preferred location
      nominal - the preferred number of bicycles at this hub's preferred location
      upperTrigger - the upper trigger for the number of bicycles at the preferred location
      pickupTime - a random variable providing the time it takes to pick up a bicycle that is at this hub but not at the hub's preferred location
      count - the initial number of bicycles stored at the preferred location of this hub
      overCount - the initial number of bicycles that are stored at this hub but not at this hub's preferred location
      x - the X value in meters of the preferred location for this hub
      y - the Y value in meters of the preferred location for this hub
      usrDomain - the user domain for this hub
      sysDomain - the system domain for his hub
    • needBikes

      public int needBikes()
      Get the number of bicycles needed to raise the number of bicycles stored at a hub's preferred location to the lower-trigger value.
      Returns:
      the number of bicycles needed to raise the number of bicycles stored at a hub's preferred location to the lower-trigger value; zero if no rebalancing is necessary
    • excessBikes

      public int excessBikes()
      Get the number of bicycles that must be removed from the hub's preferred location to reduce that number to the upper-trigger value.
      Returns:
      the number of bicycles that must be removed from the hub's preferred location to reduce that number to the upper-trigger value; zero if no rebalancing is necessary
    • getInitialBikeCount

      public int getInitialBikeCount()
      Get the initial bicycle count at the preferred location.
      Returns:
      the initial bicycle count at the preferred location
    • getBikeCount

      public int getBikeCount()
      Get the current bicycle count at the preferred location.
      Returns:
      the current bicycle count at the preferred location
    • getCapacity

      public int getCapacity()
      Get the capacity at the preferred location. The capacity is that maximum number of bicycles that can be stored at the preferred location of this hub.
      Returns:
      the capacity at the preferred location for this hub
    • getOverflow

      public int getOverflow()
      Get the number of bicycles in a hub's overflow area.
      Returns:
      the number of bicycles in this hub's overflow area
    • getNominal

      public int getNominal()
      Get the nominal value for the number of bicycles that are stored at a hub's preferred location. Load-balancing operations will try to adjust the number of bicycles at each hub to the nominal value for that hub.
      Returns:
      the nominal value for the number of bicycles that are stored at this hub's preferred location
    • getLowerTrigger

      public int getLowerTrigger()
      Get the lower trigger for the number of bicycles stored at a hub's preferred location. When the number of bicycles at the preferred location is smaller than this value, hub listeners will be notified.
      Returns:
      the lower trigger
    • getUpperTrigger

      public int getUpperTrigger()
      Get the upper trigger for the number of bicycles stored at a hub's preferred location. When the number of bicycles at the preferred location is larger than this value, hub listeners will be notified.
      Returns:
      the upper trigger
    • pickupOverflow

      public long pickupOverflow(int n) throws IllegalArgumentException
      Pickup bicycles from the overflow area. This method will reduce the count of bicycles in the overflow area for this hub.
      Parameters:
      n - the number of bicycles to remove from the overflow area
      Returns:
      the time it will take to pick up the specified number of bicycles
      Throws:
      IllegalArgumentException - the argument was larger than the number of bicycles in the overflow area or the argument was negative
    • decrBikeCount

      public int decrBikeCount(int decr)
      Decrement the number of bicycles at a hub's preferred location. The value returned may differ from the argument as the number of bicycles at the current location cannot be negative or larger then the hub's capacity.
      Parameters:
      decr - the decrement in the number of bicycles
      Returns:
      the number of bicycles actually removed from the preferred location
    • incrOverflow

      public void incrOverflow(int incr) throws IllegalArgumentException
      Increment the number of bicycles in the overflow area of a hub.
      Parameters:
      incr - the increment
      Throws:
      IllegalArgumentException - if the argument is negative
    • incrBikeCount

      public int incrBikeCount(int incr)
      Increment the number of bicycles at a hub's preferred location. The value returned may differ from the argument as the number of bicycles at the current location cannot be negative or larger then the hub's capacity.
      Parameters:
      incr - the increment in the number of bicycles
      Returns:
      the number of bicycles actually added to the preferred location
    • sendUsers

      public HubDomain sendUsers(Hub dest, int m, boolean willOverflow, Callable continuation) throws IllegalArgumentException
      Send users to another hub. If the requested or required number of bicycles is not available, no bicycles will be send.
      Parameters:
      dest - the hub to which bicycles should be sent
      m - the number of bicycles or users to send
      willOverflow - true if the destination hub must put the bicycles in the overflow area; false if the destination hub will put bicycles in the preferred area and use the overflow area only if the capacity would be exceeded
      continuation - code to call when the destination is reached
      Returns:
      the domain used to compute delays on success; null otherwise
      Throws:
      IllegalArgumentException - the second argument was negative.
    • sendUsers

      public HubDomain sendUsers(Hub dest, int m, boolean willOverflow, RealValuedFunctionTwo probFunction, Callable continuation) throws IllegalArgumentException
      Send users to another hub using a probability function. If the requested or required number of bicycles is not available, no bicycles will be send. The probability function is a real-valued function of two arguments and is used when the distance hub is a member of this hub's user domain and that domain's parent domain (provided it is also a hub domain). The first argument is the delay one obtains from the user domain and the second argument is the delay one obtains from the parent domain. The value that is returned is the probability of using the hub's user domain to determine delays. When the probability function is null, it is equivalent to a function whose value is 1.0 when the user domain's delay table estimated travel time is shorter and 0.0 otherwise.
      Parameters:
      dest - the hub to which bicycles should be sent
      m - the number of bicycles or users to send
      willOverflow - true if the destination hub must put the bicycles in the overflow area; false if the destination hub will put bicycles in the preferred area and use the overflow area only if the capacity would be exceeded
      probFunction - the probability function; null for the default behavior
      continuation - code to call when the destination is reached
      Returns:
      the domain used to compute delays on success; null otherwise
      Throws:
      IllegalArgumentException - the second argument was negative.
    • printConfiguration

      public void printConfiguration(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print the configuration for an instance of Hub. The documentation for method SimObject.printConfiguration(String,String,boolean,java.io.PrintWriter) contains a description of how this method is used and how to override it. The method GenericActor.printConfiguration(String,String,boolean,java.io.PrintWriter) describes the data that will be printed for the superclass of this class. The data that will be printed when this method is called are the following.

      For class Hub:

      • the X coordinate of this hub in meters.
      • the Y coordinate of this hub in meters.
      • the initial bicycle count.
      • the capacity of this hub.
      • the lower trigger for this hub.
      • the upper trigger for this hub.
      • the user domain for this hub.
      • the system domain for this hub.
      • the pickup time for this hub (the random variable that determines the time in seconds it takes to pickup a bicycle from the overflow area).
      Overrides:
      printConfiguration in class GenericActor<DramaSimulation,Actor,Condition,Domain,DomainMember,DramaFactory,Group>
      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • printState

      public void printState(String iPrefix, String prefix, boolean printName, PrintWriter out)
      Print the state for an instance of Hub. The documentation for method SimObject.printState(String,String,boolean,java.io.PrintWriter) contains a description of how this method is used and how to override it. The method GenericSimObject.printState(String,String,boolean,java.io.PrintWriter) describes the data that will be printed for the superclass of this class. The data that will be printed when this method is called are the following.

      For class Hub:

      • the bicycle count for this hub.
      • the count of the number of bicycles in the overflow area for this hub.
      Overrides:
      printState in class GenericSimObject<DramaSimulation,Actor,Condition,Domain,DomainMember,DramaFactory,Group>
      Parameters:
      iPrefix - the prefix to use for an initial line when printName is true with null treated as an empty string
      prefix - a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is true
      printName - requests printing the name of an object
      out - the output print writer
    • clone

      protected Object clone() throws CloneNotSupportedException
      Overrides:
      clone in class Object
      Throws:
      CloneNotSupportedException
    • isInterned

      public boolean isInterned()
      Specified by:
      isInterned in interface NamedObjectOps
    • getObjectNamer

      protected Simulation getObjectNamer()
    • getName

      public final String getName()
      Specified by:
      getName in interface NamedObjectOps
    • canDelete

      public boolean canDelete()
      Specified by:
      canDelete in interface NamedObjectOps
    • delete

      public final boolean delete()
      Specified by:
      delete in interface NamedObjectOps
    • isDeleted

      public final boolean isDeleted()
      Specified by:
      isDeleted in interface NamedObjectOps
    • deletePending

      public final boolean deletePending()
      Specified by:
      deletePending in interface NamedObjectOps