Package jsl.modeling.elements.spatial

Class AbstractMover

  • All Implemented Interfaces:
    MoverIfc, PositionIfc, SpatialElementIfc, VelocityIfc, ObservableIfc, GetNameIfc, IdentityIfc
    Direct Known Subclasses:
    AbstractRG2DMover, Mover, RandomMover, Transporter
    public abstract class AbstractMover
extends SpatialModelElement
implements MoverIfc, VelocityIfc
    An AbstractMover implements the MoverIfc and is a model element (SpatialModelElement). It represents an object that can move through a spatial model. It can begin a trip and make movements towards the destination associated with the trip. Each trip can be broken up into a series of movements. Each movement can have a different length and velocity as long as the object eventually completes the trip. It has default behaviors that can be modified by some helper classes. A MovementControllerIfc can be supplied to control the movement within a trip. If a movement controller is supplied, it is responsible for setting the velocity associated with movements. A CollisionDetectorIfc can be supplied to detect collisions while moving. A CollisionHandlerIfc can be supplied to handle (react) to collisions detected while moving A OutsideSpatialModelHandlerIfc can be supplied to handle the situation if the the object attempts to go outside the valid frame of reference associated with its spatial model.

    • Field Detail

      • TRIP_STARTED

        public static final int TRIP_STARTED
        Indicates that a AbstractMover started a trip

      • TRIP_ENDED

        public static final int TRIP_ENDED
        Indicates that a AbstractMover ended a trip

      • TRIP_CANCELED

        public static final int TRIP_CANCELED
        Indicates that a AbstractMover had its trip canceled

      • MOVE_STARTED

        public static final int MOVE_STARTED
        Indicates that a AbstractMover started a movement

      • MOVE_ENDED

        public static final int MOVE_ENDED
        Indicates that a AbstractMover ended a movement

      • myMovementController

        protected MovementControllerIfc myMovementController
        Controls the movement of this element

      • myCollisionHandler

        protected CollisionHandlerIfc myCollisionHandler
        Handles the occurs of collisions

      • myCollisionDetector

        protected CollisionDetectorIfc myCollisionDetector
        Detects the occurrence of collisions

      • mySEDestination

        protected SpatialElementIfc mySEDestination
        Holds the spatial element of the destination for the current trip (movement) if given

      • myTripCounter

        protected Counter myTripCounter
        Used to count the number of trips completed by the mover

      • myTripDist

        protected ResponseVariable myTripDist
        Used to record the distance of each trip made

      • myTotalTripDist

        protected ResponseVariable myTotalTripDist
        Used to record the total distance of all trips

    • Constructor Detail

      • AbstractMover

        public AbstractMover​(ModelElement parent)
        Creates a AbstractMover with the default position within its spatial model. The spatial model of the parent is used as the spatial model of this object. If the parent does not have a spatial model (i.e. getSpatialModel() == null), then an IllegalArgumentException is thrown
        Parameters:
        parent -

      • AbstractMover

        public AbstractMover​(ModelElement parent,
                     java.lang.String name)
        Creates a AbstractMover with the default position within its spatial model. The spatial model of the parent is used as the spatial model of this object. If the parent does not have a spatial model (i.e. getSpatialModel() == null), then an IllegalArgumentException is thrown
        Parameters:
        parent -
        name -

      • AbstractMover

        public AbstractMover​(ModelElement parent,
                     CoordinateIfc coordinate)
        Creates a AbstractMover at the supplied coordinate within its spatial model. The spatial model of the parent is used as the spatial model of this object. If the parent does not have a spatial model (i.e. getSpatialModel() == null), then an IllegalArgumentException is thrown
        Parameters:
        parent -
        coordinate -

      • AbstractMover

        public AbstractMover​(ModelElement parent,
                     SpatialElementIfc element)
        Creates a AbstractMover at the same coordinates as the supplied SpatialElementIfc within its spatial model. The spatial model of the parent is used as the spatial model of this object. If the parent does not have a spatial model (i.e. getSpatialModel() == null), then an IllegalArgumentException is thrown
        Parameters:
        parent -
        element -

      • AbstractMover

        public AbstractMover​(ModelElement parent,
                     SpatialElementIfc element,
                     java.lang.String name)
        Creates a AbstractMover at the same coordinates as the supplied SpatialElementIfc within its spatial model. The spatial model of the parent is used as the spatial model of this object. If the parent does not have a spatial model (i.e. getSpatialModel() == null), then an IllegalArgumentException is thrown
        Parameters:
        parent -
        element -
        name -

      • AbstractMover

        public AbstractMover​(ModelElement parent,
                     java.lang.String name,
                     SpatialModel spatialModel)
        Creates a AbstractMover with the default position within the given spatial model. If the supplied spatial model is null the spatial model of the parent is used as the spatial model of this object. If the parent does not have a spatial model (i.e. getSpatialModel() == null), then an IllegalArgumentException is thrown
        Parameters:
        parent -
        name -
        spatialModel -

      • AbstractMover

        public AbstractMover​(ModelElement parent,
                     SpatialModel spatialModel)
        Creates a AbstractMover with the default position within the given spatial model. If the supplied spatial model is null the spatial model of the parent is used as the spatial model of this object. If the parent does not have a spatial model (i.e. getSpatialModel() == null), then an IllegalArgumentException is thrown
        Parameters:
        parent -
        spatialModel -

      • AbstractMover

        public AbstractMover​(ModelElement parent,
                     java.lang.String name,
                     SpatialModel spatialModel,
                     CoordinateIfc coordinate)
        Creates a AbstractMover at the supplied coordinates within the given spatial model. If the supplied spatial model is null the spatial model of the parent is used as the spatial model of this object. If the parent does not have a spatial model (i.e. getSpatialModel() == null), then an IllegalArgumentException is thrown
        Parameters:
        parent -
        name -
        spatialModel -
        coordinate - Must be valid for the spatial model

    • Method Detail

      • turnOnTripStatistics

        public void turnOnTripStatistics()
        Turns on trip statistical collection. Once it is on. It is on.

      • isTripStatOptionOn

        public final boolean isTripStatOptionOn()
        Returns:
        true means on, false means off

      • initialize

        protected void initialize()
        Description copied from class: ModelElement
        This method should be overridden by subclasses that need actions performed to initialize prior to a replication. It is called once before each replication occurs if the model element wants initialization. It is called after beforeReplication() is called
        Overrides:
        initialize in class SpatialModelElement

      • replicationEnded

        protected void replicationEnded()
        Description copied from class: ModelElement
        This method should be overridden by subclasses that need actions performed when the replication ends and prior to the calling of afterReplication() . It is called when each replication ends and can be used to collect data from the the model element, etc.
        Overrides:
        replicationEnded in class ModelElement

      • setMaxNumTrips

        public final void setMaxNumTrips​(int maxTrips)
        Sets the number of trips that will trigger the end of the replication
        Parameters:
        maxTrips - the desired limit

      • getMaxNumTrips

        public long getMaxNumTrips()
        Gets the number of trips that will trigger the end of the replication
        Returns:
        the limit

      • getNumTripsCompleted

        public double getNumTripsCompleted()
        Returns:
        the number of trips completed by the mover

      • isDefaultNextTripOptionOn

        public final boolean isDefaultNextTripOptionOn()
        Controls whether or not to automatically start a new trip via startNextTrip()
        Returns:
        true if the option is on

      • setDefaultNextTripOption

        public final void setDefaultNextTripOption​(boolean defaultNextTripFlag)
        Controls whether or not to automatically start a new trip via startNextTrip()
        Parameters:
        defaultNextTripFlag - true means on

      • cancelTrip

        public final void cancelTrip()
        If the mover is on a trip then the movement along the trip is canceled and the mover stays at the position where it is when this method is called. This method cancels movement. If the mover is not moving or on a trip nothing happens.
        Specified by:
        cancelTrip in interface MoverIfc

      • getFuturePosition

        public final CoordinateIfc getFuturePosition​(double time)
        Description copied from interface: MoverIfc
        Returns a CoordinateIfc that represents the future position of the spatial element at the given time.
        Specified by:
        getFuturePosition in interface MoverIfc
        Parameters:
        time - Must be greater than or equal to zero
        Returns:
        the coordinate of the future position

      • isMoving

        public final boolean isMoving()
        Description copied from interface: MoverIfc
        Indicates whether or not the element is currently moving
        Specified by:
        isMoving in interface MoverIfc
        Returns:
        true if moving

      • isOnTrip

        public final boolean isOnTrip()
        Description copied from interface: MoverIfc
        Indicates whether or not the element is currently on a trip
        Specified by:
        isOnTrip in interface MoverIfc
        Returns:
        true if on a trip

      • getMovementDistance

        public final double getMovementDistance()
        Description copied from interface: MoverIfc
        Gets the distance associated with the current movement
        Specified by:
        getMovementDistance in interface MoverIfc
        Returns:
        Returns the movementDistance.

      • getMovementTime

        public final double getMovementTime()
        Description copied from interface: MoverIfc
        Gets the time length for the current movement
        Specified by:
        getMovementTime in interface MoverIfc
        Returns:
        Returns the movementTime

      • getMovementStartTime

        public final double getMovementStartTime()
        Description copied from interface: MoverIfc
        Get the time that the current movement started
        Specified by:
        getMovementStartTime in interface MoverIfc
        Returns:
        Returns the movementStartTime.

      • getMovementVelocity

        public final double getMovementVelocity()
        Description copied from interface: MoverIfc
        Gets the velocity of the movement that is in progress
        Specified by:
        getMovementVelocity in interface MoverIfc
        Returns:
        Returns the movementVelocity.

      • setCollisionDetector

        public final void setCollisionDetector​(CollisionDetectorIfc collisionDetector)
        Description copied from interface: MoverIfc
        Sets the collision detector. If null no detection is used
        Specified by:
        setCollisionDetector in interface MoverIfc
        Parameters:
        collisionDetector - The collisionDetector to set.

      • setCollisionHandler

        public final void setCollisionHandler​(CollisionHandlerIfc collisionHandler)
        Description copied from interface: MoverIfc
        Sets the collision handler, if null then no collision handling is performed
        Specified by:
        setCollisionHandler in interface MoverIfc
        Parameters:
        collisionHandler - The collisionHandler to set.

      • setMovementController

        public final void setMovementController​(MovementControllerIfc movementController)
        Description copied from interface: MoverIfc
        Set the movement controller. If null, then the default movement uses the point to point distance at velocity 1.
        Specified by:
        setMovementController in interface MoverIfc
        Parameters:
        movementController - The movementController to set.

      • setVelocityChangeFactor

        public final void setVelocityChangeFactor​(double factor)
        Description copied from interface: VelocityIfc
        The addFactor will be used to increase or decrease the velocity returned by getVelocity()
        Specified by:
        setVelocityChangeFactor in interface VelocityIfc
        Parameters:
        factor - must be greater than zero

      • getVelocityChangeFactor

        public final double getVelocityChangeFactor()
        Description copied from interface: VelocityIfc
        The addFactor will be used to increase or decrease the velocity returned by getVelocity()
        Specified by:
        getVelocityChangeFactor in interface VelocityIfc
        Returns:
        the addFactor

      • setVelocityRandomSource

        public void setVelocityRandomSource​(RandomIfc source)
        Description copied from interface: MoverIfc
        Sets the random source associated with the velocity. This is reset at the beginning of each replication to the value set with setVelocityInitialRandomSource()
        Specified by:
        setVelocityRandomSource in interface MoverIfc
        Specified by:
        setVelocityRandomSource in interface VelocityIfc
        Parameters:
        source - the source of the randomness

      • getOSMHandler

        public final OutsideSpatialModelHandlerIfc getOSMHandler()
        Description copied from interface: MoverIfc
        Get the object the handles when the movement takes the element outside the boundaries of the current spatial model
        Specified by:
        getOSMHandler in interface MoverIfc
        Returns:
        Returns the OSMHandler.

      • setOSMHandler

        public final void setOSMHandler​(OutsideSpatialModelHandlerIfc OSMHandler)
        Description copied from interface: MoverIfc
        Set the handler for taking care of when the element goes outside the boundaries of its spatial model. If null, then an exception will be thrown if the element tries to go outside its spatial element.
        Specified by:
        setOSMHandler in interface MoverIfc
        Parameters:
        OSMHandler - The OSMHandler to set.

      • setMovement

        public final void setMovement​(double velocity,
                              CoordinateIfc position)
        Description copied from interface: MoverIfc
        Sets up the movement before it gets processed. Takes in a velocity for the movement (which must be > 0) and the coordinate where the movement should end. This method should be used by MovementControllers to set the movement characteristics prior to the move. This method sets: 1) the velocity of the move 2) the distance of the move 3) the direction of the move 4) the time the move starts 5) the total time to move to the position at the given velocity
        Specified by:
        setMovement in interface MoverIfc
        Parameters:
        velocity - Must be > 0
        position - Must not be null

      • asString

        public java.lang.String asString()
        Description copied from class: ModelElement
        Allows sub-classes to provide more detail than toString() to represent the ModelElement as a String
        Overrides:
        asString in class ModelElement
        Returns:
        a detailed String representation

      • getDestination

        public CoordinateIfc getDestination()
        Description copied from interface: MoverIfc
        Gets a reference to the CoordinateIfc representing the destination of the mover
        Specified by:
        getDestination in interface MoverIfc
        Returns:
        the CoordinateIfcIfc for this element

      • moveTo

        protected final void moveTo​(CoordinateIfc destination)
        Causes the element to start a trip from its current position to the coordinates specified. This starts a trip. A trip is a series of movements to move from the current position to the specified coordinates. At the beginning of a trip, trip start observers are notified. If the trip is broken down into movements, then each movement can have its own velocity, distance, and direction (as long as the final movement ends at the destination). If the destination is the same as the current position of the element then no trip is started and no movement occurs, i.e. nothing occurs If the specified coordinates are not in the element's associated spatial model then outsideSpatialModelHandler() is called. The default action is to throw an exception but this can be overridden in outsideSpatialModelHandler().
        Parameters:
        destination - the coordinate of the destination

      • moveTo

        protected final void moveTo​(SpatialElementIfc destination)
        Causes the element to start a trip to the coordinates of the specified SpatialElementIfc
        Parameters:
        destination - the coordinate of the destination

      • moveDeltaX1

        protected final void moveDeltaX1​(double dx)
        Relative to the current position this method causes the mover to start a trip delta in the x1 direction
        Parameters:
        dx - the amount of the move

      • moveDeltaX2

        protected final void moveDeltaX2​(double dy)
        Relative to the current position this method causes the mover to start a trip delta in the x2 direction
        Parameters:
        dy - the amount of the move

      • moveDeltaX1X2

        protected final void moveDeltaX1X2​(double dx,
                                   double dy)
        Relative to the current position this method causes the mover to start a trip to a position that is delta in the x1 direction and delta in the x2 direction.
        Parameters:
        dx - amount of change in the X1 direction
        dy - amount of change in the X2 direction

      • beforeTripStarts

        protected void beforeTripStarts()
        Can be used by subclasses to invoke logic prior to the start of a trip

      • afterTripEnds

        protected void afterTripEnds()
        Can be used by subclasses to invoke logic after a trip ends

      • hasNextTrip

        public boolean hasNextTrip()
        A method to determine if another trip should be started This result controls whether or not startNextTrip() is called. By default, it returns false. Implementors can override to provide trips via startNextTrip()
        Returns:
        true if another trip should be started, false otherwise

      • startNextTrip

        protected void startNextTrip()
        Should be used by subclasses to initiate (schedule) the next trip after ending the current trip. This is called immediately after afterTripEnds() if and only if hasNextTrip() returns true

      • beforeMovementStarts

        protected void beforeMovementStarts()
        Can be used by subclasses to invoke logic prior to the start of a movement

      • afterMovementEnds

        protected void afterMovementEnds()
        Can be used by subclasses to invoke logic after a movement ends

      • tripCanceled

        protected void tripCanceled()
        Can be used by subclasses to invoke logic when a trip is canceled

      • collectTripStats

        protected void collectTripStats()
        A method that can be overridden to collect statistics after a trip is completed, called right before afterTripEnds(). The statistical collection must be turned on via turnOnTripStatistics() for this method to be called.

      • outsideSpatialModelHandler

        protected void outsideSpatialModelHandler​(CoordinateIfc coordinate)
        This method is called if the destination is outside of the element's current spatial model. By default it throws an IllegalArgumentException unless the user supplies an object that implements the OutsideSpatialModelHandlerIfc. Alternatively subclasses can override this method and provide the behavior directly
        Parameters:
        coordinate - the coordinate

      • updatePosition

        protected void updatePosition()
        This method is called at the end of a movement to update the position. The setCurrentPosition() method is used to set the current position to the next position attribute Overriding methods can specify other ways to set the position as long as they are consistent with the process implemented for the movements.

      • computeMovement

        protected void computeMovement()
        This method can be overridden by subclasses to compute the characteristics of a movement. Alternatively the user can supply an object that implements the MovementControllerIfc By default the movement goes directly to the destination at the default mover velocity. It is important that subclasses utilize the setMovement() method to properly set the characteristics of the movement.

      • checkForCollision

        protected boolean checkForCollision()
        This method can be overridden by subclasses to provide collision detection. Alternatively the user can supply an object that implements the CollisionDetectorIfc By default there is no collision detection. When there is no collision detector this method always returns false.
        Returns:
        False if no collision, true if collided

      • handleCollision

        protected void handleCollision()
        This method can be overridden by subclasses to provide collision handling. Alternatively the user can supply an object that implements the CollisionHandlerIfc By default there is no collision handling.