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