Source code

001package jmri.jmrit.logix;
002
003import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
004import java.awt.Color;
005import java.awt.Font;
006import java.beans.PropertyChangeListener;
007import java.util.*;
008import java.util.stream.Collectors;
009
010import javax.annotation.CheckForNull;
011import javax.annotation.Nonnull;
012
013import jmri.InstanceManager;
014import jmri.NamedBean;
015import jmri.NamedBeanHandle;
016import jmri.NamedBeanUsageReport;
017import jmri.Path;
018import jmri.Sensor;
019import jmri.Turnout;
020import jmri.util.ThreadingUtil;
021
022/**
023 * OBlock extends jmri.Block to be used in Logix Conditionals and Warrants. It
024 * is the smallest piece of track that can have occupancy detection. A better
025 * name would be Detection Circuit. However, an OBlock can be defined without an
026 * occupancy sensor and used to calculate routes.
027 * <p>
028 * Additional states are defined to indicate status of the track and trains to
029 * control panels. A jmri.Block has a PropertyChangeListener on the occupancy
030 * sensor and the OBlock will pass state changes of the occ.sensor on to its
031 * Warrant.
032 * <p>
033 * Entrances (exits when train moves in opposite direction) to OBlocks have
034 * Portals. A Portal object is a pair of OBlocks. Each OBlock has a list of its
035 * Portals.
036 * <p>
037 * When an OBlock (Detection Circuit) has a Portal whose entrance to the OBlock
038 * has a signal, then the OBlock and its chains of adjacent OBlocks up to the
039 * next OBlock having an entrance Portal with a signal, can be considered a
040 * "Block" in the sense of a prototypical railroad. Preferably all entrances to
041 * the "Block" should have entrance Portals with a signal.
042 * <p>
043 * A Portal has a list of paths (OPath objects) for each OBlock it separates.
044 * The paths are determined by the turnout settings of the turnouts contained in
045 * the block. Paths are contained within the Block boundaries. Names of OPath
046 * objects only need be unique within an OBlock.
047 *
048 * @author Pete Cressman (C) 2009
049 * @author Egbert Broerse (C) 2020
050 */
051public class OBlock extends jmri.Block implements java.beans.PropertyChangeListener {
052
053    public enum OBlockStatus {
054        Unoccupied(UNOCCUPIED, "unoccupied", Bundle.getMessage("unoccupied")),
055        Occupied(OCCUPIED, "occupied", Bundle.getMessage("occupied")),
056        Allocated(ALLOCATED, "allocated", Bundle.getMessage("allocated")),
057        Running(RUNNING, "running", Bundle.getMessage("running")),
058        OutOfService(OUT_OF_SERVICE, "outOfService", Bundle.getMessage("outOfService")),
059        Dark(UNDETECTED, "dark", Bundle.getMessage("dark")),
060        TrackError(TRACK_ERROR, "powerError", Bundle.getMessage("powerError"));
061
062        private final int status;
063        private final String name;
064        private final String descr;
065
066        private static final Map<String, OBlockStatus> map = new HashMap<>();
067        private static final Map<String, OBlockStatus> reverseMap = new HashMap<>();
068
069        OBlockStatus(int status, String name, String descr) {
070            this.status = status;
071            this.name = name;
072            this.descr = descr;
073        }
074
075        public int getStatus() { return status; }
076
077        public String getName() { return name; }
078
079        public String getDescr() { return descr; }
080
081        public static OBlockStatus getByName(String name) { return map.get(name); }
082        public static OBlockStatus getByDescr(String descr) { return reverseMap.get(descr); }
083
084        static {
085            for (OBlockStatus oblockStatus : OBlockStatus.values()) {
086                map.put(oblockStatus.getName(), oblockStatus);
087                reverseMap.put(oblockStatus.getDescr(), oblockStatus);
088            }
089        }
090    }
091
092    /*
093     * OBlock states:
094     * NamedBean.UNKNOWN                 = 0x01
095     * Block.OCCUPIED =  Sensor.ACTIVE   = 0x02
096     * Block.UNOCCUPIED = Sensor.INACTIVE= 0x04
097     * NamedBean.INCONSISTENT            = 0x08
098     * Add the following to the 4 sensor states.
099     * States are OR'ed to show combination.  e.g. ALLOCATED | OCCUPIED = allocated block is occupied
100     */
101    public static final int ALLOCATED = 0x10;      // reserve the block for subsequent use by a train
102    public static final int RUNNING = 0x20;        // OBlock that running train has reached
103    public static final int OUT_OF_SERVICE = 0x40; // OBlock that should not be used
104    public static final int TRACK_ERROR = 0x80;    // OBlock has Error
105    // UNDETECTED state bit is used for DARK blocks
106    // static final public int DARK = 0x01;        // meaning: OBlock has no Sensor, same as UNKNOWN
107
108    private static final Color DEFAULT_FILL_COLOR = new Color(200, 0, 200);
109
110    /**
111     * String constant to represent path State.
112     */
113    public static final String PROPERTY_PATH_STATE = "pathState";
114
115    /**
116     * String constant to represent path Count.
117     */
118    public static final String PROPERTY_PATH_COUNT = "pathCount";
119
120    /**
121     * String constant to represent portal Count.
122     */
123    public static final String PROPERTY_PORTAL_COUNT = "portalCount";
124
125    /**
126     * String constant to represent deleted.
127     */
128    public static final String PROPERTY_DELETED = "deleted";
129
130    public static String getLocalStatusName(String str) {
131        return OBlockStatus.getByName(str).getDescr();
132    }
133
134    public static String getSystemStatusName(String str) {
135        return OBlockStatus.getByDescr(str).getName();
136    }
137    private List<Portal> _portals = new ArrayList<>();     // portals to this block
138
139    private Warrant _warrant;        // when not null, oblock is allocated to this warrant
140    private String _pathName;        // when not null, this is the allocated path or last path used by a warrant
141    protected long _entryTime;       // time when block became occupied
142    private boolean _metric = false; // desired display mode
143    private NamedBeanHandle<Sensor> _errNamedSensor;
144    private Color _markerForeground = Color.WHITE;
145    private Color _markerBackground = DEFAULT_FILL_COLOR;
146    private Font _markerFont;
147
148    public OBlock(@Nonnull String systemName) {
149        super(systemName);
150        OBlock.this.setState(UNDETECTED);
151    }
152
153    public OBlock(@Nonnull String systemName, String userName) {
154        super(systemName, userName);
155        OBlock.this.setState(UNDETECTED);
156    }
157
158    /* What super does currently is fine.
159     * FindBug wants us to duplicate and override anyway
160     */
161    @Override
162    public boolean equals(Object obj) {
163        if (obj == this) {
164            return true;
165        }
166        if (obj == null) {
167            return false;
168        }
169
170        if (!getClass().equals(obj.getClass())) {
171            return false;
172        } else {
173            OBlock b = (OBlock) obj;
174            return b.getSystemName().equals(this.getSystemName());
175        }
176    }
177
178    @Override
179    public int hashCode() {
180        return this.getSystemName().hashCode();
181    }
182
183    /**
184     * {@inheritDoc}
185     * <p>
186     * Override to only set an existing sensor and to amend state with not
187     * UNDETECTED return true if an existing Sensor is set or sensor is to be
188     * removed from block.
189     */
190    @Override
191    public boolean setSensor(String pName) {
192        Sensor oldSensor = getSensor();
193        Sensor newSensor = null;
194        if (pName != null && pName.trim().length() > 0) {
195            newSensor = InstanceManager.sensorManagerInstance().getByUserName(pName);
196            if (newSensor == null) {
197                newSensor = InstanceManager.sensorManagerInstance().getBySystemName(pName);
198            }
199            if (newSensor == null) {
200                log.error("No sensor named '{}' exists.", pName);
201                return false;
202            }
203        }
204        if (oldSensor != null && oldSensor.equals(newSensor)) {
205            return true;
206        }
207
208        // save the non-sensor states
209        int saveState = getState() & ~(UNKNOWN | OCCUPIED | UNOCCUPIED | INCONSISTENT | UNDETECTED);
210        if (newSensor == null || pName == null) {
211            setNamedSensor(null);
212        } else {
213            setNamedSensor(InstanceManager.getDefault(jmri.NamedBeanHandleManager.class).
214                getNamedBeanHandle(pName, newSensor));
215        }
216        setState(getState() | saveState);   // add them back into new sensor
217        firePropertyChange(OCC_SENSOR_CHANGE, oldSensor, newSensor);
218        return true;
219    }
220
221    // override to determine if not UNDETECTED
222    @Override
223    public void setNamedSensor(@CheckForNull NamedBeanHandle<Sensor> namedSensor) {
224        super.setNamedSensor(namedSensor);
225        Sensor s = getSensor();
226        if ( s != null) {
227            setState( s.getState() & ~UNDETECTED);
228        }
229    }
230
231    /**
232     * @param pName name of error sensor
233     * @return true if successful
234     */
235    public boolean setErrorSensor(@CheckForNull String pName) {
236        NamedBeanHandle<Sensor> newErrSensorHdl = null;
237        Sensor newErrSensor = null;
238        if (pName != null && pName.trim().length() > 0) {
239            newErrSensor = InstanceManager.sensorManagerInstance().getByUserName(pName);
240            if (newErrSensor == null) {
241                newErrSensor = InstanceManager.sensorManagerInstance().getBySystemName(pName);
242            }
243           if (newErrSensor != null) {
244                newErrSensorHdl = InstanceManager.getDefault(jmri.NamedBeanHandleManager.class).
245                    getNamedBeanHandle(pName, newErrSensor);
246           }
247           if (newErrSensor == null) {
248               log.error("No sensor named '{}' exists.", pName);
249               return false;
250           }
251        }
252        if (_errNamedSensor != null) {
253            if (_errNamedSensor.equals(newErrSensorHdl)) {
254                return true;
255            } else {
256                _errNamedSensor.getBean().removePropertyChangeListener(this);
257            }
258        }
259
260        _errNamedSensor = newErrSensorHdl;
261        setState(getState() & ~TRACK_ERROR);
262        if (newErrSensor  != null) {
263            newErrSensor.addPropertyChangeListener( this,
264                _errNamedSensor.getName(), "OBlock Error Sensor " + getDisplayName());
265            if (newErrSensor.getState() == Sensor.ACTIVE) {
266                setState(getState() | TRACK_ERROR);
267            } else {
268                setState(getState() & ~TRACK_ERROR);
269            }
270        }
271        return true;
272    }
273
274    @CheckForNull
275    public Sensor getErrorSensor() {
276        if (_errNamedSensor == null) {
277            return null;
278        }
279        return _errNamedSensor.getBean();
280    }
281
282    @CheckForNull
283    public NamedBeanHandle<Sensor> getNamedErrorSensor() {
284        return _errNamedSensor;
285    }
286
287    @Override
288    public void propertyChange(java.beans.PropertyChangeEvent evt) {
289        if (log.isDebugEnabled()) {
290            log.debug("property change: of \"{}\" property {} is now {} from {}",
291                    getDisplayName(), evt.getPropertyName(), evt.getNewValue(), evt.getSource().getClass().getName());
292        }
293        if ((getErrorSensor() != null) && (evt.getSource().equals(getErrorSensor()))
294            && Sensor.PROPERTY_KNOWN_STATE.equals(evt.getPropertyName())) {
295            int errState = ((Integer) evt.getNewValue());
296            int oldState = getState();
297            if (errState == Sensor.ACTIVE) {
298                setState(oldState | TRACK_ERROR);
299            } else {
300                setState(oldState & ~TRACK_ERROR);
301            }
302            firePropertyChange(PROPERTY_PATH_STATE, oldState, getState());
303        }
304    }
305
306    /**
307     * Another block sharing a turnout with this block queries whether turnout
308     * is in use.
309     *
310     * @param path that uses a common shared turnout
311     * @return If warrant exists and path==pathname, return warrant display
312     *         name, else null.
313     */
314    @CheckForNull
315    protected String isPathSet(@Nonnull String path) {
316        String msg = null;
317        if (_warrant != null && path.equals(_pathName)) {
318            msg = _warrant.getDisplayName();
319        }
320        log.trace("Path \"{}\" in oblock \"{}\" {}", path, getDisplayName(),
321            (msg == null ? "not set" : " set in warrant " + msg));
322        return msg;
323    }
324
325    @CheckForNull
326    public Warrant getWarrant() {
327        return _warrant;
328    }
329
330    public boolean isAllocatedTo( @CheckForNull Warrant warrant) {
331        if (warrant == null) {
332            return false;
333        }
334        return warrant.equals(_warrant);
335    }
336
337    public String getAllocatedPathName() {
338        return _pathName;
339    }
340
341    public void setMetricUnits(boolean type) {
342        _metric = type;
343    }
344
345    public boolean isMetric() {
346        return _metric;
347    }
348
349    public void setMarkerForeground(Color c) {
350        _markerForeground = c;
351    }
352
353    public Color getMarkerForeground() {
354        return _markerForeground;
355    }
356
357    public void setMarkerBackground(Color c) {
358        _markerBackground = c;
359    }
360
361    public Color getMarkerBackground() {
362        return _markerBackground;
363    }
364
365    public void setMarkerFont(Font f) {
366        _markerFont = f;
367    }
368
369    public Font getMarkerFont() {
370        return _markerFont;
371    }
372
373    /**
374     * Update the OBlock status.
375     * Override Block because change must come from an OBlock for Web Server to receive it
376     *
377     * @param v the new state, from OBlock.ALLOCATED etc, named 'status' in JSON Servlet and Web Server
378     */
379    @Override
380    public void setState(int v) {
381        int old = getState();
382        super.setState(v);
383        // override Block to get proper source to be recognized by listener in Web Server
384        log.debug("\"{}\" setState({})", getDisplayName(), getState());
385        firePropertyChange(PROPERTY_STATE, old, getState()); // used by CPE indicator track icons
386    }
387
388    /**
389     * {@inheritDoc}
390     */
391    @Override
392    public void setValue(Object o) {
393        super.setValue(o);
394        if (o == null) {
395            _markerForeground = Color.WHITE;
396            _markerBackground = DEFAULT_FILL_COLOR;
397            _markerFont = null;
398        }
399    }
400
401    /*_
402     *  From the universal name for block status, check if it is the current status
403     */
404    public boolean statusIs(String statusName) {
405        OBlockStatus oblockStatus = OBlockStatus.getByName(statusName);
406        if (oblockStatus != null) {
407            return ((getState() & oblockStatus.getStatus()) != 0);
408        }
409        log.error("\"{}\" type not found.  Update Conditional State Variable testing OBlock \"{}\" status",
410                getDisplayName(), statusName);
411        return false;
412    }
413
414    public boolean isDark() {
415        return (getState() & OBlock.UNDETECTED) != 0;
416    }
417
418    public boolean isOccupied() {
419        return (getState() & OBlock.OCCUPIED) != 0;
420    }
421
422    @CheckForNull
423    public String occupiedBy() {
424        Warrant w = _warrant;
425        if (isOccupied()) {
426            if (w != null) {
427                return w.getTrainName();
428            } else {
429                return Bundle.getMessage("unknownTrain");
430            }
431        } else {
432            return null;
433        }
434    }
435
436    /**
437     * Test that block is not occupied and not allocated
438     *
439     * @return true if not occupied and not allocated
440     */
441    public boolean isFree() {
442        int state = getState();
443        return ((state & ALLOCATED) == 0 && (state & OCCUPIED) == 0);
444    }
445
446    /**
447     * Allocate (reserves) the block for the Warrant Note the block may be
448     * OCCUPIED by a non-warranted train, but the allocation is permitted.
449     *
450     * @param warrant the Warrant
451     * @return message with if block is already allocated to another warrant or
452     *         block is OUT_OF_SERVICE
453     */
454    @CheckForNull
455    public String allocate(Warrant warrant) {
456        if (warrant == null) {
457            log.error("allocate(warrant) called with null warrant in block \"{}\"!", getDisplayName());
458            return "ERROR! allocate called with null warrant in block \"" + getDisplayName() + "\"!";
459        }
460        if (_warrant != null) {
461            if (!warrant.equals(_warrant)) {
462                return Bundle.getMessage("AllocatedToWarrant",
463                        _warrant.getDisplayName(), getDisplayName(), _warrant.getTrainName());
464            } else {
465                return null;
466            }
467        }
468        /*
469        int state = getState();
470        if ((state & OUT_OF_SERVICE) != 0) {
471            return Bundle.getMessage("BlockOutOfService", getDisplayName());
472        }*/
473
474        _warrant = warrant;
475        if (log.isDebugEnabled()) {
476            log.debug("Allocate OBlock \"{}\" to warrant \"{}\".",
477                    getDisplayName(), warrant.getDisplayName());
478        }
479        int old = getState();
480        int newState = old | ALLOCATED;
481        super.setState(newState);
482        firePropertyChange(PROPERTY_STATE, old, newState);
483        return null;
484    }
485
486    // Highlights track icons to show that block is allocated.
487    protected void showAllocated(Warrant warrant, String pathName) {
488        if (_warrant != null && !_warrant.equals(warrant)) {
489            return;
490        }
491        if (_pathName == null) {
492            _pathName = pathName;
493        }
494        firePropertyChange(PROPERTY_PATH_STATE, 0, getState());
495//        super.setState(getState());
496    }
497
498    /**
499     * Note path name may be set if block is not allocated to a warrant. For use
500     * by CircuitBuilder Only. (test paths for editCircuitPaths)
501     *
502     * @param pathName name of a path
503     * @return error message, otherwise null
504     */
505    @CheckForNull
506    public String allocatePath(String pathName) {
507        log.debug("Allocate OBlock path \"{}\" in block \"{}\", state= {}",
508                pathName, getSystemName(), getState());
509        if (pathName == null) {
510            log.error("allocate called with null pathName in block \"{}\"!", getDisplayName());
511            return null;
512        } else if (_warrant != null) {
513            // allocated to another warrant
514            return Bundle.getMessage("AllocatedToWarrant",
515                    _warrant.getDisplayName(), getDisplayName(), _warrant.getTrainName());
516        }
517        _pathName = pathName;
518        //  DO NOT ALLOCATE block
519        return null;
520    }
521
522    public String getAllocatingWarrantName() {
523        if (_warrant == null) {
524            return ("no warrant");
525        } else {
526            return _warrant.getDisplayName();
527        }
528    }
529
530    /**
531     * Remove allocation state // maybe restore this? Remove listener regardless of ownership
532     *
533     * @param warrant warrant that has reserved this block. null is allowed for
534     *                Conditionals and CircuitBuilder to reset the block.
535     *                Otherwise, null should not be used.
536     * @return true if warrant deallocated.
537     */
538    public boolean deAllocate(Warrant warrant) {
539        if (warrant == null) {
540            return true;
541        }
542        if (_warrant != null) {
543            if (!_warrant.equals(warrant)) {
544                log.warn("{} cannot deallocate. {}", warrant.getDisplayName(), Bundle.getMessage("AllocatedToWarrant",
545                        _warrant.getDisplayName(), getDisplayName(), _warrant.getTrainName()));
546                return false;
547            }
548            Warrant curWarrant = _warrant;
549            _warrant = null;    // At times, removePropertyChangeListener may be run on a delayed thread.
550            try {
551                if (log.isDebugEnabled()) {
552                    log.debug("deAllocate block \"{}\" from warrant \"{}\"",
553                            getDisplayName(), warrant.getDisplayName());
554                }
555                removePropertyChangeListener(curWarrant);
556            } catch (Exception ex) {
557                // disposed warrant may throw null pointer - continue deallocation
558                log.trace("Warrant {} unregistered.", curWarrant.getDisplayName(), ex);
559            }
560        }
561        _warrant = null;
562        if (_pathName != null) {
563            OPath path = getPathByName(_pathName);
564            if (path != null) {
565                int lockState = Turnout.CABLOCKOUT & Turnout.PUSHBUTTONLOCKOUT;
566                path.setTurnouts(0, false, lockState, false);
567                Portal portal = path.getFromPortal();
568                if (portal != null) {
569                    portal.setState(Portal.UNKNOWN);
570                }
571                portal = path.getToPortal();
572                if (portal != null) {
573                    portal.setState(Portal.UNKNOWN);
574                }
575            }
576        }
577        int old = getState();
578        super.setState(old & ~(ALLOCATED | RUNNING));  // unset allocated and running bits
579        firePropertyChange(PROPERTY_STATE, old, getState());
580        return true;
581    }
582
583    public void setOutOfService(boolean set) {
584        if (set) {
585            setState(getState() | OUT_OF_SERVICE);  // set OoS bit
586        } else {
587            setState(getState() & ~OUT_OF_SERVICE);  // unset OoS bit
588        }
589    }
590
591    public void setError(boolean set) {
592        if (set) {
593            setState(getState() | TRACK_ERROR);  // set err bit
594        } else {
595            setState(getState() & ~TRACK_ERROR);  // unset err bit
596        }
597    }
598
599    /**
600     * Enforce unique portal names. Portals are now managed beans since 2014.
601     * This enforces unique names.
602     *
603     * @param portal the Portal to add
604     */
605    public void addPortal(Portal portal) {
606        String name = getDisplayName();
607        if (!name.equals(portal.getFromBlockName()) && !name.equals(portal.getToBlockName())) {
608            log.warn("{} not in block {}", portal.getDescription(), getDisplayName());
609            return;
610        }
611        String pName = portal.getName();
612        if (pName != null) {  // pName may be null if called from Portal ctor
613            for (Portal value : _portals) {
614                if (pName.equals(value.getName())) {
615                    return;
616                }
617            }
618        }
619        int oldSize = _portals.size();
620        _portals.add(portal);
621        log.trace("add portal \"{}\" to Block \"{}\"", portal.getName(), getDisplayName());
622        firePropertyChange(PROPERTY_PORTAL_COUNT, oldSize, _portals.size());
623    }
624
625    /**
626     * Remove portal from OBlock and stub all paths using this portal to be dead
627     * end spurs.
628     *
629     * @param portal the Portal to remove
630     */
631    @SuppressFBWarnings(value = "BC_UNCONFIRMED_CAST_OF_RETURN_VALUE", justification = "OPath extends Path")
632    protected void removePortal(@CheckForNull Portal portal) {
633        if (portal != null) {
634            Iterator<Path> iter = getPaths().iterator();
635            while (iter.hasNext()) {
636                OPath path = (OPath) iter.next();
637                if (portal.equals(path.getFromPortal())) {
638                    path.setFromPortal(null);
639                    log.trace("removed Portal {} from Path \"{}\" in oblock {}",
640                            portal.getName(), path.getName(), getDisplayName());
641                }
642                if (portal.equals(path.getToPortal())) {
643                    path.setToPortal(null);
644                    log.trace("removed Portal {} from Path \"{}\" in oblock {}",
645                            portal.getName(), path.getName(), getDisplayName());
646                }
647            }
648            iter = getPaths().iterator();
649            while (iter.hasNext()) {
650                OPath path = (OPath) iter.next();
651                if (path.getFromPortal() == null && path.getToPortal() == null) {
652                    removeOPath(path);
653                    log.trace("removed Path \"{}\" from oblock {}", path.getName(), getDisplayName());
654                }
655            }
656            int oldSize = _portals.size();
657            _portals = _portals.stream().filter(p -> !Objects.equals(p,portal)).collect(Collectors.toList());
658            firePropertyChange(PROPERTY_PORTAL_COUNT, oldSize, _portals.size());
659        }
660    }
661
662    public Portal getPortalByName(String name) {
663        for (Portal po : _portals) {
664            if (po.getName().equals(name)) {
665                return po;
666            }
667        }
668        return null;
669    }
670
671    @Nonnull
672    public List<Portal> getPortals() {
673        return new ArrayList<>(_portals);
674    }
675
676    public void setPortals(ArrayList<Portal> portals) {
677        _portals = portals;
678    }
679
680    @SuppressFBWarnings(value = "BC_UNCONFIRMED_CAST_OF_RETURN_VALUE", justification = "OPath extends Path")
681    public OPath getPathByName(String name) {
682        for (Path opa : getPaths()) {
683            OPath path = (OPath) opa;
684            if (path.getName().equals(name)) {
685                return path;
686            }
687        }
688        return null;
689    }
690
691    @Override
692    public void setLength(float len) {
693        // Only shorten paths longer than 'len'
694        getPaths().stream().forEach(p -> {
695            if (p.getLength() > len) {
696                p.setLength(len); // set to default
697            }
698        });
699        super.setLength(len);
700    }
701
702    /**
703     * Enforce unique path names within OBlock, but allow a duplicate name of an
704     * OPath from another OBlock to be checked if it is in one of the OBlock's
705     * Portals.
706     *
707     * @param path the OPath to add
708     * @return true if path was added to OBlock
709     */
710    @SuppressFBWarnings(value = "BC_UNCONFIRMED_CAST_OF_RETURN_VALUE", justification = "OPath extends Path")
711    public boolean addPath(OPath path) {
712        String pName = path.getName();
713        log.trace("addPath \"{}\" to OBlock {}", pName, getSystemName());
714        List<Path> list = getPaths();
715        for (Path p : list) {
716            if (((OPath) p).equals(path)) {
717                log.trace("Path \"{}\" duplicated in OBlock {}", pName, getSystemName());
718                return false;
719            }
720            if (pName.equals(((OPath) p).getName())) {
721                log.trace("Path named \"{}\" already exists in OBlock {}", pName, getSystemName());
722                return false;
723            }
724        }
725        OBlock pathBlock = (OBlock) path.getBlock();
726        if (pathBlock != null && !this.equals(pathBlock)) {
727            log.warn("Path \"{}\" already in block {}, cannot be added to block {}",
728                    pName, pathBlock.getDisplayName(), getDisplayName());
729            return false;
730        }
731        path.setBlock(this);
732        Portal portal = path.getFromPortal();
733        if (portal != null) {
734            if (!portal.addPath(path)) {
735                log.trace("Path \"{}\" rejected by portal  {}", pName, portal.getName());
736                return false;
737            }
738        }
739        portal = path.getToPortal();
740        if (portal != null) {
741            if (!portal.addPath(path)) {
742                log.debug("Path \"{}\" rejected by portal  {}", pName, portal.getName());
743                return false;
744            }
745        }
746        super.addPath(path);
747        firePropertyChange(PROPERTY_PATH_COUNT, null, getPaths().size());
748        return true;
749    }
750
751    public boolean removeOPath(OPath path) {
752        jmri.Block block = path.getBlock();
753        if (block != null && !getSystemName().equals(block.getSystemName())) {
754            return false;
755        }
756        if (!InstanceManager.getDefault(jmri.jmrit.logix.WarrantManager.class).okToRemoveBlockPath(this, path)) {
757            return false;
758        }
759        path.clearSettings();
760        super.removePath(path);
761        // remove path from its portals
762        Portal portal = path.getToPortal();
763        if (portal != null) {
764            portal.removePath(path);
765        }
766        portal = path.getFromPortal();
767        if (portal != null) {
768            portal.removePath(path);
769        }
770        path.dispose();
771        firePropertyChange(PROPERTY_PATH_COUNT, path, getPaths().size());
772        return true;
773    }
774
775    /**
776     * Set Turnouts for the path.
777     * <p>
778     * Called by warrants to set turnouts for a train it is able to run.
779     * The warrant parameter verifies that the block is
780     * indeed allocated to the warrant. If the block is unwarranted then the
781     * block is allocated to the calling warrant. A logix conditional may also
782     * call this method with a null warrant parameter for manual logix control.
783     * If the block is under a different warrant the call will be rejected.
784     *
785     * @param pathName name of the path
786     * @param warrant  warrant the block is allocated to
787     * @return error message if the call fails. null if the call succeeds
788     */
789    protected String setPath(String pathName, Warrant warrant) {
790        OPath path = getPathByName(pathName);
791        if (path == null) {
792            return Bundle.getMessage("PathNotFound", pathName, getDisplayName());
793        }
794        if (warrant == null || !warrant.equals(_warrant)) {
795            String name;
796            if (_warrant != null) {
797                name = _warrant.getDisplayName();
798            } else {
799                name = Bundle.getMessage("Warrant");
800            }
801            return Bundle.getMessage("PathNotSet", pathName, getDisplayName(), name);
802        }
803        _pathName = pathName;
804        int lockState = Turnout.CABLOCKOUT & Turnout.PUSHBUTTONLOCKOUT;
805        path.setTurnouts(0, true, lockState, true);
806        firePropertyChange(PROPERTY_PATH_STATE, 0, getState());
807        if (log.isTraceEnabled()) {
808            log.debug("setPath: Path \"{}\" in path \"{}\" {} set for warrant {}",
809                    pathName, getDisplayName(), _pathName, warrant.getDisplayName());
810        }
811        return null;
812    }
813
814    protected OPath getPath() {
815        if (_pathName == null) {
816            return null;
817        }
818        return getPathByName(_pathName);
819    }
820
821    /*
822     * Call for Circuit Builder to make icon color changes for its GUI
823     */
824    public void pseudoPropertyChange(String propName, Object old, Object n) {
825        log.trace("pseudoPropertyChange: Block \"{}\" property \"{}\" new value= {}",
826                getSystemName(), propName, n);
827        firePropertyChange(propName, old, n);
828    }
829
830    /**
831     * (Override) Handles Block sensor going INACTIVE: this block is empty.
832     * Called by handleSensorChange
833     */
834    @Override
835    public void goingInactive() {
836        //log.debug("OBlock \"{}\" going UNOCCUPIED from state= {}", getDisplayName(), getState());
837        // preserve the non-sensor states
838        // non-UNOCCUPIED sensor states are removed (also cannot be RUNNING there if being UNOCCUPIED)
839        setState((getState() & ~(UNKNOWN | OCCUPIED | INCONSISTENT | RUNNING)) | UNOCCUPIED);
840        setValue(null);
841        if (_warrant != null) {
842            ThreadingUtil.runOnLayout(() -> _warrant.goingInactive(this));
843        }
844    }
845
846    /**
847     * (Override) Handles Block sensor going ACTIVE: this block is now occupied,
848     * figure out from who and copy their value. Called by handleSensorChange
849     */
850    @Override
851    public void goingActive() {
852        // preserve the non-sensor states when being OCCUPIED and remove non-OCCUPIED sensor states
853        setState((getState() & ~(UNKNOWN | UNOCCUPIED | INCONSISTENT)) | OCCUPIED);
854        _entryTime = System.currentTimeMillis();
855        if (_warrant != null) {
856            ThreadingUtil.runOnLayout(() -> _warrant.goingActive(this));
857        }
858    }
859
860    @Override
861    public void goingUnknown() {
862        setState((getState() & ~(UNOCCUPIED | OCCUPIED | INCONSISTENT)) | UNKNOWN);
863    }
864
865    @Override
866    public void goingInconsistent() {
867        setState((getState() & ~(UNKNOWN | UNOCCUPIED | OCCUPIED)) | INCONSISTENT);
868    }
869
870    @Override
871    @SuppressFBWarnings(value = "BC_UNCONFIRMED_CAST_OF_RETURN_VALUE", justification = "OPath extends Path")
872    public void dispose() {
873        if (!InstanceManager.getDefault(WarrantManager.class).okToRemoveBlock(this)) {
874            return;
875        }
876        firePropertyChange(PROPERTY_DELETED, null, null);
877        // remove paths first
878        for (Path pa : getPaths()) {
879            removeOPath((OPath)pa);
880        }
881        for (Portal portal : getPortals()) {
882            if (log.isTraceEnabled()) {
883                log.debug("this = {}, toBlock = {}, fromblock= {}", getDisplayName(),
884                        portal.getToBlock().getDisplayName(), portal.getFromBlock().getDisplayName());
885            }
886            if (this.equals(portal.getToBlock())) {
887                portal.setToBlock(null, false);
888            }
889            if (this.equals(portal.getFromBlock())) {
890                portal.setFromBlock(null, false);
891            }
892        }
893        _portals.clear();
894        for (PropertyChangeListener listener : getPropertyChangeListeners()) {
895            removePropertyChangeListener(listener);
896        }
897        jmri.InstanceManager.getDefault(OBlockManager.class).deregister(this);
898        super.dispose();
899    }
900
901    public String getDescription() {
902        return java.text.MessageFormat.format(
903                Bundle.getMessage("BlockDescription"), getDisplayName());
904    }
905
906    @Override
907    public List<NamedBeanUsageReport> getUsageReport(NamedBean bean) {
908        List<NamedBeanUsageReport> report = new ArrayList<>();
909        List<NamedBean> duplicateCheck = new ArrayList<>();
910        if (bean != null) {
911            if (log.isDebugEnabled()) {
912                Sensor s = getSensor();
913                log.debug("oblock: {}, sensor = {}", getDisplayName(), (s==null?"Dark OBlock":s.getDisplayName()));  // NOI18N
914            }
915            if (bean.equals(getSensor())) {
916                report.add(new NamedBeanUsageReport("OBlockSensor"));  // NOI18N
917            }
918            if (bean.equals(getErrorSensor())) {
919                report.add(new NamedBeanUsageReport("OBlockSensorError"));  // NOI18N
920            }
921            if (bean.equals(getWarrant())) {
922                report.add(new NamedBeanUsageReport("OBlockWarant"));  // NOI18N
923            }
924
925            getPortals().forEach((portal) -> {
926                if (log.isDebugEnabled()) {
927                    log.debug("    portal: {}, fb = {}, tb = {}, fs = {}, ts = {}",  // NOI18N
928                            portal.getName(), portal.getFromBlockName(), portal.getToBlockName(),
929                            portal.getFromSignalName(), portal.getToSignalName());
930                }
931                if (bean.equals(portal.getFromBlock()) || bean.equals(portal.getToBlock())) {
932                    report.add(new NamedBeanUsageReport("OBlockPortalNeighborOBlock", portal.getName()));  // NOI18N
933                }
934                if (bean.equals(portal.getFromSignal()) || bean.equals(portal.getToSignal())) {
935                    report.add(new NamedBeanUsageReport("OBlockPortalSignal", portal.getName()));  // NOI18N
936                }
937
938                portal.getFromPaths().forEach((path) -> {
939                    log.debug("        from path = {}", path.getName());  // NOI18N
940                    path.getSettings().forEach((setting) -> {
941                        log.debug("            turnout = {}", setting.getBean().getDisplayName());  // NOI18N
942                        if (bean.equals(setting.getBean())) {
943                            if (!duplicateCheck.contains(bean)) {
944                                report.add(new NamedBeanUsageReport("OBlockPortalPathTurnout", portal.getName()));  // NOI18N
945                                duplicateCheck.add(bean);
946                            }
947                        }
948                    });
949                });
950                portal.getToPaths().forEach((path) -> {
951                    log.debug("        to path   = {}", path.getName());  // NOI18N
952                    path.getSettings().forEach((setting) -> {
953                        log.debug("            turnout = {}", setting.getBean().getDisplayName());  // NOI18N
954                        if (bean.equals(setting.getBean())) {
955                            if (!duplicateCheck.contains(bean)) {
956                                report.add(new NamedBeanUsageReport("OBlockPortalPathTurnout", portal.getName()));  // NOI18N
957                                duplicateCheck.add(bean);
958                            }
959                        }
960                    });
961                });
962            });
963        }
964        return report;
965    }
966
967    @Override
968    @Nonnull
969    public String getBeanType() {
970        return Bundle.getMessage("BeanNameOBlock");
971    }
972
973    private static final org.slf4j.Logger log = org.slf4j.LoggerFactory.getLogger(OBlock.class);
974
975}