merge: Introduce schema for trace API (#88)

This pull request updates the OpenDC trace API to support proper specification 
of a schema of the tables exposed by the traces. This functionality makes it easier 
for the API consumer to understand the types exposed by the API.

## Implementation Notes :hammer_and_pick:

* Introduce type system for trace API
* Add benchmarks for odcvm trace format 
* Add benchmarks for Azure trace format
* Add conformance suite for OpenDC trace API 

## External Dependencies :four_leaf_clover:

* N/A

## Breaking API Changes :warning:

* Removal of typed `TableColumn`. Instead, `TableColumn` instances are now 
   used to describe the columns belonging to some table.
* `TableReader` and `TableWriter` do not support accessing arbitrary objects 
   anymore. Instead, only the types supported by the type system are exposed.

1 files changed, 176 insertions, 46 deletions

diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableReader.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableReader.kt
index 8a796e6c..42b1c690 100644
--- a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableReader.kt
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/TableReader.kt
@@ -22,8 +22,12 @@
 
 package org.opendc.trace
 
+import java.time.Duration
+import java.time.Instant
+import java.util.UUID
+
 /**
- * Base class for reading entities from a workload trace table in streaming fashion.
+ * Base class for reading entities from a [Table] in streaming fashion.
  */
 public interface TableReader : AutoCloseable {
     /**
@@ -34,20 +38,15 @@ public interface TableReader : AutoCloseable {
     public fun nextRow(): Boolean
 
     /**
-     * Resolve the index of the specified [column] for this reader.
+     * Resolve the index of the column by its [name].
      *
-     * @param column The column to lookup.
+     * @param name The name of the column to lookup.
      * @return The zero-based index of the column or a negative value if the column is not present in this table.
      */
-    public fun resolve(column: TableColumn<*>): Int
-
-    /**
-     * Determine whether the [TableReader] supports the specified [column].
-     */
-    public fun hasColumn(column: TableColumn<*>): Boolean = resolve(column) >= 0
+    public fun resolve(name: String): Int
 
     /**
-     * Determine whether the specified [column] has a `null` value for the current row.
+     * Determine whether the column with the specified [index] has a `null` value for the current row.
      *
      * @param index The zero-based index of the column to check for a null value.
      * @throws IllegalArgumentException if the column index is not valid for this reader.
@@ -56,15 +55,6 @@ public interface TableReader : AutoCloseable {
     public fun isNull(index: Int): Boolean
 
     /**
-     * Obtain the object value of the column with the specified [index].
-     *
-     * @param index The zero-based index of the column to obtain the value for.
-     * @throws IllegalArgumentException if the column index is not valid for this reader.
-     * @return The object value of the column.
-     */
-    public fun get(index: Int): Any?
-
-    /**
      * Obtain the boolean value of the column with the specified [index].
      *
      * @param index The zero-based index of the column to obtain the value for.
@@ -74,7 +64,7 @@ public interface TableReader : AutoCloseable {
     public fun getBoolean(index: Int): Boolean
 
     /**
-     * Obtain the integer value of the column with the specified [index].
+     * Obtain the boolean value of the column with the specified [index].
      *
      * @param index The zero-based index of the column to obtain the value for.
      * @throws IllegalArgumentException if the column index is not valid for this reader.
@@ -92,6 +82,15 @@ public interface TableReader : AutoCloseable {
     public fun getLong(index: Int): Long
 
     /**
+     * Obtain the float value of the column with the specified [index].
+     *
+     * @param index The zero-based index of the column to obtain the value for.
+     * @throws IllegalArgumentException if the column index is not valid for this reader.
+     * @return The float value of the column or [Float.NaN] if the column is `null`.
+     */
+    public fun getFloat(index: Int): Float
+
+    /**
      * Obtain the double value of the column with the specified [index].
      *
      * @param index The zero-based index of the column to obtain the value for.
@@ -101,62 +100,193 @@ public interface TableReader : AutoCloseable {
     public fun getDouble(index: Int): Double
 
     /**
-     * Determine whether the specified [column] has a `null` value for the current row.
+     * Obtain the [String] value of the column with the specified [index].
      *
-     * @param column The column to lookup.
-     * @throws IllegalArgumentException if the column is not valid for this table.
-     * @return `true` if the column value for the current value has a `null` value, `false` otherwise.
+     * @param index The zero-based index of the column to obtain the value for.
+     * @throws IllegalArgumentException if the column index is not valid for this reader.
+     * @return The [String] value of the column or `null` if the column is `null`.
      */
-    public fun isNull(column: TableColumn<*>): Boolean = isNull(resolve(column))
+    public fun getString(index: Int): String?
 
     /**
-     * Obtain the value of the current column with type [T].
+     * Obtain the [UUID] value of the column with the specified [index].
      *
-     * @param column The column to obtain the value for.
-     * @throws IllegalArgumentException if the column is not valid for this reader.
-     * @return The object value of the column.
+     * @param index The zero-based index of the column to obtain the value for.
+     * @throws IllegalArgumentException if the column index is not valid for this reader.
+     * @return The [UUID] value of the column or `null` if the column is `null`.
+     */
+    public fun getUUID(index: Int): UUID?
+
+    /**
+     * Obtain the [Instant] value of the column with the specified [index].
+     *
+     * @param index The zero-based index of the column to obtain the value for.
+     * @throws IllegalArgumentException if the column index is not valid for this reader.
+     * @return The [Instant] value of the column or `null` if the column is `null`.
+     */
+    public fun getInstant(index: Int): Instant?
+
+    /**
+     * Obtain the [Duration] value of the column with the specified [index].
+     *
+     * @param index The zero-based index of the column to obtain the value for.
+     * @throws IllegalArgumentException if the column index is not valid for this reader.
+     * @return The [Duration] value of the column or `null` if the column is `null`.
+     */
+    public fun getDuration(index: Int): Duration?
+
+    /**
+     * Obtain the value of the column with the specified [index] as [List].
+     *
+     * @param index The zero-based index of the column to obtain the value for.
+     * @param elementType Class representing the Java data type to convert elements of the designated column to.
+     * @throws IllegalArgumentException if the column index is not valid for this reader or this type.
+     * @return The value of the column as `List` or `null` if the column is null.
+     */
+    public fun <T> getList(index: Int, elementType: Class<T>): List<T>?
+
+    /**
+     * Obtain the value of the column with the specified [index] as [Set].
+     *
+     * @param index The zero-based index of the column to obtain the value for.
+     * @param elementType Class representing the Java data type to convert elements of the designated column to.
+     * @throws IllegalArgumentException if the column index is not valid for this reader or this type.
+     * @return The value of the column as `Set` or `null` if the column is null.
+     */
+    public fun <T> getSet(index: Int, elementType: Class<T>): Set<T>?
+
+    /**
+     * Obtain the value of the column with the specified [index] as [Set].
+     *
+     * @param index The zero-based index of the column to obtain the value for.
+     * @param keyType Class representing the Java data type to convert the keys of the designated column to.
+     * @param valueType Class representing the Java data type to convert the values of the designated column to.
+     * @throws IllegalArgumentException if the column index is not valid for this reader or this type.
+     * @return The value of the column as `Map` or `null` if the column is null.
+     */
+    public fun <K, V> getMap(index: Int, keyType: Class<K>, valueType: Class<V>): Map<K, V>?
+
+    /**
+     * Determine whether a column named [name] has a `null` value for the current row.
+     *
+     * @param name The name of the column to lookup.
+     * @throws IllegalArgumentException if the column is not valid for this table.
+     * @return `true` if the column value for the current value has a `null` value, `false` otherwise.
      */
-    public fun <T> get(column: TableColumn<T>): T {
-        // This cast should always succeed since the resolve the index of the typed column
-        @Suppress("UNCHECKED_CAST")
-        return get(resolve(column)) as T
-    }
+    public fun isNull(name: String): Boolean = isNull(resolve(name))
 
     /**
-     * Read the specified [column] as boolean.
+     * Read the column named [name] as boolean.
      *
-     * @param column The column to obtain the value for.
+     * @param name The name of the column to get the value for.
      * @throws IllegalArgumentException if the column is not valid for this reader.
      * @return The boolean value of the column or `false` if the column is `null`.
      */
-    public fun getBoolean(column: TableColumn<Boolean>): Boolean = getBoolean(resolve(column))
+    public fun getBoolean(name: String): Boolean = getBoolean(resolve(name))
 
     /**
-     * Read the specified [column] as integer.
+     * Read the column named [name] as integer.
      *
-     * @param column The column to obtain the value for.
+     * @param name The name of the column to get the value for.
      * @throws IllegalArgumentException if the column is not valid for this reader.
      * @return The integer value of the column or `0` if the column is `null`.
      */
-    public fun getInt(column: TableColumn<Int>): Int = getInt(resolve(column))
+    public fun getInt(name: String): Int = getInt(resolve(name))
 
     /**
-     * Read the specified [column] as long.
+     * Read the column named [name] as long.
      *
-     * @param column The column to obtain the value for.
+     * @param name The name of the column to get the value for
      * @throws IllegalArgumentException if the column is not valid for this reader.
      * @return The long value of the column or `0` if the column is `null`.
      */
-    public fun getLong(column: TableColumn<Long>): Long = getLong(resolve(column))
+    public fun getLong(name: String): Long = getLong(resolve(name))
+
+    /**
+     * Read the column named [name] as float.
+     *
+     * @param name The name of the column to get the value for.
+     * @throws IllegalArgumentException if the column is not valid for this reader.
+     * @return The float value of the column or [Float.NaN] if the column is `null`.
+     */
+    public fun getFloat(name: String): Float = getFloat(resolve(name))
 
     /**
-     * Read the specified [column] as double.
+     * Read the column named [name] as double.
      *
-     * @param column The column to obtain the value for.
+     * @param name The name of the column to get the value for.
      * @throws IllegalArgumentException if the column is not valid for this reader.
      * @return The double value of the column or [Double.NaN] if the column is `null`.
      */
-    public fun getDouble(column: TableColumn<Double>): Double = getDouble(resolve(column))
+    public fun getDouble(name: String): Double = getDouble(resolve(name))
+
+    /**
+     * Read the column named [name] as [String].
+     *
+     * @param name The name of the column to get the value for.
+     * @throws IllegalArgumentException if the column is not valid for this reader.
+     * @return The [String] value of the column or `null` if the column is `null`.
+     */
+    public fun getString(name: String): String? = getString(resolve(name))
+
+    /**
+     * Read the column named [name] as [UUID].
+     *
+     * @param name The name of the column to get the value for.
+     * @throws IllegalArgumentException if the column is not valid for this reader.
+     * @return The [UUID] value of the column or `null` if the column is `null`.
+     */
+    public fun getUUID(name: String): UUID? = getUUID(resolve(name))
+
+    /**
+     * Read the column named [name] as [Instant].
+     *
+     * @param name The name of the column to get the value for.
+     * @throws IllegalArgumentException if the column is not valid for this reader.
+     * @return The [Instant] value of the column or `null` if the column is `null`.
+     */
+    public fun getInstant(name: String): Instant? = getInstant(resolve(name))
+
+    /**
+     * Read the column named [name] as [Duration].
+     *
+     * @param name The name of the column to get the value for.
+     * @throws IllegalArgumentException if the column is not valid for this reader.
+     * @return The [Duration] value of the column or `null` if the column is `null`.
+     */
+    public fun getDuration(name: String): Duration? = getDuration(resolve(name))
+
+    /**
+     * Obtain the value of the column named [name] as [List].
+     *
+     * @param name The name of the column to get the value for.
+     * @param elementType Class representing the Java data type to convert elements of the designated column to.
+     * @throws IllegalArgumentException if the column index is not valid for this reader or this type.
+     * @return The value of the column as `List` or `null` if the column is null.
+     */
+    public fun <T> getList(name: String, elementType: Class<T>): List<T>? = getList(resolve(name), elementType)
+
+    /**
+     * Obtain the value of the column named [name] as [Set].
+     *
+     * @param name The name of the column to get the value for.
+     * @param elementType Class representing the Java data type to convert elements of the designated column to.
+     * @throws IllegalArgumentException if the column index is not valid for this reader or this type.
+     * @return The value of the column as `Set` or `null` if the column is null.
+     */
+    public fun <T> getSet(name: String, elementType: Class<T>): Set<T>? = getSet(resolve(name), elementType)
+
+    /**
+     * Obtain the value of the column named [name] as [Set].
+     *
+     * @param name The name of the column to get the value for.
+     * @param keyType Class representing the Java data type to convert the keys of the designated column to.
+     * @param valueType Class representing the Java data type to convert the values of the designated column to.
+     * @throws IllegalArgumentException if the column index is not valid for this reader or this type.
+     * @return The value of the column as `Map` or `null` if the column is null.
+     */
+    public fun <K, V> getMap(name: String, keyType: Class<K>, valueType: Class<V>): Map<K, V>? =
+        getMap(resolve(name), keyType, valueType)
 
     /**
      * Closes the reader so that no further iteration or data access can be made.