Package jmri.jmrit.ctc

Class LockedRoute

  • public class LockedRoute
extends java.lang.Object
    Each of these objects describe a route consisting of all of the occupancy sensors(s) that specify a route. This is the "topology" information needed to determine if a route is available or not.

    For O.S. sections, this routine will get the reference to the "_mOSSectionOccupiedExternalSensor" associated with that O.S. section. For the occupancy sensors, just a reference to those occupancy sensors.

    It will register with the occupancy sensors for state change. As each occupancy sensor goes unoccupied (INACTIVE), it will subtract one from a counter of outstanding reservations. If the count becomes zero, it will remove from it's list that resource, thereby freeing it up for any other allocation in the future.

    This object is NOT multi-thread safe (nor does it need to be). I DO NOT (nor do I make any assumptions) about JMRI's threading as regards this objects design. It is "hardened" against multi-threading issues of ONLY this form: It is possible that while we are (say) adding a new route by merging it to an existing route, for an de-occupancy event to occur. If we didn't harden the object, then it is possible for an increment and decrement to occur "in parallel" thus screwing up the count. So whenever a merge or de-occupy event occurs, we lock down the object "CountedSensor" only as long as needed to get to a "safe" state.

    • Constructor Summary

      Constructors 
      Constructor Description
      LockedRoute​(LockedRoutesManager lockedRoutesManager, java.util.HashSet<Sensor> sensors, java.lang.String osSectionDescription, java.lang.String ruleDescription, boolean rightTraffic)  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void allocateRoute()
      This routine is ONLY called by the higher level if this is NOT a merged route, but a brand new route.
      LockedRoute.AnyInCommonReturn anyInCommon​(LockedRoute lockedRoute, boolean checkDirection, boolean rightTraffic)
      Checks the sensors passed in as object type "LockedRoute" against the sensors in this object.
      java.lang.String dumpRoute()
      Simple routine to return in a string all information on this route.
      java.util.HashSet<jmri.jmrit.ctc.LockedRoute.CountedSensor> getCountedSensors()  
      java.util.HashSet<Sensor> getSensors()  
      void mergeRoutes​(LockedRoute newLockedRoute)
      The higher level called us to merge "newLockedRoute" sensors into "this" object.
      void removeAllListeners()
      Simple routine to remove all listeners that were registered to each of our counted sensors.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • LockedRoute

        public LockedRoute​(LockedRoutesManager lockedRoutesManager,
                   java.util.HashSet<Sensor> sensors,
                   java.lang.String osSectionDescription,
                   java.lang.String ruleDescription,
                   boolean rightTraffic)

    • Method Detail

      • getCountedSensors

        public java.util.HashSet<jmri.jmrit.ctc.LockedRoute.CountedSensor> getCountedSensors()

      • allocateRoute

        public void allocateRoute()
        This routine is ONLY called by the higher level if this is NOT a merged route, but a brand new route.

        Once the higher level has determined that this route is valid and available, then finish the process here. Here we register occupancy changes for all sensors, and as they report "unoccupied", we prune that entry from our set, thereby releasing that segment to the rest of the system. See "occupancyStateChange".

      • mergeRoutes

        public void mergeRoutes​(LockedRoute newLockedRoute)
        The higher level called us to merge "newLockedRoute" sensors into "this" object. "newLockedRoute" has had NOTHING done to it other than construct it. We iterate the sensors in it, and if there is a match in our sensor list just increment the count, otherwise register a property change on the new added sensor.

        After this, "newLockedRoute" is not needed for anything.

        NOTE: The higher level routines saved a copy of "this" object somewhere, so that when Signals Normal (all stop) is ever selected by the Dispatcher, we can delete this entire object easily. Ergo, we MUST merge the newLockedRoute into "this", NOT the other way around. Besides, merge to "this" is easier anyways.....

        Parameters:
        newLockedRoute - New route that needs to be merged to "this".

      • anyInCommon

        public LockedRoute.AnyInCommonReturn anyInCommon​(LockedRoute lockedRoute,
                                                 boolean checkDirection,
                                                 boolean rightTraffic)
        Checks the sensors passed in as object type "LockedRoute" against the sensors in this object. Support Fleeting requests.
        Parameters:
        lockedRoute - Existing LockedRoute to check against.
        checkDirection - Pass false if this is a turnout resource request, else pass true to check traffic direction.
        rightTraffic - If right traffic was requested pass true, else false for left traffic.
        Returns:
        AnyInCommonReturn enum value. NONE = Nothing matches at all, YES = Absolute overlap, FLEETING = Overlap, but direction matches.

      • removeAllListeners

        public void removeAllListeners()
        Simple routine to remove all listeners that were registered to each of our counted sensors.

      • dumpRoute

        public java.lang.String dumpRoute()
        Simple routine to return in a string all information on this route.
        Returns:
        Dump of routes information in returned string. No specific format. See code in routine.