Consistent error messages

Author: manuelbl

java-does-usb/src/main/java/net/codecrete/usb/USB.java

@@ -33,7 +33,9 @@ private static USBDeviceRegistry createInstance() {
         } else if (osName.equals("Linux") && (osArch.equals("amd64") || osArch.equals("aarch64"))) {
             impl = new LinuxUSBDeviceRegistry();
         } else {
-            throw new UnsupportedOperationException(String.format("Java Does USB has no implementation for architecture " + "%s/%s", osName, osArch));
+            throw new UnsupportedOperationException(String.format(
+                    "Java Does USB has no implementation for architecture %s/%s",
+                    osName, osArch));
         }
         return impl;
     }

java-does-usb/src/main/java/net/codecrete/usb/USBControlTransfer.java

@@ -24,6 +24,11 @@
  * @param value       value (value between 0 and 65535, called {@code wValue} in USB specification)
  * @param index       index (value between 0 and 65535, called {@code wIndex} in USB specification).
  */
-public record USBControlTransfer(USBRequestType requestType, USBRecipient recipient, int request, int value,
-                                 int index) {
+public record USBControlTransfer(
+        USBRequestType requestType,
+        USBRecipient recipient,
+        int request,
+        int value,
+        int index
+) {
 }

java-does-usb/src/main/java/net/codecrete/usb/common/CompositeFunction.java

@@ -8,7 +8,7 @@
 package net.codecrete.usb.common;
 
 /**
- * Describes the function of an interface of a composite USB device.
+ * Describes a function of a composite USB device.
  * <p>
  * A composite USB device can have multiple functions, e.g. a mass
  * storage function and a virtual serial port function. Each function

java-does-usb/src/main/java/net/codecrete/usb/common/ConfigurationParser.java

@@ -28,7 +28,7 @@
 public class ConfigurationParser {
 
     /**
-     * Parse a USB configuration descriptor (incl. interface and endpoint descriptors)
+     * Parses a USB configuration descriptor (incl. interface and endpoint descriptors)
      *
      * @param desc configuration descriptor
      * @return parsed configuration data
@@ -97,11 +97,11 @@ public Configuration parse() {
     private void parseHeader() {
         var desc = new ConfigurationDescriptor(descriptor);
         if (CONFIGURATION_DESCRIPTOR_TYPE != desc.descriptorType())
-            throw new USBException("Invalid USB configuration descriptor");
+            throw new USBException("invalid USB configuration descriptor");
 
         var totalLength = desc.totalLength();
         if (descriptor.byteSize() != totalLength)
-            throw new USBException("Invalid USB configuration descriptor length");
+            throw new USBException("invalid USB configuration descriptor (invalid length)");
 
         configuration = new Configuration(desc.configurationValue(), desc.attributes(), desc.maxPower());
     }

java-does-usb/src/main/java/net/codecrete/usb/common/EndpointInputStream.java

@@ -22,12 +22,12 @@
  * Input stream for bulk endpoints – optimized for high throughput.
  *
  * <p>
- * Multiple asynchronous transfer are submitted to achieve a good
+ * Multiple asynchronous transfers are submitted to achieve a good
  * degree of concurrency between the USB communication handled by the operating
  * system and the consuming application code.
  * </p>
  * <p>
- * For thread synchronization (between the background thread handling IO completion
+ * For thread synchronization (between the background thread handling IO completions
  * and the consuming application thread) a blocking queue is used. When an transfer
  * completes, the background thread adds it to the queue. The consuming code
  * waits for the next item in the queue.
@@ -178,7 +178,7 @@ private void receiveMoreData() throws IOException {
 
                 // check for error
                 if (currentTransfer.resultCode() != 0)
-                    device.throwOSException(currentTransfer.resultCode(), "error reading from endpoint %d",
+                    device.throwOSException(currentTransfer.resultCode(), "error occurred while reading from endpoint %d",
                             endpointNumber);
 
             } while (currentTransfer.resultSize() <= 0);

java-does-usb/src/main/java/net/codecrete/usb/common/EndpointOutputStream.java

@@ -40,7 +40,7 @@ public abstract class EndpointOutputStream extends OutputStream {
     protected USBDeviceImpl device;
     protected final int endpointNumber;
     protected final Arena arena;
-    // Endpoint's packet size
+    // Endpoint packet size
     private final int packetSize;
     // Transfer size (multiple of packet size)
     private final int transferSize;
@@ -228,7 +228,7 @@ private Transfer waitForAvailableTransfer() {
                 var result = transfer.resultCode();
                 if (result != 0 && !hasError) {
                     transfer.setResultCode(0);
-                    device.throwOSException(result, "error writing to endpoint %d", endpointNumber);
+                    device.throwOSException(result, "error occurred while transmitting to endpoint %d", endpointNumber);
                 }
 
                 return transfer;
@@ -256,6 +256,6 @@ protected void configureEndpoint() {
 
     private void checkIsOpen() throws IOException {
         if (isClosed())
-            throw new IOException("Bulk endpoint output stream has been closed");
+            throw new IOException("endpoint output stream has been closed");
     }
 }

java-does-usb/src/main/java/net/codecrete/usb/common/TransferCompletion.java

@@ -16,8 +16,8 @@ public interface TransferCompletion {
     /**
      * Called when the asynchronous transfer has completed.
      * <p>
-     * When this function has been called, {@link Transfer#resultCode} and
-     * {@link Transfer#resultSize} have been filled in.
+     * When this function has been called, {@link Transfer#resultSize()} and
+     * {@link Transfer#resultSize()} have been filled in.
      * </p>
      * <p>
      * Since there is a single background task calling all completion functions,

java-does-usb/src/main/java/net/codecrete/usb/common/USBDeviceImpl.java

@@ -21,7 +21,7 @@
 public abstract class USBDeviceImpl implements USBDevice {
 
     /**
-     * Operation-specific device ID used for {@link #equals(Object)} and {@link #hashCode()}.
+     * Operating system-specific device ID used for {@link #equals(Object)} and {@link #hashCode()}.
      * <p>
      * Can be a String instance (such as a file path) or a Long instance (such as an internal ID).
      * It only needs to be valid for the duration the device is connected.
@@ -79,7 +79,7 @@ public void attachStandardDrivers() {
 
     protected void checkIsOpen() {
         if (!isOpen())
-            throw new USBException("The device needs to be open to call this method");
+            throw new USBException("device needs to be opened first for this operation");
     }
 
     @Override
@@ -221,7 +221,7 @@ public void setClaimed(int interfaceNumber, boolean claimed) {
                 return;
             }
         }
-        throw new USBException("Internal error (interface not found)");
+        throw new USBException("internal error (interface not found)");
     }
 
     @Override
@@ -232,11 +232,11 @@ public USBInterfaceImpl getInterface(int interfaceNumber) {
     public USBInterfaceImpl getInterfaceWithCheck(int interfaceNumber, boolean isClaimed) {
         var intf = getInterface(interfaceNumber);
         if (intf == null)
-            throw new USBException(String.format("Invalid interface number: %d", interfaceNumber));
+            throw new USBException(String.format("invalid interface number: %d", interfaceNumber));
         if (isClaimed && !intf.isClaimed()) {
-            throw new USBException(String.format("Interface %d has not been claimed", interfaceNumber));
+            throw new USBException(String.format("interface %d must be claimed first", interfaceNumber));
         } else if (!isClaimed && intf.isClaimed()) {
-            throw new USBException(String.format("Interface %d has already been claimed", interfaceNumber));
+            throw new USBException(String.format("interface %d has already been claimed", interfaceNumber));
         }
         return intf;
     }
@@ -292,7 +292,9 @@ protected void throwInvalidEndpointException(USBDirection direction, int endpoin
             transferTypeDesc = transferType1.name();
         else
             transferTypeDesc = String.format("%s or %s", transferType1.name(), transferType2.name());
-        throw new USBException(String.format("Endpoint number %d does not exist, is not part of a claimed interface " + "or is not valid for %s transfer in %s direction", endpointNumber, transferTypeDesc, direction.name()));
+        throw new USBException(String.format(
+                "endpoint number %d does not exist, is not part of a claimed interface or is not valid for %s transfer in %s direction",
+                endpointNumber, transferTypeDesc, direction.name()));
     }
 
     protected int getInterfaceNumber(USBDirection direction, int endpointNumber) {
@@ -337,8 +339,8 @@ protected void waitForTransfer(Transfer transfer, int timeout, USBDirection dire
             if (hasTimedOut && transfer.resultCode() == 0) {
                 abortTransfers(direction, endpointNumber);
                 waitNoTimeout(transfer);
-                throw new USBTimeoutException(getOperationDescription(direction, endpointNumber) + "aborted due to " +
-                        "timeout");
+                throw new USBTimeoutException(getOperationDescription(direction, endpointNumber)
+                        + "aborted due to timeout");
             }
         }
 
@@ -381,9 +383,9 @@ private static boolean waitWithTimeout(Transfer transfer, int timeout) {
 
     protected static String getOperationDescription(USBDirection direction, int endpointNumber) {
         if (endpointNumber == 0) {
-            return "Control transfer";
+            return "control transfer";
         } else {
-            return String.format("Transfer %s on endpoint %d", direction.name(), endpointNumber);
+            return String.format("transfer %s on endpoint %d", direction.name(), endpointNumber);
         }
 
     }

java-does-usb/src/main/java/net/codecrete/usb/common/USBDeviceRegistry.java

@@ -104,8 +104,8 @@ protected void emitOnDeviceDisconnected(USBDevice device) {
             onDeviceDisconnectedHandler.accept(device);
 
         } catch (Exception e) {
-            System.err.println("Warning: [JavaDoesUSB] unhandled exception in 'onDeviceDisconnected' handler - " +
-                    "ignoring");
+            System.err.println(
+                    "Warning: [JavaDoesUSB] unhandled exception in 'onDeviceDisconnected' handler - ignoring");
             e.printStackTrace(System.err);
         }
     }
@@ -136,7 +136,7 @@ protected void startDeviceMonitor(Runnable monitorTask) {
         }
 
         if (failureCause != null)
-            throw new USBException("Initial device enumeration has failed", failureCause);
+            throw new USBException("initial device enumeration has failed", failureCause);
     }
 
     /**

java-does-usb/src/main/java/net/codecrete/usb/linux/LinuxAsyncTask.java

@@ -253,7 +253,7 @@ synchronized void submitTransfer(LinuxUSBDevice device, int endpointAddress, USB
             if (IO.ioctl(device.fileDescriptor(), SUBMITURB, urb, errorState) < 0) {
                 var action = endpointAddress >= 128 ? "reading from" : "writing to";
                 var endpoint = endpointAddress == 0 ? "control endpoint" : String.format("endpoint %d", endpointAddress);
-                throwLastError(errorState, "failed %s %s", action, endpoint);
+                throwLastError(errorState, "error occurred while %s %s", action, endpoint);
             }
         }
     }
@@ -310,7 +310,7 @@ synchronized void abortTransfers(LinuxUSBDevice device, byte endpointAddress) {
                 if (IO.ioctl(fd, DISCARDURB, urb, errorState) < 0) {
                     // ignore EINVAL; it occurs if the URB has completed at the same time
                     if (Linux.getErrno(errorState) != errno.EINVAL())
-                        throwLastError(errorState, "failed to abort transfer");
+                        throwLastError(errorState, "error occurred while aborting transfer");
                 }
             }
         }