refactor: normalize log and exception messages (#8)

Author: andrei-cristea

CHANGELOG.md

@@ -6,8 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 ### Changed
-- Logging improvement.
+- Normalized logging and error messages using Keyple coding standards.
 - Migrated the CI pipeline from Jenkins to GitHub Actions.
+### Upgraded
+- `keyple-util-java-lib` from `2.4.0` to `2.4.1`
+- `slf4j-api` from `1.7.32` to `1.7.36` (compileOnly)
 
 ## [2.1.0] - 2024-04-12
 ### Changed

plugin/build.gradle.kts

@@ -21,8 +21,8 @@ dependencies {
   implementation("org.jetbrains.kotlin:kotlin-stdlib:1.7.20")
   implementation("org.eclipse.keyple:keyple-common-java-api:2.0.2")
   implementation("org.eclipse.keyple:keyple-plugin-java-api:2.3.2")
-  implementation("org.eclipse.keyple:keyple-util-java-lib:2.4.0")
-  implementation("org.slf4j:slf4j-api:1.7.32")
+  implementation("org.eclipse.keyple:keyple-util-java-lib:2.4.1")
+  compileOnly("org.slf4j:slf4j-api:1.7.36")
 }
 
 ///////////////////////////////////////////////////////////////////////////////

plugin/src/main/kotlin/org/eclipse/keyple/plugin/android/omapi/AbstractAndroidOmapiPluginAdapter.kt

@@ -44,13 +44,15 @@ internal abstract class AbstractAndroidOmapiPluginAdapter<T, V> : AndroidOmapiPl
     return if (seService != null) {
       callback()
     } else {
-      logger.info("Plugin [{}]: connect to SE", name)
+      logger.info("Connecting to OMAPI SE Service")
       connectToSe(context.applicationContext, callback)
     }
   }
 
   override fun searchAvailableReaders(): MutableSet<ReaderSpi> {
-    logger.info("Plugin [{}]: search available readers", name)
+    if (logger.isTraceEnabled) {
+      logger.trace("Searching available readers")
+    }
     val readerSpis = HashSet<ReaderSpi>()
     getNativeReaders()?.forEach { nativeReader ->
       val reader = mapToReader(nativeReader)

plugin/src/main/kotlin/org/eclipse/keyple/plugin/android/omapi/se/AndroidOmapiPluginAdapter.kt

@@ -35,10 +35,7 @@ internal object AndroidOmapiPluginAdapter :
     seService =
         seServiceFactory.connectToSe(
             SEService.OnConnectedListener {
-              logger.info(
-                  "Plugin [{}]: connected, ready to register plugin, OMAPI SEService version: {}",
-                  name,
-                  seService?.version)
+              logger.info("OMAPI SE Service connected [version={}]", seService?.version)
               callback()
             })
   }
@@ -49,8 +46,7 @@ internal object AndroidOmapiPluginAdapter :
 
   override fun mapToReader(nativeReader: android.se.omapi.Reader): ReaderSpi {
     logger.info(
-        "Plugin [{}]: reader available: [{}], is card present: {}",
-        name,
+        "Reader connected [nativeReader={}, isCardPresent={}]",
         nativeReader.name,
         nativeReader.isSecureElementPresent)
     return AndroidOmapiReaderAdapter(

plugin/src/main/kotlin/org/eclipse/keyple/plugin/android/omapi/se/AndroidOmapiReaderAdapter.kt

@@ -40,33 +40,33 @@ internal class AndroidOmapiReaderAdapter(private val nativeReader: Reader, reade
       try {
         openChannel = session?.openBasicChannel(null)
       } catch (e: IOException) {
-        throw ReaderIOException("IOException while opening basic channel.")
+        throw ReaderIOException("Failed to open the basic channel", e)
       } catch (e: SecurityException) {
         throw ReaderIOException(
-            "Error while opening basic channel, DFNAME = " + HexUtil.toHex(aid), e.cause)
+            "Failed to open the basic channel. AID: " + HexUtil.toHex(aid), e.cause)
       }
 
       if (openChannel == null) {
-        throw ReaderIOException("Failed to open a basic channel.")
+        throw ReaderIOException("Failed to open the basic channel")
       }
     } else {
-      logger.info(
-          "Reader [{}]: open logical channel, select application with AID [{}]",
-          name,
-          HexUtil.toHex(aid))
+      if (logger.isDebugEnabled) {
+        logger.debug(
+            "[readerExt={}] Opening card physical channel [aid={}]", name, HexUtil.toHex(aid))
+      }
       try {
         openChannel = session?.openLogicalChannel(aid, isoControlMask)
       } catch (e: IOException) {
-        throw ReaderIOException("IOException while opening logical channel.")
+        throw ReaderIOException("Failed to open the logical channel", e)
       } catch (e: NoSuchElementException) {
-        throw java.lang.IllegalArgumentException("NoSuchElementException: " + HexUtil.toHex(aid), e)
+        throw java.lang.IllegalArgumentException("AID not found: " + HexUtil.toHex(aid), e)
       } catch (e: SecurityException) {
         throw ReaderIOException(
-            "SecurityException while opening logical channel, aid:" + HexUtil.toHex(aid), e.cause)
+            "Failed to open the logical channel. AID: " + HexUtil.toHex(aid), e.cause)
       }
 
       if (openChannel == null) {
-        throw ReaderIOException("Failed to open a logical channel.")
+        throw ReaderIOException("Failed to open the logical channel")
       }
     }
     /* get the FCI and build an ApduResponse */
@@ -92,7 +92,7 @@ internal class AndroidOmapiReaderAdapter(private val nativeReader: Reader, reade
     try {
       session = nativeReader.openSession()
     } catch (e: ReaderIOException) {
-      throw ReaderIOException("IOException while opening physical channel.", e)
+      throw ReaderIOException("Failed to open the physical channel", e)
     }
   }
 
@@ -135,7 +135,9 @@ internal class AndroidOmapiReaderAdapter(private val nativeReader: Reader, reade
     val atr = session?.atr
     return if (atr != null) {
       val sAtr = HexUtil.toHex(atr)
-      logger.info("Reader [{}]: retrieving ATR from session: {}", name, sAtr)
+      if (logger.isDebugEnabled) {
+        logger.debug("[readerExt={}] Retrieving ATR [atr={}]", name, sAtr)
+      }
       sAtr
     } else ""
   }
@@ -147,19 +149,11 @@ internal class AndroidOmapiReaderAdapter(private val nativeReader: Reader, reade
    */
   @Throws(ReaderIOException::class)
   override fun transmitApdu(apduIn: ByteArray): ByteArray {
-    // Initialization
-    if (logger.isTraceEnabled) {
-      logger.trace("Reader [{}]: transmit APDU: {} bytes", name, apduIn.size)
-      logger.trace("Reader [{}]: data in: {}", name, HexUtil.toHex(apduIn))
-    }
     var dataOut = byteArrayOf(0)
     try {
       openChannel.let { dataOut = it?.transmit(apduIn) ?: throw IOException("Channel is not open") }
     } catch (e: IOException) {
-      throw ReaderIOException("Error while transmitting APDU", e)
-    }
-    if (logger.isTraceEnabled) {
-      logger.trace("Reader [{}]: data out: {}", name, HexUtil.toHex(dataOut))
+      throw ReaderIOException("Failed to transmit APDU", e)
     }
     return dataOut
   }

plugin/src/main/kotlin/org/eclipse/keyple/plugin/android/omapi/simalliance/AndroidOmapiPluginAdapter.kt

@@ -33,10 +33,7 @@ internal object AndroidOmapiPluginAdapter :
     seService =
         seServiceFactory.connectToSe(
             SEService.CallBack {
-              logger.info(
-                  "Plugin [{}]: connected, ready to register plugin, OMAPI SEService version: {}",
-                  name,
-                  seService?.version)
+              logger.info("OMAPI SE Service connected [version={}]", seService?.version)
               callback()
             })
   }
@@ -47,8 +44,7 @@ internal object AndroidOmapiPluginAdapter :
 
   override fun mapToReader(nativeReader: org.simalliance.openmobileapi.Reader): ReaderSpi {
     logger.info(
-        "Plugin [{}]: reader available: [{}], is card present: {}",
-        name,
+        "Reader connected [nativeReader={}, isCardPresent={}]",
         nativeReader.name,
         nativeReader.isSecureElementPresent)
     return AndroidOmapiReaderAdapter(

plugin/src/main/kotlin/org/eclipse/keyple/plugin/android/omapi/simalliance/AndroidOmapiReaderAdapter.kt

@@ -43,20 +43,22 @@ internal class AndroidOmapiReaderAdapter(private val nativeReader: Reader, reade
       try {
         openChannel = session?.openBasicChannel(null)
       } catch (e: IOException) {
-        throw ReaderIOException("IOException while opening basic channel.")
+        throw ReaderIOException("Failed to open the basic channel", e)
       } catch (e: ReaderIOException) {
         throw ReaderIOException(
-            "Error while opening basic channel, DFNAME = " + HexUtil.toHex(aid), e.cause)
+            "Failed to communicate with card while opening the basic channel. DF Name: " +
+                HexUtil.toHex(aid),
+            e.cause)
       }
 
       if (openChannel == null) {
-        throw ReaderIOException("Failed to open a basic channel.")
+        throw ReaderIOException("Failed to open the basic channel")
       }
     } else {
-      logger.info(
-          "Reader [{}]: open logical channel, select application with AID [{}]",
-          name,
-          HexUtil.toHex(aid))
+      if (logger.isDebugEnabled) {
+        logger.debug(
+            "[readerExt={}] Opening card physical channel [aid={}]", name, HexUtil.toHex(aid))
+      }
       try {
         // openLogicalChannel of SimAlliance OMAPI is only available for version 3.0+ of the
         // library.
@@ -76,16 +78,16 @@ internal class AndroidOmapiReaderAdapter(private val nativeReader: Reader, reade
               }
             }
       } catch (e: IOException) {
-        throw ReaderIOException("IOException while opening logical channel.", e)
+        throw ReaderIOException("Failed to open the logical channel", e)
       } catch (e: NoSuchElementException) {
-        throw java.lang.IllegalArgumentException("NoSuchElementException: " + HexUtil.toHex(aid), e)
+        throw java.lang.IllegalArgumentException("AID not found: " + HexUtil.toHex(aid), e)
       } catch (e: SecurityException) {
         throw ReaderIOException(
-            "SecurityException while opening logical channel, aid:" + HexUtil.toHex(aid), e.cause)
+            "Failed to open the logical channel. AID:" + HexUtil.toHex(aid), e.cause)
       }
 
       if (openChannel == null) {
-        throw ReaderIOException("Failed to open a logical channel.")
+        throw ReaderIOException("Failed to open the logical channel")
       }
     }
     /* get the FCI and build an ApduResponse */
