Merge pull request #10 from tomtom-international/1.0.12-SNAPSHOT

Added tagging class to tracers

README.md

@@ -86,7 +86,7 @@ The code for that looks like this:
      |  }
      |
      |  companion object {
-(3)  |      private val tracer = Tracer.Factory.create<MyTraceEvents>(this)
+(3)  |      private val tracer = Tracer.Factory.create<MyTraceEvents>()
      |  }
 ```
 
@@ -101,7 +101,9 @@ explains line (3).
 It creates a proxy object `tracer` (also shown in line (2) above), which implements all trace events
 for you. The implementation of the trace event methods sends the serialized functional name and its
 parameters to an event queue. The events on this queue are subsequently consumed by trace events
-consumers, asynchronously.
+consumers, asynchronously. You can add a 'tagging' object to `create`. The class name of the
+object (typically `this`) may be added to log if `@TraceOptions(includeTaggingClass = true)` is
+used.
 
 By default, a logging trace event consumer is enabled, which sends the events to a `Log` method
 that send the message to `stdout` or can be redirected to, for example, Android `Log`.
@@ -159,14 +161,14 @@ such as `INFO`, `DEBUG`, `ERROR`, etc.
 the optional parameter `includeExceptionStackTrace`. This applies to the last argument of an event (if it 
 is a `Throwable` object). By default, a stack trace is included.
 
-#### `@TraceOptions(includeCalledFromFile=true|false)`
+#### `@TraceOptions(includeFileLocation=true|false)`
 
 `@TraceOptions` also offers the option to specify logging the filename and line number of
 the caller of an event. By default, the caller source code location is not provided.
 
-#### `@TraceOptions(includeCalledFromClass=true|false)`
+#### `@TraceOptions(includeTaggingClass=true|false)`
 
-`@TraceOptions` offers the option to add the class that uses the event tracer
+`@TraceOptions` offers the option to add the class passed to `create()` 
 to the log message, or omit that. By default, the caller class is not included.
 
 #### `@TraceOptions(includeEventInterface=true|false)`
@@ -328,7 +330,7 @@ If you wish to define a tracer to *only* log standard messages using `d()` etc.,
 to create (or use) an `TraceEventListener` interface. You can just use this:
 
 ```
