merge: Integrate v2.1 progress into public repository

This pull request integrates the changes planned for the v2.1 release of
OpenDC into the public Github repository in order to sync the progress
of both repositories.

2 files changed, 143 insertions, 0 deletions

diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/spi/TableDetails.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/spi/TableDetails.kt
new file mode 100644
index 00000000..1a9b9ee1
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/spi/TableDetails.kt
@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.opendc.trace.spi
+
+import org.opendc.trace.Table
+import org.opendc.trace.TableColumn
+
+/**
+ * A class used by the [TraceFormat] interface for describing the metadata of a [Table].
+ *
+ * @param columns The available columns in the table.
+ * @param partitionKeys The table columns that act as partition keys for the table.
+ */
+public data class TableDetails(
+    val columns: List<TableColumn<*>>,
+    val partitionKeys: List<TableColumn<*>> = emptyList()
+)
diff --git a/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/spi/TraceFormat.kt b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/spi/TraceFormat.kt
new file mode 100644
index 00000000..f2e610db
--- /dev/null
+++ b/opendc-trace/opendc-trace-api/src/main/kotlin/org/opendc/trace/spi/TraceFormat.kt
@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2021 AtLarge Research
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.opendc.trace.spi
+
+import org.opendc.trace.TableReader
+import org.opendc.trace.TableWriter
+import java.nio.file.Path
+import java.util.*
+
+/**
+ * A service-provider class for parsing trace formats.
+ */
+public interface TraceFormat {
+    /**
+     * The name of the trace format.
+     */
+    public val name: String
+
+    /**
+     * Construct an empty trace at [path].
+     *
+     * @param path The path where to create the empty trace.
+     * @throws IllegalArgumentException If [path] is invalid.
+     * @throws UnsupportedOperationException If the table does not support trace creation.
+     */
+    public fun create(path: Path)
+
+    /**
+     * Return the name of the tables available in the trace at the specified [path].
+     *
+     * @param path The path to the trace.
+     * @return The list of tables available in the trace.
+     */
+    public fun getTables(path: Path): List<String>
+
+    /**
+     * Return the details of [table] in the trace at the specified [path].
+     *
+     * @param path The path to the trace.
+     * @param table The name of the table to obtain the details for.
+     * @throws IllegalArgumentException If [table] does not exist.
+     * @return The [TableDetails] for the specified [table].
+     */
+    public fun getDetails(path: Path, table: String): TableDetails
+
+    /**
+     * Open a [TableReader] for the specified [table].
+     *
+     * @param path The path to the trace to open.
+     * @param table The name of the table to open a [TableReader] for.
+     * @throws IllegalArgumentException If [table] does not exist.
+     * @return A [TableReader] instance for the table.
+     */
+    public fun newReader(path: Path, table: String): TableReader
+
+    /**
+     * Open a [TableWriter] for the specified [table].
+     *
+     * @param path The path to the trace to open.
+     * @param table The name of the table to open a [TableWriter] for.
+     * @throws IllegalArgumentException If [table] does not exist.
+     * @throws UnsupportedOperationException If the format does not support writing.
+     * @return A [TableWriter] instance for the table.
+     */
+    public fun newWriter(path: Path, table: String): TableWriter
+
+    /**
+     * A helper object for resolving providers.
+     */
+    public companion object {
+        /**
+         * A list of [TraceFormat] that are available on this system.
+         */
+        @JvmStatic
+        public val installedProviders: List<TraceFormat> by lazy {
+            val loader = ServiceLoader.load(TraceFormat::class.java)
+            loader.toList()
+        }
+
+        /**
+         * Obtain a [TraceFormat] implementation by [name].
+         */
+        @JvmStatic
+        public fun byName(name: String): TraceFormat? = installedProviders.find { it.name == name }
+    }
+}