001package jmri;
002
003import java.util.Comparator;
004
005import javax.annotation.Nonnull;
006import javax.annotation.OverridingMethodsMustInvokeSuper;
007
008import jmri.util.startup.StartupActionFactory;
009
010/**
011 * Lightweight interface denoting that a system is active, and provide
012 * general information.
013 * <p>
014 * Objects of specific subtypes of this are registered in the
015 * {@link InstanceManager} to activate their particular system.
016 *
017 * @author Bob Jacobsen Copyright (C) 2020
018 */
019public interface SystemConnectionMemo extends jmri.beans.PropertyChangeProvider {
020
021    void dispose();
022
023    /**
024     * Get a manager for a specific type. This method <strong>must</strong>
025     * return a non-null value if {@link #provides(java.lang.Class)} is true for
026     * the type, and <strong>must</strong> return null if provides() is false
027     * for the type.
028     *
029     * @param <T>  Type of manager to get
030     * @param type Type of manager to get
031     * @return The manager or null if provides() is false for T
032     * @see #provides(java.lang.Class)
033     */
034    @OverridingMethodsMustInvokeSuper
035    <T> T get(Class<T> type);
036
037    String DISABLED = "ConnectionDisabled";
038    String USER_NAME = "ConnectionNameChanged";
039    String SYSTEM_PREFIX = "ConnectionPrefixChanged";
040    String INTERVAL = "OutputInterval";
041    String STORE = "Store";
042    String DEREGISTER = "Deregister";
043
044    /**
045     * Provide a factory for getting startup actions.
046     * <p>
047     * This is a bound, read-only, property under the name "actionFactory".
048     *
049     * @return the factory
050     */
051    @Nonnull
052    StartupActionFactory getActionFactory();
053
054    /**
055     * Get if the System Connection is currently Disabled.
056     *
057     * @return true if Disabled, else false.
058     */
059    boolean getDisabled();
060
061    /**
062     * Get the Comparator to be used for two NamedBeans. This is typically an
063     * {@link jmri.util.NamedBeanComparator}, but may be any Comparator that works for
064     * this connection type.
065     *
066     * @param <B>  the type of NamedBean
067     * @param type the class of NamedBean
068     * @return the Comparator
069     */
070    <B extends NamedBean> Comparator<B> getNamedBeanComparator(Class<B> type);
071
072    /**
073     * Provide access to the system prefix string.
074     * <p>
075     * This was previously called the "System letter".
076     *
077     * @return System prefix
078     */
079    String getSystemPrefix();
080
081    /**
082     * Provide access to the system user name string.
083     * <p>
084     * This was previously fixed at configuration time.
085     *
086     * @return User name of the connection
087     */
088    String getUserName();
089
090    /**
091     * Get if connection is dirty. Checked fields are disabled, prefix, userName
092     *
093     * @return true if changed since loaded
094     */
095    boolean isDirty();
096
097    boolean isRestartRequired();
098
099    /**
100     * Check if this connection provides a specific manager type. This method
101     * <strong>must</strong> return false if a manager for the specific type is
102     * not provided, and <strong>must</strong> return true if a manager for the
103     * specific type is provided.
104     *
105     * @param c The class type for the manager to be provided
106     * @return true if the specified manager is provided
107     * @see #get(java.lang.Class)
108     */
109    @OverridingMethodsMustInvokeSuper
110    boolean provides(Class<?> c);
111
112    /**
113     * Store in InstanceManager with proper ID for later retrieval as a generic
114     * system.
115     */
116    void register();
117
118    /**
119     * Set if the System Connection is currently Disabled.
120     * <p>
121     * disabledAsLoaded is only set once. Sends PropertyChange on change of
122     * disabled status.
123     *
124     * @param disabled true to disable, false to enable.
125     */
126    void setDisabled(boolean disabled);
127
128    /**
129     * Set the system prefix.
130     *
131     * @param systemPrefix prefix to use for this system connection
132     * @throws java.lang.NullPointerException if systemPrefix is null
133     * @return true if the system prefix could be set
134     */
135    boolean setSystemPrefix(@Nonnull String systemPrefix);
136
137    /**
138     * Set the user name for the system connection.
139     *
140     * @param userName user name to use for this system connection
141     * @throws java.lang.NullPointerException if name is null
142     * @return true if the user name could be set
143     */
144    boolean setUserName(@Nonnull String userName);
145
146    /**
147     * Get the connection specific OutputInterval to wait between/before commands
148     * are sent, configured in AdapterConfig.
149     * Used in {@link jmri.implementation.AbstractTurnout#setCommandedStateAtInterval(int)}.
150     *
151     * @return the output interval time in ms
152     */
153    int getOutputInterval();
154
155    /**
156     * Get the Default connection specific OutputInterval to wait between/before commands
157     * are sent.
158     * @return the default output interval time in ms.
159     */
160    int getDefaultOutputInterval();
161
162    void setOutputInterval(int newInterval);
163
164}