Move Entities from trip to timeseries

GitOrigin-RevId: e2f2faabe8c8ced5f4d52c73ae708925429b95f9

Author: ex0ns

src/main/scala/io/sqooba/oss/timeseries/entity/EntityParser.scala

@@ -0,0 +1,41 @@
+package io.sqooba.oss.timeseries.entity
+
+import io.sqooba.oss.timeseries.labels.{LabelUnitMapper, TsLabel}
+
+import scala.annotation.implicitNotFound
+import scala.util.{Failure, Success, Try}
+
+/** Encapsulates the parsing logic for [[TsLabel]], [[TsId]] and
+  * [[TimeSeriesEntityId]]. It lets the user provide their own mapping from string
+  * keys to entities and to units.
+  */
+@implicitNotFound("Cannot parse entities and/or units for TsId/TsLabel because no parser was defined.")
+trait EntityParser extends LabelUnitMapper {
+
+  /** Parse the unit of a TsLabel from the given string key.
+    *
+    * @return an option containing the string representation of the unit
+    */
+  def deriveUnit(in: TsLabel): Option[String]
+
+  /** Parse the key prefix of a TsId from the given string key.
+    *
+    * @return a TsKeyPrefix or a Failure
+    */
+  def parseKeyPrefix(string: String): Try[TsKeyPrefix]
+}
+
+object EntityParser {
+
+  /** Default parser that returns [[GenericKeyPrefix]]es and no units. */
+  val default: EntityParser = new EntityParser {
+
+    override def deriveUnit(in: TsLabel): Option[String] = None
+
+    override def parseKeyPrefix(string: String): Try[TsKeyPrefix] = Success(GenericKeyPrefix(string))
+
+  }
+
+  val hexEntityParser: EntityParser = default
+
+}

src/main/scala/io/sqooba/oss/timeseries/entity/TimeSeriesEntityId.scala

@@ -0,0 +1,53 @@
+package io.sqooba.oss.timeseries.entity
+
+import io.sqooba.oss.timeseries.labels.TsLabel
+
+import scala.util.Try
+
+trait TimeSeriesEntityId {
+
+  /**
+    * @return the key prefix for the implementing identifier.
+    */
+  def keyPrefix: TsKeyPrefix
+
+  /**
+    * @return the internal identification number of whatever the implementor identifies.
+    */
+  def id: Long
+
+  /**
+    * @param signal the name of the sensor we want to build the TSDB identifier for
+    * @return the full key identifying a time series in the TSDB.
+    */
+  // TODO: the use of this function probably causes AnyVal implementations to require an instantiation.
+  // At the moment we mostly care about correctness, not performance, but we need to keep it in mind.
+  // If at some point we want to do things allocation-free, have a look at
+  // https://docs.scala-lang.org/overviews/core/value-classes.html
+  // under the extension methods paragraph
+  def buildTimeseriesID(signal: TsLabel): TsId
+
+  /**
+    *  Gets the entity Id, formatted as PREFIX_ID
+    */
+  def formatted: String
+
+}
+
+abstract class GenericEntityId(override val id: Long, override val keyPrefix: TsKeyPrefix) extends TimeSeriesEntityId {
+  override def buildTimeseriesID(signal: TsLabel): TsId = GenericTsId(this, signal)
+  override val formatted: String                        = s"${keyPrefix.prefix}${GenericTsId.prefixSeparator}$id"
+}
+
+case class TripEntityId(id: Long, keyPrefix: TsKeyPrefix) extends TimeSeriesEntityId {
+  override def buildTimeseriesID(signal: TsLabel): TsId = TripTsId(this, signal)
+  override val formatted: String                        = s"${keyPrefix.prefix}${TripTsId.prefixSeparator}$id"
+}
+
+object TimeSeriesEntityId {
+
+  /** Builds a [[TimeSeriesEntityId]] from a given prefix and id. */
+  def from(prefix: String, id: Long)(implicit entityParser: EntityParser): Try[TimeSeriesEntityId] =
+    entityParser.parseKeyPrefix(prefix).map(_.toEntityId(id))
+
+}

src/main/scala/io/sqooba/oss/timeseries/entity/TsId.scala

