Keyple Logging Android Timber JVM Lib

Overview

This library provides a Timber-based implementation of the Keyple logging API. It allows Keyple components to integrate seamlessly with Timber (a popular wrapper around android.util.Log), enabling applications to leverage Timber's enhanced logging infrastructure including Logcat for debugging, crash reporting integration, and customizable logging trees for production monitoring.

Purpose

The Keyple Logging Timber library serves as a bridge between the Keyple logging framework and Timber. By using this implementation, developers can leverage Timber's powerful features to configure and manage logging across their Keyple-based Android applications. This includes better debugging trees for development, crash reporting integration for production, and the ability to customize logging behavior through Timber's extensible tree system.

Usage

To use this library, include it as a dependency in your Android project along with Timber. Initialize Timber in your Application class before using Keyple components:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        if (BuildConfig.DEBUG) {
            Timber.plant(Timber.DebugTree())
        } else {
            // Plant production trees (e.g., CrashlyticsTree)
        }
    }
}

The Keyple logging framework will automatically detect and use this Timber implementation. Logs will be visible in Logcat and routed through your configured Timber trees.

Tag Management

This implementation automatically handles Android's 23-character tag limit by intelligently compressing fully qualified class names. For example, com.mycompany.android.data.repository.UserRepository is transformed to cmadr.UserRepository, preserving both package context and class identification. These tags are passed to Timber, which can further process them through custom trees if needed.

Package Structure

This library contains a single internal package:

• org.eclipse.keyple.logging.android.timber.internal - Internal implementation classes for Timber integration

Important Notes

Internal API: The classes in this library are internal implementation details and should not be used directly by client applications. They are subject to change without notice. Applications should interact with the Keyple logging framework through the public API provided by the core Keyple logging module.

Timber Initialization: Ensure that Timber is properly initialized (planted) before any Keyple logging occurs, typically in your Application's onCreate() method. Without Timber initialization, logs will not be output.

ProGuard/R8: Ensure that logging-related classes are properly configured in your ProGuard/R8 rules to maintain tag generation accuracy in release builds. Add the following rules to your proguard-rules.pro file:

# ============================================================================
# Keyple Logging Timber - ProGuard/R8 Configuration
# ============================================================================

# Service Provider Interface (SPI) - REQUIRED
-keep interface org.eclipse.keyple.core.util.logging.spi.LoggerProvider
-keep class * implements org.eclipse.keyple.core.util.logging.spi.LoggerProvider {
public <init>();
}

# Preserve class names for correct tag generation - CRITICAL
-keepnames class org.eclipse.keyple.**

# If you use logging in your own classes, preserve their names too
# -keepnames class com.yourpackage.** {
#     # Replace with your actual package name
# }

# Timber-specific rules
-dontwarn org.jetbrains.annotations.**
-keep class timber.log.Timber { *; }
-keep class timber.log.Timber$Tree { *; }

# Required attributes
-keepattributes *Annotation*
-keepattributes Signature
-keepattributes InnerClasses
-keepattributes SourceFile,LineNumberTable

# ============================================================================
# Important notes:
# - Do not use -keep instead of -keepnames as it prevents optimization
# - -keepnames only preserves names, not dead code
# - Test in release mode to verify tags are readable
# - Ensure Timber is initialized before any logging occurs
# ============================================================================