Merge branch 'master' of http://github.com/JMRI/JMRI into testbenchmarks

help/en/html/doc/Technical/RP.shtml

@@ -61,9 +61,21 @@
         <a href="https://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html">HashMap</a>, 
         etc) in the 
         <a href="https://docs.oracle.com/javase/8/docs/api/java/util/package-summary.html">java.util package</a>.
-        Not everything needs to be an array! A 
-        <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Deque.html">Deque</a>
+        Not everything needs to be an array! Only use a 
+        <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Vector.html">Vector</a>
+        when there's a specific reason for it such as compatibility with an existing API;
+        they're slow and memory-intensive compared to e.g. an 
+        <a href="https://docs.oracle.com/javase/8/docs/api/java/util/ArrayList.html">ArrayList</a>.
+        A <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Deque.html">Deque</a>
         can be a good default solution to holding data that won't ever contain 'null'.
+        Consider using a
+        <a href="https://docs.oracle.com/javase/8/docs/api/java/util/TreeSet.html">TreeSet</a>
+        for data that's best kept in some sorted order; there's are very few good reasons for
+        sorting data during normal running in JMRI.  If you also need random access (e.g. 
+        "The 5th element") consider 
+        <a href="http://www.jmri.org/JavaDoc/doc/jmri/util/com/dictiography/collections/IndexedTreeSet.html">IndexedTreeSet</a>
+        and
+        <a href="http://www.jmri.org/JavaDoc/doc/jmri/util/com/dictiography/collections/IndexedTreeMap.html">IndexedTreeMap</a>
         </li>
 
         <li>JMRI uses <a href=
@@ -80,17 +92,54 @@
         this page</a> from the Java Tutorial.</li>
 
         <li>If you need to use comma-separated variable (CSV)
-        files, please use the <a href=
-        "http://javacsv.sourceforge.net/">javacsv API</a> if
+        files, please use the <a href="http://javacsv.sourceforge.net/">javacsv API</a> if
         possible. We are already using that in a number of places,
         and will probably use it in more. If that doesn't provide
         enough functionality, we might eventually move to the
-        <a href=
-        "http://opencsv.sourceforge.net/api/au/com/bytecode/opencsv/">
-        opencsv API</a>, but since we only want to use one, the
+        <a href="http://opencsv.sourceforge.net/api/au/com/bytecode/opencsv/">opencsv API</a>, 
+        but since we only want to use one, the
         conversion will be a lot of work.</li>
       </ul>
 