@@ -0,0 +1,83 @@
+package io.sqooba.oss.timeseries.entity
+
+import io.sqooba.oss.timeseries.labels.TsLabel
+
+import scala.util.Try
+
+trait TsId {
+  val entityId: TimeSeriesEntityId
+  val label: TsLabel
+  val id: String
+}
+
+/** Identifies a single materialized time series.
+  *
+  * @param entityId An entity which has time series data
+  * @param label    The label of the time series (e.g sensor data)
+  */
+case class TripTsId(entityId: TimeSeriesEntityId, label: TsLabel) extends TsId {
+  import TripTsId._
+
+  /** Formats the [[TsId]] into a string of the format: LABEL-PREFIX_ID */
+  override val id: String = s"${label.value}$keySeparator${entityId.formatted}"
+}
+
+object TripTsId {
+
+  val keySeparator    = "-"
+  val prefixSeparator = "_"
+
+  /** Tries to construct a [[TsId]] from a raw string representation. By using the
+    * given entityParser it will try to parse the entity type and unit of the label.
+    *
+    * The label is a string (anything is accepted).
+    * The idRaw is in the format PREFIX_ID.
+    *   - PREFIX must be a known prefix, by the given entityParser
+    *   - ID must be a number
+    */
+  def from(label: String, idRaw: String)(implicit entityParser: EntityParser): Try[TsId] = {
+    val idTokens = idRaw.split(prefixSeparator)
+
+    for {
+      idLong <- Try(idTokens(1).toLong)
+      id     <- TimeSeriesEntityId.from(idTokens(0), idLong)
+    } yield TripTsId(id, TsLabel(label))
+  }
+
+}
+
+/** Identifies a single materialized time series.
+  *
+  * @param entityId An entity which has time series data
+  * @param label    The label of the time series (e.g sensor data)
+  */
+case class GenericTsId(entityId: TimeSeriesEntityId, label: TsLabel) extends TsId {
+  import GenericTsId._
+
+  /** Formats the [[TsId]] into a string of the format: LABEL-PREFIX_ID */
+  override val id: String = s"${label.value}$keySeparator${entityId.formatted}"
+}
+
+object GenericTsId {
+
+  val keySeparator    = "-"
+  val prefixSeparator = "_"
+
+  /** Tries to construct a [[TsId]] from a raw string representation. By using the
+    * given entityParser it will try to parse the entity type and unit of the label.
+    *
+    * The label is a string (anything is accepted).
+    * The idRaw is in the format PREFIX_ID.
+    *   - PREFIX must be a known prefix, by the given entityParser
+    *   - ID must be a number
+    */
+  def from(label: String, idRaw: String)(implicit entityParser: EntityParser): Try[TsId] = {
+    val idTokens = idRaw.split(prefixSeparator)
+
+    for {
+      idLong <- Try(idTokens(1).toLong)
+      id     <- TimeSeriesEntityId.from(idTokens(0), idLong)
+    } yield GenericTsId(id, TsLabel(label))
+  }
+}
+

src/main/scala/io/sqooba/oss/timeseries/entity/TsKeyPrefix.scala

@@ -0,0 +1,19 @@
+package io.sqooba.oss.timeseries.entity
+
+/**
+  * Represents a key prefix to distinguish between different types of entities for which
+  * data is stored
+  */
+trait TsKeyPrefix {
+
+  val prefix: String
+
+  override def toString: String = prefix
+
+  def toEntityId(id: Long): TimeSeriesEntityId
+}
+
+case class GenericKeyPrefix(prefix: String) extends TsKeyPrefix {
+
+  def toEntityId(id: Long): TimeSeriesEntityId = new GenericEntityId(id, this) {}
+}

src/main/scala/io/sqooba/oss/timeseries/labels/LabelUnitMapper.scala

@@ -0,0 +1,19 @@
+package io.sqooba.oss.timeseries.labels
+
+import scala.annotation.implicitNotFound
+
+/**
+  * Provide a mapping from label to units:
+  * Implementations may provide any logic (either through a static mapping or deriving it from the label itself)
+  * to return an optional unit for a given label.
+  */
+@implicitNotFound("Cannot derive units for TsLabel because no LabelUnitMapper was defined.")
+trait LabelUnitMapper {
+
+  /**
+    * @param in the label for which the unit should be determined
+    * @return the unit corresponding to this label, if any can be derived.
+    */
+  def deriveUnit(in: TsLabel): Option[String]
+
+}

src/main/scala/io/sqooba/oss/timeseries/labels/TsLabel.scala

@@ -0,0 +1,13 @@
+package io.sqooba.oss.timeseries.labels
+
+/** A time series label.
+  *
+  * Units can be inferred by specifying the (implicit) LabelUnitMapper
+  */
+case class TsLabel(value: String) {
+
+  def unit(implicit unitMapper: LabelUnitMapper): Option[String] = unitMapper.deriveUnit(this)
+
+  // A label should never contain a key separator, since it would break the formatting
+  // require(!value.contains(TsId.keySeparator))
+}

src/test/scala/io/sqooba/oss/timeseries/entity/GenericTsIdSpec.scala

