diff --git a/src/main/cpp/_nix_based/jssc.cpp b/src/main/cpp/_nix_based/jssc.cpp index 97c3e67f9..6887a0b6a 100644 --- a/src/main/cpp/_nix_based/jssc.cpp +++ b/src/main/cpp/_nix_based/jssc.cpp @@ -700,7 +700,7 @@ JNIEXPORT jint JNICALL Java_jssc_SerialNativeInterface_getFlowControlMode /* OK */ /* - * Send break for setted duration + * Send break for set duration */ JNIEXPORT jboolean JNICALL Java_jssc_SerialNativeInterface_sendBreak (JNIEnv *, jobject, jlong portHandle, jint duration){ diff --git a/src/main/cpp/windows/jssc.cpp b/src/main/cpp/windows/jssc.cpp index 799d91907..fe261c025 100644 --- a/src/main/cpp/windows/jssc.cpp +++ b/src/main/cpp/windows/jssc.cpp @@ -136,7 +136,7 @@ JNIEXPORT jboolean JNICALL Java_jssc_SerialNativeInterface_setParams if(SetCommState(hComm, dcb)){ - //since 2.1.0 -> previously setted timeouts by another application should be cleared + //since 2.1.0 -> timeouts set previously by another application should be cleared COMMTIMEOUTS *lpCommTimeouts = new COMMTIMEOUTS(); lpCommTimeouts->ReadIntervalTimeout = 0; lpCommTimeouts->ReadTotalTimeoutConstant = 0; @@ -392,7 +392,7 @@ JNIEXPORT jint JNICALL Java_jssc_SerialNativeInterface_getFlowControlMode } /* - * Send break for setted duration + * Send break for set duration * * since 0.8 */ diff --git a/src/main/java/jssc/SerialNativeInterface.java b/src/main/java/jssc/SerialNativeInterface.java index f6ccf35f7..58ddd1d4c 100644 --- a/src/main/java/jssc/SerialNativeInterface.java +++ b/src/main/java/jssc/SerialNativeInterface.java @@ -37,43 +37,71 @@ public class SerialNativeInterface { private static final String libVersion = "2.9"; private static final String libMinorSuffix = "1"; //since 0.9.0 + /** Linux **/ public static final int OS_LINUX = 0; + /** Windows **/ public static final int OS_WINDOWS = 1; + /** Solaris **/ public static final int OS_SOLARIS = 2;//since 0.9.0 + /** MacOS **/ public static final int OS_MAC_OS_X = 3;//since 0.9.0 - - private static int osType = -1; + /** Unknown **/ + public static final int OS_UNKNOWN = -1;//since 0.9.0 /** + * Port is busy + * * @since 2.3.0 */ public static final long ERR_PORT_BUSY = -1; /** + * Port is not found + * * @since 2.3.0 */ public static final long ERR_PORT_NOT_FOUND = -2; /** + * Insufficient permissions to access port + * * @since 2.3.0 */ public static final long ERR_PERMISSION_DENIED = -3; /** + * Serial port handle is incorrect + * * @since 2.3.0 */ public static final long ERR_INCORRECT_SERIAL_PORT = -4; /** + * Disable exclusive lock for serial port + * + * Usage: + * System.setProperty("jssc_no_tiocexcl", "true"); + * * @since 2.6.0 */ public static final String PROPERTY_JSSC_NO_TIOCEXCL = "JSSC_NO_TIOCEXCL"; /** + * Ignore bytes with framing error or parity error + * + * Usage: + * System.setProperty("jssc_ignpar", "true"); + * * @since 2.6.0 */ public static final String PROPERTY_JSSC_IGNPAR = "JSSC_IGNPAR"; /** + * Mark bytes with parity error or framing error + * + * Usage: + * System.setProperty("jssc_iparmrk", "true"); + * * @since 2.6.0 */ public static final String PROPERTY_JSSC_PARMRK = "JSSC_PARMRK"; + private static int osType; static { String osName = System.getProperty("os.name"); if(osName.equals("Linux")) @@ -84,6 +112,8 @@ else if(osName.equals("SunOS")) osType = OS_SOLARIS; else if(osName.equals("Mac OS X") || osName.equals("Darwin")) osType = OS_MAC_OS_X; + else + osType = OS_UNKNOWN; try { /** * JSSC includes a small, platform-specific shared library and uses native-lib-loader for extraction. @@ -105,7 +135,10 @@ else if(osName.equals("Mac OS X") || osName.equals("Darwin")) public SerialNativeInterface() {} /** - * Get OS type (OS_LINUX || OS_WINDOWS || OS_SOLARIS) + * Get OS type + * + * @return OS_LINUX, OS_WINDOWS, OS_SOLARIS,OS_MACOS + * or OS_UNKNOWN if unknown. * * @since 0.8 */ @@ -114,7 +147,9 @@ public static int getOsType() { } /** - * Get jSSC version. The version of library is Base Version + Minor Suffix + * Get library version + * + * @return Full library version in "major.minor.patch" format. * * @since 0.8 */ @@ -123,27 +158,35 @@ public static String getLibraryVersion() { } /** - * Get jSSC Base Version + * Get library base Version + * + * @return Library base version in "major.minor" format. Was previously used for library versioning caching + * but is no longer used by the project. * * @since 0.9.0 */ + @Deprecated public static String getLibraryBaseVersion() { return libVersion; } /** - * Get jSSC minor suffix. For example in version 0.8.1 - 1 is a minor suffix + * Get library patch version + * + * @return Library patch version only (e.g. only "patch" from "major.minor.patch"). Was previously used for + * library versioning caching but is no longer used by the project. * * @since 0.9.0 */ + @Deprecated public static String getLibraryMinorSuffix() { return libMinorSuffix; } /** - * Get jSSC native library version + * Get native library version * - * @return native lib version (for jSSC-2.8.0 should be 2.8 for example) + * @return Full native library version in "major.minor.patch" format. * * @since 2.8.0 */ @@ -293,7 +336,7 @@ public static String getLibraryMinorSuffix() { * * @param handle handle of opened port * - * @return Mask of setted flow control mode + * @return Mask of set flow control mode * * @since 0.8 */ @@ -320,7 +363,7 @@ public static String getLibraryMinorSuffix() { public native int[] getLinesStatus(long handle); /** - * Send Break singnal for setted duration + * Send Break signal for set duration * * @param handle handle of opened port * @param duration duration of Break signal diff --git a/src/main/java/jssc/SerialPort.java b/src/main/java/jssc/SerialPort.java index 933eced61..14f9acc9e 100644 --- a/src/main/java/jssc/SerialPort.java +++ b/src/main/java/jssc/SerialPort.java @@ -31,6 +31,7 @@ * * @author scream3r */ +@SuppressWarnings("unused") public class SerialPort { private final SerialNativeInterface serialInterface; @@ -44,77 +45,128 @@ public class SerialPort { //since 2.2.0 -> private volatile Method methodErrorOccurred = null; //<- since 2.2.0 - + + /** Baud rate 110 symbols/second **/ public static final int BAUDRATE_110 = 110; + /** Baud rate 300 symbols/second **/ public static final int BAUDRATE_300 = 300; + /** Baud rate 600 symbols/second **/ public static final int BAUDRATE_600 = 600; + /** Baud rate 1200 symbols/second **/ public static final int BAUDRATE_1200 = 1200; + /** Baud rate 2400 symbols/second **/ public static final int BAUDRATE_2400 = 2400; + /** Baud rate 4800 symbols/second **/ public static final int BAUDRATE_4800 = 4800; + /** Baud rate 9600 symbols/second **/ public static final int BAUDRATE_9600 = 9600; + /** Baud rate 14400 symbols/second **/ public static final int BAUDRATE_14400 = 14400; + /** Baud rate 19200 symbols/second **/ public static final int BAUDRATE_19200 = 19200; + /** Baud rate 38400 symbols/second **/ public static final int BAUDRATE_38400 = 38400; + /** Baud rate 57600 symbols/second **/ public static final int BAUDRATE_57600 = 57600; + /** Baud rate 115200 symbols/second **/ public static final int BAUDRATE_115200 = 115200; + /** Baud rate 128000 symbols/second **/ public static final int BAUDRATE_128000 = 128000; + /** Baud rate 256000 symbols/second **/ public static final int BAUDRATE_256000 = 256000; - + /** Five (5) data bits per byte **/ public static final int DATABITS_5 = 5; + /** Six (6) data bits per byte **/ public static final int DATABITS_6 = 6; + /** Seven (7) data bits per byte **/ public static final int DATABITS_7 = 7; + /** Eight (8) data bits per byte **/ public static final int DATABITS_8 = 8; - + /** One (1) stop bits per byte **/ public static final int STOPBITS_1 = 1; + /** Two (2) stop bits per byte **/ public static final int STOPBITS_2 = 2; + /** One and a half (1.5) stop bits per byte **/ public static final int STOPBITS_1_5 = 3; - + /** Do not send a parity bit **/ public static final int PARITY_NONE = 0; + /** Use a very basic checksum: Send an additional bit to report if odd number of data bits **/ public static final int PARITY_ODD = 1; + /** Use a very basic checksum: Send an additional bit to report if even number of data bits **/ public static final int PARITY_EVEN = 2; + /** Use a very basic checksum: Send a parity bit to indicate "mark signal" condition (rarely used) **/ public static final int PARITY_MARK = 3; + /** Use a very basic checksum: Send a parity bit to indicate "space signal" condition (rarely used) **/ public static final int PARITY_SPACE = 4; - + + /** Receive "abort" status code **/ public static final int PURGE_RXABORT = 0x0002; + /** Receive "clear" status code **/ public static final int PURGE_RXCLEAR = 0x0008; + /** Transfer "abort" status code **/ public static final int PURGE_TXABORT = 0x0001; + /** Transfer "clear" status code **/ public static final int PURGE_TXCLEAR = 0x0004; + /** Receive character flag **/ public static final int MASK_RXCHAR = 1; + /** Receive flag **/ public static final int MASK_RXFLAG = 2; + /** Receive empty flag **/ public static final int MASK_TXEMPTY = 4; + /** CTS (clear to send) mask **/ public static final int MASK_CTS = 8; + /** DSR (data set to ready) flag **/ public static final int MASK_DSR = 16; + /** RLSD (Receive Line Signal Detected) flag **/ public static final int MASK_RLSD = 32; + /** Break (reset a communications line or change the operating mode) flag **/ public static final int MASK_BREAK = 64; + /** Error flag **/ public static final int MASK_ERR = 128; - public static final int MASK_RING = 256; + /** State of RING line (0 - OFF, 1 - ON) **/ + public static final int MASK_RING = 256; //since 0.8 -> + /** Disable flow control **/ public static final int FLOWCONTROL_NONE = 0; + /** Legacy hardware control: RTS/CTS (request to send/clear to send) flow control on input **/ public static final int FLOWCONTROL_RTSCTS_IN = 1; + /** Legacy hardware control: RTS/CTS (request to send/clear to send) flow control on output **/ public static final int FLOWCONTROL_RTSCTS_OUT = 2; + /** Software flow control: XON/XOFF flow control on input **/ public static final int FLOWCONTROL_XONXOFF_IN = 4; + /** Software flow control: XON/XOFF flow control on output **/ public static final int FLOWCONTROL_XONXOFF_OUT = 8; //<- since 0.8 //since 0.8 -> + /** Indicates faulty data or frame **/ public static final int ERROR_FRAME = 0x0008; + /** Overrun error; receiver hardware unable to handle receive data **/ public static final int ERROR_OVERRUN = 0x0002; + /** Parity/check bit error **/ public static final int ERROR_PARITY = 0x0004; //<- since 0.8 //since 2.6.0 -> + /** Ignore bytes with framing error or parity error **/ private static final int PARAMS_FLAG_IGNPAR = 1; + /** Mark bytes with parity error or framing error **/ private static final int PARAMS_FLAG_PARMRK = 2; //<- since 2.6.0 + /** + * Construct a serial port object with the specified portName + * + * @param portName Name of the port, e.g. COM1, /dev/tty.FOO, etc. + */ public SerialPort(String portName) { this.portName = portName; serialInterface = new SerialNativeInterface(); @@ -146,7 +198,7 @@ public boolean isOpened() { * * @return If the operation is successfully completed, the method returns true * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public synchronized boolean openPort() throws SerialPortException { if(portOpened){ @@ -186,7 +238,7 @@ else if(portHandle == SerialNativeInterface.ERR_INCORRECT_SERIAL_PORT){ * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public boolean setParams(int baudRate, int dataBits, int stopBits, int parity) throws SerialPortException { return setParams(baudRate, dataBits, stopBits, parity, true, true); @@ -204,7 +256,7 @@ public boolean setParams(int baudRate, int dataBits, int stopBits, int parity) t * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -233,9 +285,11 @@ else if(stopBits == 3){ * parameter "PURGE_RXCLEAR | PURGE_TXCLEAR". *
Note: some devices or drivers may not support this function * + * @param flags One or more SerialPort.PURGE_* flag + * * @return If the operation is successfully completed, the method returns true, otherwise false. * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public synchronized boolean purgePort(int flags) throws SerialPortException { checkPortOpened("purgePort()"); @@ -255,10 +309,12 @@ public synchronized boolean purgePort(int flags) throws SerialPortException { * Sent parameter "mask" is additive value, so addition of flags is allowed. * For example if messages about data receipt and CTS and DSR status changing * shall be received, it is required to set the mask - "MASK_RXCHAR | MASK_CTS | MASK_DSR" + * + * @param mask One or more SerialPort.MASK_* value * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public synchronized boolean setEventsMask(int mask) throws SerialPortException { checkPortOpened("setEventsMask()"); @@ -292,7 +348,7 @@ public synchronized boolean setEventsMask(int mask) throws SerialPortException { * * @return Method returns events mask as int type variable. This variable is an additive value * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public int getEventsMask() throws SerialPortException { checkPortOpened("getEventsMask()"); @@ -316,9 +372,11 @@ private int getLinuxMask() { /** * Change RTS line state. Set "true" for switching ON and "false" for switching OFF RTS line * + * @param enabled on/off flag + * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public boolean setRTS(boolean enabled) throws SerialPortException { checkPortOpened("setRTS()"); @@ -328,9 +386,11 @@ public boolean setRTS(boolean enabled) throws SerialPortException { /** * Change DTR line state. Set "true" for switching ON and "false" for switching OFF DTR line * + * @param enabled on/off flag + * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public boolean setDTR(boolean enabled) throws SerialPortException { checkPortOpened("setDTR()"); @@ -340,9 +400,11 @@ public boolean setDTR(boolean enabled) throws SerialPortException { /** * Write byte array to port * + * @param buffer byte[] array to write + * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public boolean writeBytes(byte[] buffer) throws SerialPortException { checkPortOpened("writeBytes()"); @@ -352,9 +414,11 @@ public boolean writeBytes(byte[] buffer) throws SerialPortException { /** * Write single byte to port * + * @param singleByte single byte value to write + * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -366,9 +430,11 @@ public boolean writeByte(byte singleByte) throws SerialPortException { /** * Write String to port * + * @param string String value to write + * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -380,9 +446,12 @@ public boolean writeString(String string) throws SerialPortException { /** * Write String to port * + * @param string String value to write + * @param charsetName valid Charset name, e.g. "UTF-8" * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred + * @throws UnsupportedEncodingException if encoding exception occurred * * @since 2.8.0 */ @@ -394,9 +463,11 @@ public boolean writeString(String string, String charsetName) throws SerialPortE /** * Write int value (in range from 0 to 255 (0x00 - 0xFF)) to port * + * @param singleInt single int value to write + * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -408,9 +479,11 @@ public boolean writeInt(int singleInt) throws SerialPortException { /** * Write int array (in range from 0 to 255 (0x00 - 0xFF)) to port * + * @param buffer int[] array to write + * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -430,7 +503,7 @@ public boolean writeIntArray(int[] buffer) throws SerialPortException { * * @return byte array with "byteCount" length * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public byte[] readBytes(int byteCount) throws SerialPortException { checkPortOpened("readBytes()"); @@ -444,7 +517,7 @@ public byte[] readBytes(int byteCount) throws SerialPortException { * * @return byte array with "byteCount" length converted to String * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -460,7 +533,7 @@ public String readString(int byteCount) throws SerialPortException { * * @return byte array with "byteCount" length converted to Hexadecimal String * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -470,13 +543,14 @@ public String readHexString(int byteCount) throws SerialPortException { } /** - * Read Hex string from port with setted separator (example if separator is "::": FF::0A::FF) + * Read Hex string from port with set separator (example if separator is "::": FF::0A::FF) * * @param byteCount count of bytes for reading + * @param separator the hex string separator, e.g. "::", etc * * @return byte array with "byteCount" length converted to Hexadecimal String * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -502,7 +576,7 @@ public String readHexString(int byteCount, String separator) throws SerialPortEx * * @return String array with "byteCount" length and Hexadecimal String values * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -527,7 +601,7 @@ public String[] readHexStringArray(int byteCount) throws SerialPortException { * * @return int array with values in range from 0 to 255 * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -557,7 +631,7 @@ private void waitBytesWithTimeout(String methodName, int byteCount, int timeout) } } if(timeIsOut){ - throw new SerialPortTimeoutException(portName, methodName, timeout); + throw new SerialPortTimeoutException(this, methodName, timeout); } } @@ -569,8 +643,8 @@ private void waitBytesWithTimeout(String methodName, int byteCount, int timeout) * * @return byte array with "byteCount" length * - * @throws SerialPortException - * @throws SerialPortTimeoutException + * @throws SerialPortException if exception occurred + * @throws SerialPortTimeoutException if timeout exception occurred * * @since 2.0 */ @@ -588,8 +662,8 @@ public byte[] readBytes(int byteCount, int timeout) throws SerialPortException, * * @return byte array with "byteCount" length converted to String * - * @throws SerialPortException - * @throws SerialPortTimeoutException + * @throws SerialPortException if exception occurred + * @throws SerialPortTimeoutException if timeout exception occurred * * @since 2.0 */ @@ -607,8 +681,8 @@ public String readString(int byteCount, int timeout) throws SerialPortException, * * @return byte array with "byteCount" length converted to Hexadecimal String * - * @throws SerialPortException - * @throws SerialPortTimeoutException + * @throws SerialPortException if exception occurred + * @throws SerialPortTimeoutException if timeout exception occurred * * @since 2.0 */ @@ -619,15 +693,16 @@ public String readHexString(int byteCount, int timeout) throws SerialPortExcepti } /** - * Read Hex string from port with setted separator (example if separator is "::": FF::0A::FF) + * Read Hex string from port with set separator (example if separator is "::": FF::0A::FF) * * @param byteCount count of bytes for reading + * @param separator the hex string separator, e.g. "::", etc * @param timeout timeout in milliseconds * * @return byte array with "byteCount" length converted to Hexadecimal String * - * @throws SerialPortException - * @throws SerialPortTimeoutException + * @throws SerialPortException if exception occurred + * @throws SerialPortTimeoutException if timeout exception occurred * * @since 2.0 */ @@ -645,8 +720,8 @@ public String readHexString(int byteCount, String separator, int timeout) throws * * @return String array with "byteCount" length and Hexadecimal String values * - * @throws SerialPortException - * @throws SerialPortTimeoutException + * @throws SerialPortException if exception occurred + * @throws SerialPortTimeoutException if timeout exception occurred * * @since 2.0 */ @@ -664,8 +739,8 @@ public String[] readHexStringArray(int byteCount, int timeout) throws SerialPort * * @return int array with values in range from 0 to 255 * - * @throws SerialPortException - * @throws SerialPortTimeoutException + * @throws SerialPortException if exception occurred + * @throws SerialPortTimeoutException if timeout exception occurred * * @since 2.0 */ @@ -680,7 +755,7 @@ public int[] readIntArray(int byteCount, int timeout) throws SerialPortException * * @return If input buffer is empty null will be returned, else byte array with all data from port * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -698,7 +773,7 @@ public byte[] readBytes() throws SerialPortException { * * @return If input buffer is empty null will be returned, else byte array with all data from port converted to String * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -716,7 +791,7 @@ public String readString() throws SerialPortException { * * @return If input buffer is empty null will be returned, else byte array with all data from port converted to Hex String * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -730,11 +805,13 @@ public String readHexString() throws SerialPortException { } /** - * Read all available bytes from port like a Hex String with setted separator + * Read all available bytes from port like a Hex String with set separator + * + * @param separator the hex string separator, e.g. "::", etc * * @return If input buffer is empty null will be returned, else byte array with all data from port converted to Hex String * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -752,7 +829,7 @@ public String readHexString(String separator) throws SerialPortException { * * @return If input buffer is empty null will be returned, else byte array with all data from port converted to Hex String array * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -770,7 +847,7 @@ public String[] readHexStringArray() throws SerialPortException { * * @return If input buffer is empty null will be returned, else byte array with all data from port converted to int array * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -788,7 +865,7 @@ public int[] readIntArray() throws SerialPortException { * * @return Count of bytes in input buffer or -1 if error occured * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -802,7 +879,7 @@ public int getInputBufferBytesCount() throws SerialPortException { * * @return Count of bytes in output buffer or -1 if error occured * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -815,9 +892,11 @@ public int getOutputBufferBytesCount() throws SerialPortException { * Set flow control mode. For required mode use variables with prefix "FLOWCONTROL_". * Example of hardware flow control mode(RTS/CTS): setFlowControlMode(FLOWCONTROL_RTSCTS_IN | FLOWCONTROL_RTSCTS_OUT); * + * @param mask mask of flow control mode + * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -829,9 +908,9 @@ public boolean setFlowControlMode(int mask) throws SerialPortException { /** * Get flow control mode * - * @return Mask of setted flow control mode + * @return Mask of set flow control mode * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -841,13 +920,13 @@ public int getFlowControlMode() throws SerialPortException { } /** - * Send Break singnal for setted duration + * Send Break singnal for set duration * * @param duration duration of Break signal * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred * * @since 0.8 */ @@ -865,7 +944,7 @@ private int[][] waitEvents() { * * @param methodName method name * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ private void checkPortOpened(String methodName) throws SerialPortException { if(!portOpened){ @@ -882,7 +961,7 @@ private void checkPortOpened(String methodName) throws SerialPortException { *
element 2 - RING line state *
element 3 - RLSD line state * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public int[] getLinesStatus() throws SerialPortException { checkPortOpened("getLinesStatus()"); @@ -894,7 +973,7 @@ public int[] getLinesStatus() throws SerialPortException { * * @return If line is active, method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public boolean isCTS() throws SerialPortException { checkPortOpened("isCTS()"); @@ -911,7 +990,7 @@ public boolean isCTS() throws SerialPortException { * * @return If line is active, method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public boolean isDSR() throws SerialPortException { checkPortOpened("isDSR()"); @@ -928,7 +1007,7 @@ public boolean isDSR() throws SerialPortException { * * @return If line is active, method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public boolean isRING() throws SerialPortException { checkPortOpened("isRING()"); @@ -945,7 +1024,7 @@ public boolean isRING() throws SerialPortException { * * @return If line is active, method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public boolean isRLSD() throws SerialPortException { checkPortOpened("isRLSD()"); @@ -963,7 +1042,9 @@ public boolean isRLSD() throws SerialPortException { * be in charge for handling of occurred events. This method will independently * set the mask in "MASK_RXCHAR" state if it was not set beforehand * - * @throws SerialPortException + * @param listener Event Listener of type SerialPortListener + * + * @throws SerialPortException if exception occurred */ public void addEventListener(SerialPortEventListener listener) throws SerialPortException { addEventListener(listener, MASK_RXCHAR, false); @@ -975,9 +1056,12 @@ public void addEventListener(SerialPortEventListener listener) throws SerialPort * charge for handling of occurred events. Also events mask shall be sent to * this method, to do it use variables with prefix "MASK_" for example "MASK_RXCHAR" * + * @param listener Event Listener of type SerialPortListener + * @param mask SerialPort.MASK_* representing the event mask to listen upon + * * @see #setEventsMask(int) setEventsMask(int mask) * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public void addEventListener(SerialPortEventListener listener, int mask) throws SerialPortException { addEventListener(listener, mask, true); @@ -988,14 +1072,18 @@ public void addEventListener(SerialPortEventListener listener, int mask) throws * to the method. This object shall be properly described, as it will be in * charge for handling of occurred events. Also events mask shall be sent to * this method, to do it use variables with prefix "MASK_" for example "MASK_RXCHAR". If - * overwriteMask == true and mask has been already assigned it value will be rewrited by mask + * overwriteMask == true and mask has been already assigned it value will be rewritten by mask * value, if overwriteMask == false and mask has been already assigned the new mask value will be ignored, * if there is no assigned mask to this serial port the mask value will be used for setting it up in spite of * overwriteMask value * + * @param listener Event Listener of type SerialPortListener + * @param mask SerialPort.MASK_* representing the event mask to listen upon + * @param overwriteMask overwrite mask if already assigned + * * @see #setEventsMask(int) setEventsMask(int mask) * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ private synchronized void addEventListener(SerialPortEventListener listener, int mask, boolean overwriteMask) throws SerialPortException { checkPortOpened("addEventListener()"); @@ -1047,7 +1135,7 @@ private EventThread getNewEventThread() { * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public synchronized boolean removeEventListener() throws SerialPortException { checkPortOpened("removeEventListener()"); @@ -1076,7 +1164,7 @@ public synchronized boolean removeEventListener() throws SerialPortException { * * @return If the operation is successfully completed, the method returns true, otherwise false * - * @throws SerialPortException + * @throws SerialPortException if exception occurred */ public synchronized boolean closePort() throws SerialPortException { checkPortOpened("closePort()"); diff --git a/src/main/java/jssc/SerialPortEvent.java b/src/main/java/jssc/SerialPortEvent.java index e37be380f..b65919d74 100644 --- a/src/main/java/jssc/SerialPortEvent.java +++ b/src/main/java/jssc/SerialPortEvent.java @@ -38,22 +38,67 @@ public class SerialPortEvent { @Deprecated private String portName; - public static final int RXCHAR = 1; - public static final int RXFLAG = 2; - public static final int TXEMPTY = 4; - public static final int CTS = 8; - public static final int DSR = 16; - public static final int RLSD = 32; - public static final int BREAK = 64; - public static final int ERR = 128; - public static final int RING = 256; + /** Deprecated: Use SerialPort.MASK_RXCHAR instead **/ + @Deprecated + public static final int RXCHAR = SerialPort.MASK_RXCHAR; + + /** Deprecated: Use SerialPort.MASK_RXFLAG instead **/ + @Deprecated + public static final int RXFLAG = SerialPort.MASK_RXFLAG; + + /** Deprecated: Use SerialPort.MASK_TXEMPTY instead **/ + @Deprecated + public static final int TXEMPTY = SerialPort.MASK_TXEMPTY; + + /** Deprecated: Use SerialPort.MASK_CTS instead **/ + @Deprecated + public static final int CTS = SerialPort.MASK_CTS; + + /** Deprecated: Use SerialPort.MASK_DSR instead **/ + @Deprecated + public static final int DSR = SerialPort.MASK_DSR; + + /** Deprecated: Use SerialPort.MASK_RLSD instead **/ + @Deprecated + public static final int RLSD = SerialPort.MASK_RLSD; + /** Deprecated: Use SerialPort.MASK_BREAK instead **/ + @Deprecated + public static final int BREAK = SerialPort.MASK_BREAK; + + /** Deprecated: Use SerialPort.MASK_ERR instead **/ + @Deprecated + public static final int ERR = SerialPort.MASK_ERR; + + /** Deprecated: Use SerialPort.MASK_RING instead **/ + @Deprecated + public static final int RING = SerialPort.MASK_RING; + + /** + * Constructs a SerialPortEvent representing a port, event type and event value. + * + * @param port SerialPort object which the event occurred + * @param eventType Can be any value from SerialPort.MASK_* or LinuxEventThread.INTERRUPT_* + * @param eventValue Event value which changes context depending on getEventType() + * + * @see #getEventType() + */ public SerialPortEvent(SerialPort port, int eventType, int eventValue){ this.port = port; this.eventType = eventType; this.eventValue = eventValue; } + /** + * Constructs a SerialPortEvent representing a port, event type and event value. + * Deprecated: Use SerialPortEvent(SerialPort, int, int) instead. + * + * @param portName port which the event occurred + * @param eventType Can be any value from SerialPort.MASK_* or LinuxEventThread.INTERRUPT_* + * @param eventValue Event value which changes context depending on getEventType() + * + * @see #SerialPortEvent(SerialPort, int, int) + */ @Deprecated public SerialPortEvent(String portName, int eventType, int eventValue){ this.portName = portName; @@ -63,6 +108,8 @@ public SerialPortEvent(String portName, int eventType, int eventValue){ /** * Getting the port that set off this event + * + * @return The SerialPort object the event occurred on */ public SerialPort getPort(){ return port; @@ -70,6 +117,8 @@ public SerialPort getPort(){ /** * Getting port name which sent the event + * + * @return The port name the event occurred on */ @Deprecated public String getPortName() { @@ -78,7 +127,10 @@ public String getPortName() { /** * Getting event type + * + * @return The SerialPort.MASK_* event mask */ + @SuppressWarnings("unused") public int getEventType() { return eventType; } @@ -96,71 +148,97 @@ public int getEventType() { *
BREAK - 0 *
RING - state of RING line (0 - OFF, 1 - ON) *
ERR - mask of errors + * @return Event value which changes context depending on getEventType() (see listing) */ + @SuppressWarnings("unused") public int getEventValue() { return eventValue; } /** - * Method returns true if event of type "RXCHAR" is received and otherwise false + * Convenience method to check if getEventType() is SerialPort.MASK_RXCHAR + * @return true or false */ + @SuppressWarnings("unused") public boolean isRXCHAR() { - return eventType == RXCHAR; + return eventType == SerialPort.MASK_RXCHAR; } /** - * Method returns true if event of type "RXFLAG" is received and otherwise false + * Convenience method to check if getEventType() is SerialPort.MASK_RXFLAG + * @return true or false */ + @SuppressWarnings("unused") public boolean isRXFLAG() { - return eventType == RXFLAG; + return eventType == SerialPort.MASK_RXFLAG; } /** - * Method returns true if event of type "TXEMPTY" is received and otherwise false + * Convenience method to check if getEventType() is SerialPort.MASK_TXEMPTY + * @return true or false */ + @SuppressWarnings("unused") public boolean isTXEMPTY() { - return eventType == TXEMPTY; + return eventType == SerialPort.MASK_TXEMPTY; } /** - * Method returns true if event of type "CTS" is received and otherwise false + * Convenience method to check if getEventType() is SerialPort.MASK_CTS + * + * @return true or false */ + @SuppressWarnings("unused") public boolean isCTS() { - return eventType == CTS; + return eventType == SerialPort.MASK_CTS; } /** - * Method returns true if event of type "DSR" is received and otherwise false + * Convenience method to check if getEventType() is SerialPort.MASK_DSR + * + * @return true or false */ + @SuppressWarnings("unused") public boolean isDSR() { - return eventType == DSR; + return eventType == SerialPort.MASK_DSR; } /** - * Method returns true if event of type "RLSD" is received and otherwise false + * Convenience method to check if getEventType() is SerialPort.MASK_RLSD + * + * @return true or false */ + @SuppressWarnings("unused") public boolean isRLSD() { - return eventType == RLSD; + return eventType == SerialPort.MASK_RLSD; } /** - * Method returns true if event of type "BREAK" is received and otherwise false + * Convenience method to check if getEventType() is SerialPort.MASK_RLSD + * + * @return true or false */ + @SuppressWarnings("unused") public boolean isBREAK() { - return eventType == BREAK; + return eventType == SerialPort.MASK_RLSD; } /** - * Method returns true if event of type "ERR" is received and otherwise false + * Convenience method to check if getEventType() is SerialPort.MASK_ERR + * + * @return true or false */ + @SuppressWarnings("unused") public boolean isERR() { - return eventType == ERR; + return eventType == SerialPort.MASK_ERR; } /** - * Method returns true if event of type "RING" is received and otherwise false + * Convenience method to check if getEventType() is SerialPort.MASK_RING + * + * @return true or false */ + @SuppressWarnings("unused") public boolean isRING() { - return eventType == RING; + return eventType == SerialPort.MASK_RING; } } diff --git a/src/main/java/jssc/SerialPortEventListener.java b/src/main/java/jssc/SerialPortEventListener.java index 9a2441aa8..ed731521e 100644 --- a/src/main/java/jssc/SerialPortEventListener.java +++ b/src/main/java/jssc/SerialPortEventListener.java @@ -29,6 +29,10 @@ * @author scream3r */ public interface SerialPortEventListener { - - public abstract void serialEvent(SerialPortEvent serialPortEvent); + /** + * Called when an event fires + * + * @param serialPortEvent SerialPortEvent object containing port, event type and event data + */ + void serialEvent(SerialPortEvent serialPortEvent); } diff --git a/src/main/java/jssc/SerialPortException.java b/src/main/java/jssc/SerialPortException.java index 464c41d3b..ba35e7684 100644 --- a/src/main/java/jssc/SerialPortException.java +++ b/src/main/java/jssc/SerialPortException.java @@ -30,11 +30,17 @@ */ public class SerialPortException extends Exception { final private static long serialVersionUID = 1L; + /** Port already opened **/ final public static String TYPE_PORT_ALREADY_OPENED = "Port already opened"; + /** Port not opened **/ final public static String TYPE_PORT_NOT_OPENED = "Port not opened"; + /** Can't set mask **/ final public static String TYPE_CANT_SET_MASK = "Can't set mask"; + /** Event listener already added **/ final public static String TYPE_LISTENER_ALREADY_ADDED = "Event listener already added"; + /** Event listener thread interrupted **/ final public static String TYPE_LISTENER_THREAD_INTERRUPTED = "Event listener thread interrupted"; + /** Can't remove event listener **/ final public static String TYPE_CANT_REMOVE_LISTENER = "Can't remove event listener, because listener not added"; /** * @since 0.8 @@ -61,10 +67,24 @@ public class SerialPortException extends Exception { */ final public static String TYPE_INCORRECT_SERIAL_PORT = "Incorrect serial port"; + /** Serial port object **/ private SerialPort port; + /** Method name **/ private String methodName; + /** Exception type **/ private String exceptionType; + /** Port name **/ + @Deprecated + private String portName; + + /** + * Constructs a new SerialPortException + * + * @param port Port which the exception occurred on + * @param methodName Method name which the exception occurred on + * @param exceptionType Any SerialPortException.TYPE_* + */ public SerialPortException(SerialPort port, String methodName, String exceptionType) { super("Port name - " + port.getPortName() + "; Method name - " + methodName + "; Exception type - " + exceptionType + "."); this.port = port; @@ -72,9 +92,16 @@ public SerialPortException(SerialPort port, String methodName, String exceptionT this.exceptionType = exceptionType; } - @Deprecated - private String portName; - + /** + * Constructs a new SerialPortException + * Deprecated: Use SerialPortTimeoutException(SerialPort, String, String) instead. + * + * @param portName Port which the exception occurred on + * @param methodName Method name which the exception occurred on + * @param exceptionType Any SerialPortException.TYPE_* + * + * @see #SerialPortException(SerialPort, String, String) + */ @Deprecated public SerialPortException(String portName, String methodName, String exceptionType) { super("Port name - " + portName + "; Method name - " + methodName + "; Exception type - " + exceptionType + "."); @@ -85,29 +112,42 @@ public SerialPortException(String portName, String methodName, String exceptionT /** * Getting port name during operation with which the exception was called + * Deprecated: Use getPort().getName() instead. + * + * @return Port name */ @Deprecated public String getPortName() { - return port.getPortName(); + return port != null ? port.getPortName() : portName; } /** - * Getting the port which threw the exception + * Gets the SerialPort which threw the exception + * + * @return SerialPort object */ + @SuppressWarnings("unused") public SerialPort getPort() { return port; } /** - * Getting method name during execution of which the exception was called + * Gets the method name during execution of which the exception was called + * + * @return Calling method name */ + @SuppressWarnings("unused") public String getMethodName() { return methodName; } /** * Getting exception type + * + * @return a value from SerialPortException.TYPE_* + * or a custom String value if provided */ + @SuppressWarnings("unused") public String getExceptionType() { return exceptionType; } diff --git a/src/main/java/jssc/SerialPortList.java b/src/main/java/jssc/SerialPortList.java index b61ba9be0..becf90713 100644 --- a/src/main/java/jssc/SerialPortList.java +++ b/src/main/java/jssc/SerialPortList.java @@ -76,7 +76,7 @@ private SerialPortList() {} } } - //since 2.1.0 -> Fully rewrited port name comparator + //since 2.1.0 -> Fully rewritten port name comparator private static final Comparator PORTNAMES_COMPARATOR = new Comparator() { @Override diff --git a/src/main/java/jssc/SerialPortTimeoutException.java b/src/main/java/jssc/SerialPortTimeoutException.java index 3be3eb8ab..0e31cc52a 100644 --- a/src/main/java/jssc/SerialPortTimeoutException.java +++ b/src/main/java/jssc/SerialPortTimeoutException.java @@ -30,10 +30,43 @@ */ public class SerialPortTimeoutException extends Exception { final private static long serialVersionUID = 1L; - private String portName; + + /** Serial port object **/ + private SerialPort port; + /** Method name **/ private String methodName; + /** Timeout value **/ private int timeoutValue; + /** Port name **/ + @Deprecated + private String portName; + + /** + * Constructs a new SerialPortTimeoutException + * + * @param port Port which the exception occurred on + * @param methodName Method name which the exception occurred on + * @param timeoutValue Timeout value which the exception occurred on + */ + public SerialPortTimeoutException(SerialPort port, String methodName, int timeoutValue) { + super("Port name - " + port.getPortName() + "; Method name - " + methodName + "; Serial port operation timeout (" + timeoutValue + " ms)."); + this.port = port; + this.methodName = methodName; + this.timeoutValue = timeoutValue; + } + + /** + * Constructs a new SerialPortTimeoutException + * Deprecated: Use SerialPortTimeoutException(SerialPort, String, int) instead. + * + * @param portName Port name which the exception occurred on + * @param methodName Method name which the exception occurred on + * @param timeoutValue Timeout value which the exception occurred on + * + * @see #SerialPortTimeoutException(SerialPort, String, int) + */ + @Deprecated public SerialPortTimeoutException(String portName, String methodName, int timeoutValue) { super("Port name - " + portName + "; Method name - " + methodName + "; Serial port operation timeout (" + timeoutValue + " ms)."); this.portName = portName; @@ -43,22 +76,42 @@ public SerialPortTimeoutException(String portName, String methodName, int timeou /** * Getting port name during operation with which the exception was called + * Deprecated: Use getPort().getName() instead. + * + * @return Port name + */ + @Deprecated + public String getPortName() { + return port != null ? port.getPortName() : portName; + } + + /** + * Gets the SerialPort which threw the exception + * + * @return SerialPort object */ - public String getPortName(){ - return portName; + @SuppressWarnings("unused") + public SerialPort getPort() { + return port; } /** - * Getting method name during execution of which the exception was called + * Gets the method name during execution of which the exception was called + * + * @return Calling method name */ - public String getMethodName(){ + @SuppressWarnings("unused") + public String getMethodName() { return methodName; } /** - * Getting timeout value in millisecond + * Gets timeout value of which the exception was called + * + * @return Calling method name */ - public int getTimeoutValue(){ + @SuppressWarnings("unused") + public int getTimeoutValue() { return timeoutValue; } }