001package jmri.jmrix;
002
003import java.io.DataInputStream;
004import java.io.DataOutputStream;
005import java.io.IOException;
006
007import jmri.SystemConnectionMemo;
008
009/**
010 * Enables basic setup of a interface for a jmrix implementation.
011 * <p>
012 * This is the basic interface. Subclasses provide extensions for specific
013 * connection types (network, serial, etc).
014 * <p>
015 * For historical reasons, this provides both four specific options (option1 to option4)
016 * plus a more flexible interface based on a String array.  The more flexible 
017 * interface is the preferred one for new work, but the 1-4 form hasn't been 
018 * deprecated yet.
019 * <p>
020 * General design documentation is available on the 
021 * <a href="http://jmri.org/help/en/html/doc/Technical/SystemStructure.shtml">Structure of External System Connections page</a>.
022 *
023 * @author Bob Jacobsen Copyright (C) 2001, 2003, 2008, 2010
024 * @see jmri.jmrix.SerialConfigException
025 * @since 2.3.1
026 */
027public interface PortAdapter {
028
029    /**
030     * Configure all of the other jmrix widgets needed to work with this adapter.
031     */
032    void configure();
033
034    /**
035     * Query the status of this connection.
036     * This is a question of configuration, not transient hardware status.
037     *
038     * @return true if OK, at least as far as known
039     */
040    boolean status();
041
042    /**
043     * Open the connection.
044     *
045     * @throws java.io.IOException if unable to connect
046     */
047    void connect() throws IOException;
048
049    String getCurrentPortName();
050
051    /**
052     * Get the InputStream from the port.
053     *
054     * @return the InputStream from the port
055     */
056    DataInputStream getInputStream();
057
058    /**
059     * Get the outputStream to the port.
060     *
061     * @return the outputStream to the port
062     */
063    DataOutputStream getOutputStream();
064
065    String getOption1Name();
066
067    String getOption2Name();
068
069    String getOption3Name();
070
071    String getOption4Name();
072
073    /**
074     * Set the first port option. Only to be used after construction,
075     * but before the openPort call.
076     *
077     * @param value to set the option to
078     */
079    void configureOption1(String value);
080
081    /**
082     * Set the second port option. Only to be used after construction,
083     * but before the openPort call.
084     *
085     * @param value to set the option to
086     */
087    void configureOption2(String value);
088
089    /**
090     * Set the third port option. Only to be used after construction,
091     * but before the openPort call.
092     *
093     * @param value to set the option to
094     */
095    void configureOption3(String value);
096
097    /**
098     * Set the fourth port option. Only to be used after construction,
099     * but before the openPort call.
100     *
101     * @param value to set the option to
102     */
103    void configureOption4(String value);
104
105    /**
106     * Get a list of all the options configured against this adapter.
107     *
108     * @return Array of option identifier strings
109     */
110    String[] getOptions();
111
112    boolean isOptionAdvanced(String option);
113
114    String getOptionDisplayName(String option);
115
116    /**
117     * Set the value of an option.
118     *
119     * @param option the name string of the option
120     * @param value the string value to set the option to
121     */
122    void setOptionState(String option, String value);
123
124    /**
125     * Get the string value of a specific option.
126     *
127     * @param option the name of the option to query
128     * @return the option value
129     */
130    String getOptionState(String option);
131
132    /**
133     * Get a list of the various choices allowed with an given option.
134     *
135     * @param option the name of the option to query
136     * @return list of valid values for the option
137     */
138    String[] getOptionChoices(String option);
139
140    /**
141     * Should this option be represented by a text field
142     * (as opposed to a JCombobox)
143     * @param option Name of the option to check
144     * @return true for text representation preferred
145     */
146    boolean isOptionTypeText(String option);
147    
148    /**
149     * Should this option be represented by a password field
150     * @param option Name of the option to check
151     * @return true for text representation preferred
152     */
153    boolean isOptionTypePassword(String option);
154    
155    /**
156     * Get the system manufacturer's name.
157     *
158     * @return manufacturer's name
159     */
160    String getManufacturer();
161
162    /**
163     * Set the system manufacturer's name.
164     *
165     * @param Manufacturer the manufacturer's name
166     */
167    void setManufacturer(String Manufacturer);
168
169    /**
170     * Return the disabled state of the adapter.
171     *
172     * @return true if disabled
173     */
174    boolean getDisabled();
175
176    /**
177     * Set whether the connection is disabled.
178     *
179     * @param disabled When true, disables operation
180     */
181    void setDisabled(boolean disabled);
182
183    /**
184     * Get the user name for this adapter.
185     *
186     * @return the username or null
187     */
188    String getUserName();
189
190    /**
191     * Set the user name for this adapter.
192     *
193     * @param userName the new user name
194     * @throws IllegalArgumentException if another adapter has this user name
195     */
196    void setUserName(String userName) throws IllegalArgumentException;
197
198    /**
199     * Get the system prefix for this adapter.
200     *
201     * @return the system prefix or null
202     */
203    String getSystemPrefix();
204
205    /**
206     * Set the system prefix for this adapter.
207     *
208     * @param systemPrefix the new system prefix
209     * @throws IllegalArgumentException if another adapter has this system
210     *                                  prefix
211     */
212    void setSystemPrefix(String systemPrefix) throws IllegalArgumentException;
213
214    SystemConnectionMemo getSystemConnectionMemo();
215
216    /**
217     * Replace the existing SystemConnectionMemo with another one. Overriding
218     * methods should throw an {@link java.lang.IllegalAccessException} if the
219     * overriding class requires a specific subclass of SystemConnectionMemo. A
220     * {@link java.lang.NullPointerException} should be thrown if the parameter
221     * is null.
222     *
223     * @param connectionMemo the new connection memo
224     * @throws IllegalArgumentException if connectionMemo is the wrong subclass
225     *                                  of SystemConnectionMemo
226     * @throws NullPointerException     if connectionMemo is null
227     */
228    void setSystemConnectionMemo(SystemConnectionMemo connectionMemo) throws IllegalArgumentException;
229
230    /**
231     * This is called when a connection is to be disposed.
232     */
233    void dispose();
234
235    /**
236     * This is called when a connection is initially lost.
237     */
238    void recover();
239
240    /**
241     * Determine if configuration needs to be written to disk.
242     *
243     * @return true if configuration needs to be saved, false otherwise
244     */
245    boolean isDirty();
246
247    /**
248     * Determine if application needs to be restarted for configuration changes
249     * to be applied.
250     *
251     * @return true if application needs to restart, false otherwise
252     */
253    boolean isRestartRequired();
254    
255    /**
256     * Set the maximum interval between reconnection attempts.
257     * @param maxInterval in seconds.
258     */
259    void setReconnectMaxInterval(int maxInterval);
260    
261    /**
262     * Set the maximum number of reconnection attempts.
263     * -1 will set an infinite number of attempts.
264     * @param maxAttempts total maximum reconnection attempts.
265     */
266    void setReconnectMaxAttempts(int maxAttempts);
267    
268    /**
269     * Get the maximum interval between reconnection attempts.
270     * @return maximum interval in seconds.
271     */
272    int getReconnectMaxInterval();
273    
274    /**
275     * Get the maximum number of reconnection attempts which should be made.
276     * A value of -1 means no maximum value, i.e. infinite attempts.
277     * @return total number of attempts which should be made.
278     */
279    int getReconnectMaxAttempts();
280
281}