-val tracer = Tracer.Factory.createLoggerOnly(this)
+val tracer = Tracer.Factory.createLoggerOnly()
 ```
 
 **Note:** Using the `Log.x` functions on tracers defeats the advantages of using type-safe
@@ -438,6 +440,12 @@ Contributors: Timon Kanters, Jeroen Erik Jensen
 
 ## Release notes
 
+### 1.0.12
+
+* Renamed annotations: `@TraceOptions(includeExceptionStackTrace, includeTaggingClass, includeFileLocation, includeEventInterface)`
+
+* Added ability to add tagging class to tracers.
+
 ### 1.0.11
 
 * Removed restriction that tracers can only be created in a `companion object`. 
@@ -452,7 +460,7 @@ Contributors: Timon Kanters, Jeroen Erik Jensen
 
 ### 1.0.9
 
-* Added `includeCalledFromFile` to `@TraceLoglevel` add the caller filename and line number to the logger.
+* Added `includeFileLocation` to `@TraceLoglevel` add the caller filename and line number to the logger.
 
 ### 1.0.8
 
@@ -502,4 +510,3 @@ understand package names
 ### 1.0.0-1.0.2
 
 * Initial release
-

pom.xml

@@ -21,7 +21,7 @@
 
     <groupId>com.tomtom.kotlin</groupId>
     <artifactId>kotlin-tools</artifactId>
-    <version>1.0.11</version>
+    <version>1.0.12</version>
     <packaging>pom</packaging>
 
     <name>Kotlin Tools</name>

traceevents/pom.xml

@@ -24,7 +24,7 @@
     <parent>
         <groupId>com.tomtom.kotlin</groupId>
         <artifactId>kotlin-tools</artifactId>
-        <version>1.0.11</version>
+        <version>1.0.12</version>
     </parent>
 
     <artifactId>traceevents</artifactId>

traceevents/src/main/java/com/tomtom/kotlin/traceevents/TraceEvent.kt

@@ -22,7 +22,8 @@ import java.time.LocalDateTime
  *
  * @param dateTime Event time.
  * @param logLevel Log level (from [TraceLogLevel] annotation).
- * @param calledFromClass Class logging the event.
+ * @param tracerClassName Class logging the event.
+ * @param taggingClassName Tagging class passed to event, for convenience of debugging.
  * @param interfaceName Interface name, derived from [TraceEventListener].
  * @param stackTraceHolder Throwable from which a stack trace can be produced.
  * @param eventName Function name in interface, which represents the trace event name.
@@ -31,7 +32,8 @@ import java.time.LocalDateTime
 data class TraceEvent(
     val dateTime: LocalDateTime,
     val logLevel: LogLevel,
-    val calledFromClass: String,
+    val tracerClassName: String,
+    val taggingClassName: String,
     val interfaceName: String,
     val stackTraceHolder: Throwable,
     val eventName: String,
@@ -49,7 +51,8 @@ data class TraceEvent(
 
         if (dateTime != other.dateTime) return false
         if (logLevel != other.logLevel) return false
-        if (calledFromClass != other.calledFromClass) return false
+        if (tracerClassName != other.tracerClassName) return false
+        if (taggingClassName != other.taggingClassName) return false
         if (interfaceName != other.interfaceName) return false
         if (stackTraceHolder != other.stackTraceHolder) return false
         if (eventName != other.eventName) return false
@@ -61,7 +64,8 @@ data class TraceEvent(
     override fun hashCode(): Int {
         var result = dateTime.hashCode()
         result = 31 * result + logLevel.hashCode()
-        result = 31 * result + calledFromClass.hashCode()
+        result = 31 * result + tracerClassName.hashCode()
+        result = 31 * result + taggingClassName.hashCode()
         result = 31 * result + interfaceName.hashCode()
         result = 31 * result + stackTraceHolder.hashCode()
         result = 31 * result + eventName.hashCode()

traceevents/src/main/java/com/tomtom/kotlin/traceevents/TraceLogLevel.kt

@@ -24,5 +24,5 @@ import com.tomtom.kotlin.traceevents.TraceLog.LogLevel
  * Default value is [LogLevel.DEBUG].
  */
 @Retention(AnnotationRetention.RUNTIME)
-@Target(AnnotationTarget.FUNCTION)
+@Target(AnnotationTarget.FUNCTION, AnnotationTarget.CLASS)
 annotation class TraceLogLevel(val logLevel: LogLevel)

traceevents/src/main/java/com/tomtom/kotlin/traceevents/TraceOptions.kt

@@ -15,18 +15,20 @@
 package com.tomtom.kotlin.traceevents
 
 /**
- * This annotation can be used to annotate methods in [TraceEventListener].
+ * This annotation can be used to annotate functions in for a trace event listener.
+ * Both interfaces and individual functions can be annotated. Annotations at the function level
+ * override those at the interface level.
  *
  * @param includeExceptionStackTrace Specifies whether a stack trace should be included if the last
  * parameter of the event is derived from [Throwable]. If false, only the exception message is
  * shown.
  * Default value is true.
  *
- * @param includeCalledFromClass Specifies whether owner class of the event definition should be logged
+ * @param includeTaggingClass Specifies whether owner class of the event definition should be logged
  * or not.
  * Default is false.
 
- * @param includeCalledFromFile Specifies whether the filename and line number of the caller
+ * @param includeFileLocation Specifies whether the filename and line number of the caller
  * should be logged or not.
  * Default is false.
  *
@@ -36,10 +38,10 @@ package com.tomtom.kotlin.traceevents
  *
  */
 @Retention(AnnotationRetention.RUNTIME)
-@Target(AnnotationTarget.FUNCTION)
+@Target(AnnotationTarget.FUNCTION, AnnotationTarget.CLASS)
 annotation class TraceOptions(
     val includeExceptionStackTrace: Boolean = true,
-    val includeCalledFromClass: Boolean = false,
-    val includeCalledFromFile: Boolean = false,
+    val includeTaggingClass: Boolean = false,
+    val includeFileLocation: Boolean = false,
     val includeEventInterface: Boolean = false
 )