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}