@@ -0,0 +1,26 @@
+package io.sqooba.oss.timeseries.entity
+
+import io.sqooba.oss.timeseries.labels.TsLabel
+import org.scalatest.FlatSpec
+import org.scalatest.matchers.should.Matchers
+
+import scala.util.{Failure, Success}
+
+class GenericTsIdSpec extends FlatSpec with Matchers {
+
+  implicit val parser: EntityParser = fruitParser
+
+  "TsId.from" should "be parsable from a string" in {
+    GenericTsId.from("test", "ba_1") should be(Success(GenericTsId(BananaId(1L), TsLabel("test"))))
+
+    GenericTsId.from("test_2", "ch_2") should be(Success(GenericTsId(CherryId(2L), TsLabel("test_2"))))
+  }
+
+  it should "not be parsable if prefix is unknown" in {
+    GenericTsId.from("test_2", "does_not_exist_2") shouldBe a[Failure[_]]
+  }
+
+  it should "not be parsable if id is malformed" in {
+    GenericTsId.from("test_2", "t_malformed_id") shouldBe a[Failure[_]]
+  }
+}

src/test/scala/io/sqooba/oss/timeseries/entity/TimeSeriesEntityIdSpec.scala

@@ -0,0 +1,33 @@
+package io.sqooba.oss.timeseries.entity
+
+import io.sqooba.oss.timeseries.labels.TsLabel
+import org.scalatest.FlatSpec
+import org.scalatest.matchers.should.Matchers
+
+import scala.util.Failure
+
+class TimeSeriesEntityIdSpec extends FlatSpec with Matchers {
+
+  implicit val parser: EntityParser = fruitParser
+
+  "TimeSeriesEntity" should "return the correct TSDB identification string" in {
+    BananaId(666).buildTimeseriesID(TsLabel("bob")).id should be("bob-ba_666")
+  }
+
+  "TimeSeriesEntity.from" should "be able to parse a fruit id" in {
+    TimeSeriesEntityId.from("ch", 111).get shouldBe CherryId(111L)
+  }
+
+  it should "be built from a prefix and an id" in {
+    TimeSeriesEntityId.from("ap", 2).get shouldBe AppleId(2L)
+  }
+
+  it should "not be created from unknown prefix" in {
+    ('A' to 'z')
+      .filter(character => character != 'w' && character != 't')
+      .foreach { character =>
+        TimeSeriesEntityId.from(character.toString, 2) shouldBe a[Failure[_]]
+      }
+  }
+
+}

src/test/scala/io/sqooba/oss/timeseries/entity/TsLabelSpec.scala

@@ -0,0 +1,66 @@
+package io.sqooba.oss.timeseries.entity
+
+import io.sqooba.oss.timeseries.labels.TsLabel
+import org.scalatest.flatspec.AnyFlatSpec
+import org.scalatest.matchers.should.Matchers
+
+import scala.util.{Failure, Try}
+
+class TsLabelSpec extends AnyFlatSpec with Matchers {
+
+  // scalastyle:off non.ascii.character.disallowed
+
+  "TsLabel.fromString" should "be derived from label name" in {
+
+    implicit val physicsParser: EntityParser = new EntityParser {
+      private val AMPERE_PATTERN   = "(.*_A_.*)".r
+      private val HERTZ_PATTERN    = "(.*_Hz_.*)".r
+      private val PHS_VOLT_PATTERN = "(.*_PhsV_.*)".r
+      private val TEMP_PATTERN     = "(.*Temp_.*)".r
+
+      def parseKeyPrefix(string: String): Try[TsKeyPrefix] = Failure(new Exception("This is not used"))
+
+      override def deriveUnit(in: TsLabel): Option[String] =
+        in.value match {
+          case AMPERE_PATTERN(_)   => Some("A")
+          case HERTZ_PATTERN(_)    => Some("Hz")
+          case PHS_VOLT_PATTERN(_) => Some("V")
+          case TEMP_PATTERN(_)     => Some("°C")
+          case _                   => None
+        }
+    }
+
+    Seq(
+      ("MMCX_A_10m_Avg", Some("A")),
+      ("MMCX_Hz_10m_Avg", Some("Hz")),
+      ("MMCX_PhsV_PhsA_10m_Avg", Some("V")),
+      ("WCNV_XXTemp_10m_Avg", Some("°C")),
+      ("MMCX_PF_10m_Avg", None),
+      ("this_is_an_unkown_unit", None)
+    ).foreach {
+      case (label, unit) => TsLabel(label).unit shouldBe unit
+    }
+  }
+  // scalastyle:on non.ascii.character.disallowed
+
+  it should "return a failure if a case is not handled" in {
+
+    implicit val parser: EntityParser = new EntityParser {
+
+      def parseKeyPrefix(string: String): Try[TsKeyPrefix] = Failure(new Exception("This is not used"))
+
+      /** Parse the unit of a TsLabel from the given string key.
+        *
+        * @return an option containing the string representation of the unit
+        */
+      override def deriveUnit(in: TsLabel): Option[String] =
+        in.value match {
+          case "not exhaustive" => Some("unit")
+          case _                => None
+        }
+    }
+
+    TsLabel("anything").unit shouldBe None
+    TsLabel("not exhaustive").unit shouldBe Some("unit")
+  }
+}