From 924bd97ad41054c33f535d968653ea29503cb38a Mon Sep 17 00:00:00 2001 From: hedgecrw85 Date: Fri, 3 Jan 2020 13:50:55 -0600 Subject: [PATCH] New SerialPortMessageListenerWithExceptions to allow users to handle event-based exceptions --- .../com/fazecast/jSerialComm/SerialPort.java | 18 ++++--- .../SerialPortDataListenerWithExceptions.java | 2 +- ...rialPortMessageListenerWithExceptions.java | 47 +++++++++++++++++++ 3 files changed, 59 insertions(+), 8 deletions(-) create mode 100644 src/main/java/com/fazecast/jSerialComm/SerialPortMessageListenerWithExceptions.java diff --git a/src/main/java/com/fazecast/jSerialComm/SerialPort.java b/src/main/java/com/fazecast/jSerialComm/SerialPort.java index db26ae2..3b836ed 100644 --- a/src/main/java/com/fazecast/jSerialComm/SerialPort.java +++ b/src/main/java/com/fazecast/jSerialComm/SerialPort.java @@ -2,10 +2,10 @@ * SerialPort.java * * Created on: Feb 25, 2012 - * Last Updated on: Nov 04, 2019 + * Last Updated on: Jan 03, 2020 * Author: Will Hedgecock * - * Copyright (C) 2012-2019 Fazecast, Inc. + * Copyright (C) 2012-2020 Fazecast, Inc. * * This file is part of jSerialComm. * @@ -50,7 +50,7 @@ import java.util.Date; public final class SerialPort { // Static initializer loads correct native library for this machine - private static final String versionString = "2.5.3"; + private static final String versionString = "2.5.4"; private static volatile boolean isAndroid = false; private static volatile boolean isUnixBased = false; private static volatile boolean isWindows = false; @@ -726,20 +726,22 @@ public final class SerialPort *

* Calling this function enables event-based serial port callbacks to be used instead of, or in addition to, direct serial port read/write calls or the {@link java.io.InputStream}/{@link java.io.OutputStream} interface. *

- * The parameter passed into this method must be an implementation of either {@link SerialPortDataListener}, {@link SerialPortDataListenerWithExceptions}, {@link SerialPortPacketListener}, or {@link SerialPortMessageListener}. - * The {@link SerialPortMessageListener} interface should be used if you plan to use event-based reading of delimited data messages over the serial port. + * The parameter passed into this method must be an implementation of either {@link SerialPortDataListener}, {@link SerialPortDataListenerWithExceptions}, + * {@link SerialPortPacketListener}, {@link SerialPortMessageListener} or {@link SerialPortMessageListenerWithExceptions}. + * The {@link SerialPortMessageListener} or {@link SerialPortMessageListenerWithExceptions} interface should be used if you plan to use event-based reading of delimited data messages over the serial port. * The {@link SerialPortPacketListener} interface should be used if you plan to use event-based reading of full data packets over the serial port. * Otherwise, the simpler {@link SerialPortDataListener} or {@link SerialPortDataListenerWithExceptions} may be used. *

* Only one listener can be registered at a time; however, that listener can be used to detect multiple types of serial port events. - * Refer to {@link SerialPortDataListener}, {@link SerialPortDataListenerWithExceptions}, {@link SerialPortPacketListener}, and {@link SerialPortMessageListener} for more information. + * Refer to {@link SerialPortDataListener}, {@link SerialPortDataListenerWithExceptions}, {@link SerialPortPacketListener}, {@link SerialPortMessageListener}, and {@link SerialPortMessageListenerWithExceptions} for more information. * - * @param listener A {@link SerialPortDataListener}, {@link SerialPortDataListenerWithExceptions}, {@link SerialPortPacketListener}, or {@link SerialPortMessageListener} implementation to be used for event-based serial port communications. + * @param listener A {@link SerialPortDataListener}, {@link SerialPortDataListenerWithExceptions}, {@link SerialPortPacketListener}, {@link SerialPortMessageListener}, or {@link SerialPortMessageListenerWithExceptions} implementation to be used for event-based serial port communications. * @return Whether the listener was successfully registered with the serial port. * @see SerialPortDataListener * @see SerialPortDataListenerWithExceptions * @see SerialPortPacketListener * @see SerialPortMessageListener + * @see SerialPortMessageListenerWithExceptions */ public final boolean addDataListener(SerialPortDataListener listener) { @@ -1303,6 +1305,8 @@ public final class SerialPort isListening = false; if (userDataListener instanceof SerialPortDataListenerWithExceptions) ((SerialPortDataListenerWithExceptions)userDataListener).catchException(e); + else if (userDataListener instanceof SerialPortMessageListenerWithExceptions) + ((SerialPortMessageListenerWithExceptions)userDataListener).catchException(e); } } isListening = false; diff --git a/src/main/java/com/fazecast/jSerialComm/SerialPortDataListenerWithExceptions.java b/src/main/java/com/fazecast/jSerialComm/SerialPortDataListenerWithExceptions.java index b734e12..948d7d7 100644 --- a/src/main/java/com/fazecast/jSerialComm/SerialPortDataListenerWithExceptions.java +++ b/src/main/java/com/fazecast/jSerialComm/SerialPortDataListenerWithExceptions.java @@ -27,7 +27,7 @@ package com.fazecast.jSerialComm; /** * This interface must be implemented to enable simple event-based serial port I/O with a custom Exception callback. - * + * * @author Will Hedgecock <will.hedgecock@fazecast.com> * @version 2.5.4 * @see com.fazecast.jSerialComm.SerialPortDataListener diff --git a/src/main/java/com/fazecast/jSerialComm/SerialPortMessageListenerWithExceptions.java b/src/main/java/com/fazecast/jSerialComm/SerialPortMessageListenerWithExceptions.java new file mode 100644 index 0000000..a5479ee --- /dev/null +++ b/src/main/java/com/fazecast/jSerialComm/SerialPortMessageListenerWithExceptions.java @@ -0,0 +1,47 @@ +/* + * SerialPortMessageListenerWithExceptions.java + * + * Created on: Jan 03, 2020 + * Last Updated on: Jan 03, 2020 + * Author: Will Hedgecock + * + * Copyright (C) 2012-2020 Fazecast, Inc. + * + * This file is part of jSerialComm. + * + * jSerialComm is free software: you can redistribute it and/or modify + * it under the terms of either the Apache Software License, version 2, or + * the GNU Lesser General Public License as published by the Free Software + * Foundation, version 3 or above. + * + * jSerialComm is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + * + * You should have received a copy of both the GNU Lesser General Public + * License and the Apache Software License along with jSerialComm. If not, + * see and . + */ + +package com.fazecast.jSerialComm; + +/** + * This interface must be implemented to enable delimited message reads using event-based serial port I/O with a custom Exception callback. + *

+ * Note: Using this interface will negate any serial port read timeout settings since they make no sense in an asynchronous context. + * + * @author Will Hedgecock <will.hedgecock@fazecast.com> + * @version 2.5.4 + * @see com.fazecast.jSerialComm.SerialPortMessageListener + * @see com.fazecast.jSerialComm.SerialPortDataListener + * @see java.util.EventListener + */ +public interface SerialPortMessageListenerWithExceptions extends SerialPortMessageListener +{ + /** + * Must be overridden to handle any Java exceptions that occur asynchronously in this data listener. + * + * @param e An {@link Exception} object containing information about the exception that occurred. + */ + public abstract void catchException(Exception e); +}