@@ -110,7 +112,9 @@ internal class AndroidOmapiReaderAdapter(private val nativeReader: Reader, reade
     val atr = session?.atr
     return if (atr != null) {
       val sAtr = HexUtil.toHex(atr)
-      logger.info("Reader [{}]: retrieving ATR from session: {}", name, sAtr)
+      if (logger.isDebugEnabled) {
+        logger.debug("[readerExt={}] Retrieving ATR [atr={}]", name, sAtr)
+      }
       sAtr
     } else ""
   }
@@ -125,7 +129,7 @@ internal class AndroidOmapiReaderAdapter(private val nativeReader: Reader, reade
     try {
       session = nativeReader.openSession()
     } catch (e: ReaderIOException) {
-      throw ReaderIOException("IOException while opening physical channel.", e)
+      throw ReaderIOException("Failed to open the physical channel", e)
     }
   }
 
@@ -166,19 +170,11 @@ internal class AndroidOmapiReaderAdapter(private val nativeReader: Reader, reade
    */
   @Throws(ReaderIOException::class)
   override fun transmitApdu(apduIn: ByteArray): ByteArray {
-    // Initialization
-    if (logger.isTraceEnabled) {
-      logger.trace("Reader [{}]: transmit APDU: {} bytes", name, apduIn.size)
-      logger.trace("Reader [{}]: data in: {}", name, HexUtil.toHex(apduIn))
-    }
     var dataOut = byteArrayOf(0)
     try {
       openChannel.let { dataOut = it?.transmit(apduIn) ?: throw IOException("Channel is not open") }
     } catch (e: IOException) {
-      throw ReaderIOException("Error while transmitting APDU", e)
-    }
-    if (logger.isTraceEnabled) {
-      logger.trace("Reader [{}]: data out: {}", name, HexUtil.toHex(dataOut))
+      throw ReaderIOException("Failed to transmit APDU", e)
     }
     return dataOut
   }