+      <a id="collections" name="collections"></a>
+      <h2>Collections</h2>
+        Take a few moments to learn about the different
+        types of <a href=
+        "https://docs.oracle.com/javase/tutorial/collections/intro/">
+        Java collections</a> that are available (
+        <a href="https://docs.oracle.com/javase/8/docs/api/java/util/List.html">List</a>,
+        <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Deque.html">Deque</a>,
+        <a href="https://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html">HashMap</a>, 
+        etc) in the 
+        <a href="https://docs.oracle.com/javase/8/docs/api/java/util/package-summary.html">java.util package</a>.
+
+
+        <ul>
+        <li>
+        Please don't use fixed-size arrays for holding variable sized data in objects.
+        That generally ends up wasting huge amounts of space at runtime, and we 
+        try to keep the JMRI memory footprint small when we can.
+
+        <li>
+        Only use a 
+            <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Vector.html">Vector</a>
+            when there's a specific reason for it such as compatibility with an existing API;
+            they're slow and memory-intensive compared to e.g. an 
+            <a href="https://docs.oracle.com/javase/8/docs/api/java/util/ArrayList.html">ArrayList</a>.
+        <li>
+            A <a href="https://docs.oracle.com/javase/8/docs/api/java/util/Deque.html">Deque</a>
+            can be a good default solution to holding data that won't ever contain 'null'.
+       <li> 
+            Consider using a
+            <a href="https://docs.oracle.com/javase/8/docs/api/java/util/TreeSet.html">TreeSet</a>
+            for data that's best kept in some sorted order; there's are very few good reasons for
+            sorting data during normal running in JMRI.  If you also need random access (e.g. 
+            "The 5th element") consider 
+            <a href="http://www.jmri.org/JavaDoc/doc/jmri/util/com/dictiography/collections/IndexedTreeSet.html">IndexedTreeSet</a>
+            and
+            <a href="http://www.jmri.org/JavaDoc/doc/jmri/util/com/dictiography/collections/IndexedTreeMap.html">IndexedTreeMap</a>
+        </ul>
+
       <h2>Code Format</h2>The <a href=
       "http://www.oracle.com/technetwork/java/codeconventions-150003.pdf">
       Java Code Conventions</a> (if that link is broken, try

help/en/manual/DecoderPro3/Main_Monitor_Window.shtml

@@ -73,7 +73,7 @@
       "checkbox"> <strong>Show timestamps</strong>-Normally, the
       program just displays the data from the communication link..
       If you would like each message to be preceded by the time it
-      was sent or recieved, check this box.</p>
+      was sent or received, check this box.</p>
 
       <p align="left"><input name="a" type="checkbox"> <span style=
       "font-weight: bold;">Window always on Top</span> -- Always

java/src/jmri/ConditionalVariable.java

@@ -931,7 +931,7 @@ public static String getTestTypeString(int t) {
             case Conditional.TYPE_SIGNAL_HEAD_FLASHYELLOW:
                 return Bundle.getMessage("SignalHeadStateFlashingYellow"); // NOI18N
             case Conditional.TYPE_SIGNAL_HEAD_FLASHGREEN:
-                Bundle.getMessage("SignalHeadStateFlashingGreen"); // NOI18N
+                return Bundle.getMessage("SignalHeadStateFlashingGreen"); // NOI18N
             case Conditional.TYPE_SIGNAL_HEAD_LIT:
                 return Bundle.getMessage("SignalHeadStateLit"); // NOI18N
             case Conditional.TYPE_SIGNAL_HEAD_HELD:

java/src/jmri/Manager.java

@@ -496,12 +496,12 @@ public default String getEntryToolTip() {
      * Register a {@link ManagerDataListener} to hear about 
      * adding or removing items from the list of NamedBeans
      */
-    public void addDataListener(ManagerDataListener e);
+    public void addDataListener(ManagerDataListener<E> e);
 
     /**
      * Unregister a previously-added {@link ManagerDataListener}
      */
-    public void removeDataListener(ManagerDataListener e);
+    public void removeDataListener(ManagerDataListener<E> e);
 
     /**
      * Temporarily suppress DataListener notifications.

java/src/jmri/SignalMastLogicManager.java

@@ -31,15 +31,6 @@ public interface SignalMastLogicManager extends Manager<SignalMastLogic> {
      */
     public void automaticallyDiscoverSignallingPairs() throws JmriException;
 
-    /**
-     * Use the Layout Editor to check if the destination signal mast is
-     * reachable from the source signal mast.
-     *
-     * @param sourceMast Source Signal Mast
-     * @param destMast   Destination Signal Mast
-     * @return true if valid, false if not valid
-     */
-    // public boolean checkValidDest(SignalMast sourceMast, SignalMast destMast) throws JmriException;
     /**
      * Discover valid destination signal masts for a given source Signal Mast on
      * a given Layout Editor Panel.

java/src/jmri/implementation/AbstractIdTag.java

@@ -57,6 +57,10 @@ public Date getWhenLastSeen() {
         }
     }
 
+    // note that this doesn't properly implement the 
+    // contract in {@link NamedBean.toString()}, 
+    // which means things like tables and persistance 
+    // might not behave properly.
     @Override
     public String toString() {
         String userName = getUserName();

java/src/jmri/implementation/AbstractNamedBean.java

@@ -60,23 +60,18 @@ protected AbstractNamedBean(@Nonnull String sys, @Nullable String user) throws N
     }
 
     /**
-     * Get associated comment text.
+     * {@inheritDoc}
      */
     @Override
-    public String getComment() {
+    final public String getComment() {
         return this.comment;
     }
 
     /**
-     * Set associated comment text.
-     * <p>
-     * Comments can be any valid text.
-     *
-     * @param comment 'nulln means no comment associated.
+     * {@inheritDoc}
      */
     @Override
-    @OverridingMethodsMustInvokeSuper
-    public void setComment(String comment) {
+    final public void setComment(String comment) {
         String old = this.comment;
         if (comment == null || comment.trim().isEmpty()) {
             this.comment = null;
@@ -88,8 +83,12 @@ public void setComment(String comment) {
     private String comment;
 
     /**
-     * Get the name string of this object.
-     *
+     * {@inheritDoc}
+     * <p>
+     * It would be good to eventually make this final to 
+     * keep it consistent system-wide, but 
+     * we have some existing classes to update first.
+     * 
      * @return user name if not null or empty, else return system name
      */
     @Override
@@ -102,6 +101,12 @@ public String getDisplayName() {
         }
     }
 
+    /**
+     * <p>
+     * It would be good to eventually make this final to 
+     * keep it consistent system-wide, but 
+     * we have some existing classes to update first.
+     */
     @Override
     public String getFullyFormattedDisplayName() {
         String name = getUserName();
@@ -203,12 +208,16 @@ public synchronized PropertyChangeListener[] getPropertyChangeListeners() {
     }
 
     @Override
-    public String getSystemName() {
+    final public String getSystemName() {
         return mSystemName;
     }
 
     /**
      * {@inheritDoc}
+     * <p>
+     * It would be good to eventually make this final to 
+     * keep it consistent system-wide, but 
+     * we have some existing classes to update first.
      */
     @Nonnull
     @Override
@@ -217,7 +226,7 @@ public String toString() {
     }
 
     @Override
-    public String getUserName() {
+    final public String getUserName() {
         return mUserName;
     }
 

java/src/jmri/implementation/AbstractReporter.java

@@ -31,12 +31,6 @@ public String getBeanType() {
         return Bundle.getMessage("BeanNameReporter");
     }
 
-    // for combo boxes
-    @Override
-    public String toString() {
-        return getDisplayName();
-    }
-
     @Override
     public Object getCurrentReport() {
         return _currentReport;

java/src/jmri/implementation/DccConsist.java

@@ -492,7 +492,7 @@ protected void notifyConsistListeners(DccLocoAddress LocoAddress, int ErrorCode)
     // include the programmingOpReply() function
     @Override
     public void programmingOpReply(int value, int status) {
-        log.debug("Programming Operation reply recieved, value is {}, status is {}", value, status);
+        log.debug("Programming Operation reply received, value is {}, status is {}", value, status);
         notifyConsistListeners(new DccLocoAddress(0, false), ConsistListener.OPERATION_SUCCESS);
     }
 

java/src/jmri/implementation/DefaultRailCom.java

@@ -284,6 +284,10 @@ public List<Integer> getCVList() {
 
     Hashtable<Integer, Integer> cvValues = new Hashtable<>();
 
+    // note that this doesn't properly implement the 
+    // contract in {@link NamedBean.toString()}, 
+    // which means things like tables and persistance 
+    // might not behave properly.
     @Override
     public String toString() {
         String comment;

java/src/jmri/implementation/DefaultSignalSystem.java

@@ -178,6 +178,10 @@ public float getMaximumLineSpeed() {
 
     protected java.util.Vector<String> imageTypes = new java.util.Vector<>();
 
+    // note that this doesn't properly implement the 
+    // contract in {@link NamedBean.toString()}, 
+    // which means things like tables and persistance 
+    // might not behave properly.
     @Override
     public String toString() {
         StringBuilder retval = new StringBuilder();

java/src/jmri/implementation/SE8cSignalHead.java

@@ -46,7 +46,6 @@ public SE8cSignalHead(NamedBeanHandle<Turnout> lowTO,
         super(makeSystemName(lowTO, highTO), userName);
         this.lowTurnout = lowTO;
         this.highTurnout = highTO;
-        systemName = makeSystemName(lowTO, highTO);
         init();
     }
 
@@ -62,7 +61,6 @@ public SE8cSignalHead(NamedBeanHandle<Turnout> lowTO,
         super(makeSystemName(lowTO, highTO));
         this.lowTurnout = lowTO;
         this.highTurnout = highTO;
-        systemName = makeSystemName(lowTO, highTO);
         init();
     }
 
@@ -81,7 +79,6 @@ public SE8cSignalHead(String sname, NamedBeanHandle<Turnout> lowTO,
         super(sname, userName);
         this.lowTurnout = lowTO;
         this.highTurnout = highTO;
-        systemName = sname;
         init();
     }
 
@@ -98,7 +95,6 @@ public SE8cSignalHead(String sname, NamedBeanHandle<Turnout> lowTO,
         super(sname);
         this.lowTurnout = lowTO;
         this.highTurnout = highTO;
-        systemName = sname;
         init();
     }
 
@@ -112,7 +108,6 @@ public SE8cSignalHead(int pNumber, String userName) {
         super("LH" + pNumber, userName);
         this.lowTurnout = makeHandle(pNumber);
         this.highTurnout = makeHandle(pNumber + 1);
-        systemName = "LH" + pNumber;
         init();
     }
 
@@ -156,7 +151,6 @@ public SE8cSignalHead(int pNumber) {
         super("LH" + pNumber);
         this.lowTurnout = makeHandle(pNumber);
         this.highTurnout = makeHandle(pNumber + 1);
-        systemName = "LH" + pNumber;
         init();
     }
 
@@ -173,12 +167,6 @@ void init() {
         updateOutput();
     }
 
-    @Override
-    public String getSystemName() {
-        return systemName;
-    }
-    String systemName;
-
     /**
      * Type-specific routine to handle output to the layout hardware.
      * Implemented to handle a request to change state by sending a LocoNet

java/src/jmri/jmrit/audio/AbstractAudioSource.java

@@ -49,7 +49,6 @@ public abstract class AbstractAudioSource extends AbstractAudio implements Audio
     private int fadeInTime = 1000;
     private int fadeOutTime = 1000;
     private float fadeGain = 1.0f;
-    private float dopplerFactor = 1.0f;
     private long timeOfLastFadeCheck = 0;
     private long timeOfLastPositionCheck = 0;
     private int fading = Audio.FADE_NONE;
@@ -833,6 +832,10 @@ protected int getFading() {
         return this.fading;
     }
 
+    // note that this doesn't properly implement the 
+    // contract in {@link NamedBean.toString()}, 
+    // which means things like tables and persistance 
+    // might not behave properly.
     @Override
     public String toString() {
         return "Pos: " + this.getPosition().toString()