Factor out ProtoDecoderBase for extensibility (#285)

Ostrzyciel · web-flow · commit 2be48ca56cee · 2025-03-02T14:44:48.000+01:00
To support extensions like Jelly-Patch, it would be useful to factor out the common ProtoDecoder code to a trait that can be extended. More info: Jelly-RDF/jelly-protobuf#11 This is analogous to very similar changes in ProtoEncoder here: #278
diff --git a/core/src/main/java/eu/ostrzyciel/jelly/core/internal/NameDecoder.java b/core/src/main/java/eu/ostrzyciel/jelly/core/internal/NameDecoder.java
@@ -9,7 +9,7 @@
  * Class for decoding RDF IRIs from their Jelly representation.
  * @param <TIri> The type of the IRI in the target RDF library.
  */
-final class NameDecoder<TIri> {
+final class NameDecoderImpl<TIri> implements NameDecoder<TIri> {
     private static final class NameLookupEntry {
         // Primary: the actual name
         public String name;
@@ -44,7 +44,7 @@ private static final class PrefixLookupEntry {
      * @param nameTableSize The size of the name lookup table.
      * @param iriFactory A function that creates an IRI from a string.
      */
-    public NameDecoder(int prefixTableSize, int nameTableSize, Function<String, TIri> iriFactory) {
+    public NameDecoderImpl(int prefixTableSize, int nameTableSize, Function<String, TIri> iriFactory) {
         this.iriFactory = iriFactory;
         nameLookup = new NameLookupEntry[nameTableSize + 1];
         prefixLookup = new PrefixLookupEntry[prefixTableSize + 1];
diff --git a/core/src/main/scala/eu/ostrzyciel/jelly/core/JellyOptions.scala b/core/src/main/scala/eu/ostrzyciel/jelly/core/JellyOptions.scala
@@ -7,75 +7,82 @@ import eu.ostrzyciel.jelly.core.proto.v1.{LogicalStreamType, PhysicalStreamType,
  * None of the presets specifies the stream type – do that with the .withPhysicalType method.
  */
 object JellyOptions:
+  private[core] inline val bigNameTableSize = 4000
+  private[core] inline val bigPrefixTableSize = 150
+  private[core] inline val bigDtTableSize = 32
+  
+  private[core] inline val smallNameTableSize = 128
+  private[core] inline val smallPrefixTableSize = 16
+  private[core] inline val smallDtTableSize = 16
 
   /**
    * "Big" preset suitable for high-volume streams and larger machines.
    * Does not allow generalized RDF statements.
    * @return
    */
-  def bigStrict: RdfStreamOptions = RdfStreamOptions(
-    maxNameTableSize = 4000,
-    maxPrefixTableSize = 150,
-    maxDatatypeTableSize = 32,
+  lazy val bigStrict: RdfStreamOptions = RdfStreamOptions(
+    maxNameTableSize = bigNameTableSize,
+    maxPrefixTableSize = bigPrefixTableSize,
+    maxDatatypeTableSize = bigDtTableSize,
   )
 
   /**
    * "Big" preset suitable for high-volume streams and larger machines.
    * Allows generalized RDF statements.
    * @return
    */
-  def bigGeneralized: RdfStreamOptions =
+  lazy val bigGeneralized: RdfStreamOptions =
     bigStrict.withGeneralizedStatements(true)
 
   /**
    * "Big" preset suitable for high-volume streams and larger machines.
    * Allows RDF-star statements.
    * @return
    */
-  def bigRdfStar: RdfStreamOptions =
+  lazy val bigRdfStar: RdfStreamOptions =
     bigStrict.withRdfStar(true)
 
   /**
    * "Big" preset suitable for high-volume streams and larger machines.
    * Allows all protocol features (including generalized RDF statements and RDF-star statements).
    * @return
    */
-  def bigAllFeatures: RdfStreamOptions =
+  lazy val bigAllFeatures: RdfStreamOptions =
     bigStrict.withGeneralizedStatements(true).withRdfStar(true)
 
   /**
    * "Small" preset suitable for low-volume streams and smaller machines.
    * Does not allow generalized RDF statements.
    * @return
    */
-  def smallStrict: RdfStreamOptions = RdfStreamOptions(
-    maxNameTableSize = 128,
-    maxPrefixTableSize = 16,
-    maxDatatypeTableSize = 16,
+  lazy val smallStrict: RdfStreamOptions = RdfStreamOptions(
+    maxNameTableSize = smallNameTableSize,
+    maxPrefixTableSize = smallPrefixTableSize,
+    maxDatatypeTableSize = smallDtTableSize,
   )
 
   /**
    * "Small" preset suitable for low-volume streams and smaller machines.
    * Allows generalized RDF statements.
    * @return
    */
-  def smallGeneralized: RdfStreamOptions =
+  lazy val smallGeneralized: RdfStreamOptions =
     smallStrict.withGeneralizedStatements(true)
     
   /**
     * "Small" preset suitable for low-volume streams and smaller machines.
     * Allows RDF-star statements.
     * @return
     */
-  def smallRdfStar: RdfStreamOptions =
+  lazy val smallRdfStar: RdfStreamOptions =
     smallStrict.withRdfStar(true)
 
   /**
    * "Small" preset suitable for low-volume streams and smaller machines.
    * Allows all protocol features (including generalized RDF statements and RDF-star statements).
    * @return
    */
-  def smallAllFeatures: RdfStreamOptions =
+  lazy val smallAllFeatures: RdfStreamOptions =
     smallStrict.withGeneralizedStatements(true).withRdfStar(true)
 
   /**
@@ -96,7 +103,7 @@ object JellyOptions:
    * 
    * @return
    */
-  def defaultSupportedOptions: RdfStreamOptions = RdfStreamOptions(
+  lazy val defaultSupportedOptions: RdfStreamOptions = RdfStreamOptions(
     generalizedStatements = true,
     rdfStar = true,
     maxNameTableSize = 4096,
diff --git a/core/src/main/scala/eu/ostrzyciel/jelly/core/internal/NameDecoder.scala b/core/src/main/scala/eu/ostrzyciel/jelly/core/internal/NameDecoder.scala
@@ -0,0 +1,41 @@
+package eu.ostrzyciel.jelly.core.internal
+
+import eu.ostrzyciel.jelly.core.proto.v1.*
+
+object NameDecoder:
+  /**
+   * Create a new NameDecoder.
+   * @param prefixTableSize size of the prefix table
+   * @param nameTableSize size of the name table
+   * @param iriFactory factory for creating IRIs
+   * @tparam TIri type of the IRI
+   * @return new NameDecoder
+   */
+  def apply[TIri](
+    prefixTableSize: Int, nameTableSize: Int, iriFactory: java.util.function.Function[String, TIri]
+  ): NameDecoder[TIri] =
+    new NameDecoderImpl(prefixTableSize, nameTableSize, iriFactory)
+
+/**
+ * Interface for NameDecoder exposed for Jelly extensions.
+ * @tparam TIri type of the IRI
+ */
+private[core] trait NameDecoder[TIri]:
+  /**
+   * Update the name table with a new entry.
+   * @param nameEntry new name entry
+   */
+  def updateNames(nameEntry: RdfNameEntry): Unit
+
+  /**
+   * Update the prefix table with a new entry.
+   * @param prefixEntry new prefix entry
+   */
+  def updatePrefixes(prefixEntry: RdfPrefixEntry): Unit
+
+  /**
+   * Reconstruct an IRI from its prefix and name ids.
+   * @param iri IRI row from the Jelly proto
+   * @return full IRI combining the prefix and the name
+   */
+  def decode(iri: RdfIri): TIri
diff --git a/core/src/main/scala/eu/ostrzyciel/jelly/core/internal/ProtoDecoderBase.scala b/core/src/main/scala/eu/ostrzyciel/jelly/core/internal/ProtoDecoderBase.scala
@@ -0,0 +1,140 @@
+package eu.ostrzyciel.jelly.core.internal
+
+import eu.ostrzyciel.jelly.core.*
+import eu.ostrzyciel.jelly.core.JellyExceptions.*
+import eu.ostrzyciel.jelly.core.proto.v1.*
+
+import scala.reflect.ClassTag
+
+/**
+ * Base trait for Jelly proto decoders. Only for internal use.
+ * @tparam TNode type of RDF nodes in the library
+ * @tparam TDatatype type of the datatype in the library
+ * @tparam TTriple type of the triple in the library
+ * @tparam TQuad type of the quad in the library
+ */
+private[core] trait ProtoDecoderBase[TNode, TDatatype : ClassTag, +TTriple, +TQuad]:
+
+  // To be implemented by the concrete class
+  protected val converter: ProtoDecoderConverter[TNode, TDatatype, TTriple, TQuad]
+  protected def getNameTableSize: Int
+  protected def getPrefixTableSize: Int
+  protected def getDatatypeTableSize: Int
+
+  // Private fields
+  protected final lazy val nameDecoder =
+    NameDecoder(getPrefixTableSize, getNameTableSize, converter.makeIriNode)
+  protected final lazy val dtLookup = new DecoderLookup[TDatatype](getDatatypeTableSize)
+
+  protected final val lastSubject: LastNodeHolder[TNode] = new LastNodeHolder()
+  protected final val lastPredicate: LastNodeHolder[TNode] = new LastNodeHolder()
+  protected final val lastObject: LastNodeHolder[TNode] = new LastNodeHolder()
+  protected final val lastGraph: LastNodeHolder[TNode] = new LastNodeHolder()
+
+  // Protected final methods
+
+  /**
+   * Convert a GraphTerm message to a node.
+   * @param graph graph term to convert
+   * @return converted node
+   */
+  protected final def convertGraphTerm(graph: GraphTerm): TNode =
+    if graph == null then
+      throw new RdfProtoDeserializationError("Empty graph term encountered in a GRAPHS stream.")
+    else if graph.isIri then
+      nameDecoder.decode(graph.iri)
+    else if graph.isDefaultGraph then
+      converter.makeDefaultGraphNode()
+    else if graph.isBnode then
+      converter.makeBlankNode(graph.bnode)
+    else if graph.isLiteral then
+      convertLiteral(graph.literal)
+    else
+      throw new RdfProtoDeserializationError("Unknown graph term type.")
+
+  /**
+   * Convert an SpoTerm message to a node, while respecting repeated terms.
+   * @param term term to convert
+   * @param lastNodeHolder holder for the last node
+   * @return converted node
+   */
+  protected final def convertTermWrapped(term: SpoTerm, lastNodeHolder: LastNodeHolder[TNode]): TNode =
+    if term == null then
+      lastNodeHolder.node match
+        case LastNodeHolder.NoValue =>
+          throw new RdfProtoDeserializationError("Empty term without previous term.")
+        case n => n.asInstanceOf[TNode]
+    else
+      val node = convertTerm(term)
+      lastNodeHolder.node = node
+      node
+
+  /**
+   * Convert a GraphTerm message to a node, while respecting repeated terms.
+   * @param graph graph term to convert
+   * @return converted node
+   */
+  protected final def convertGraphTermWrapped(graph: GraphTerm): TNode =
+    if graph == null then
+      lastGraph.node match
+        case LastNodeHolder.NoValue =>
+          throw new RdfProtoDeserializationError("Empty term without previous graph term.")
+        case n => n.asInstanceOf[TNode]
+    else
+      val node = convertGraphTerm(graph)
+      lastGraph.node = node
+      node
+
+  /**
+   * Convert an RdfTriple message, while respecting repeated terms.
+   * @param triple triple to convert
+   * @return converted triple
+   */
+  protected final def convertTriple(triple: RdfTriple): TTriple =
+    converter.makeTriple(
+      convertTermWrapped(triple.subject, lastSubject),
+      convertTermWrapped(triple.predicate, lastPredicate),
+      convertTermWrapped(triple.`object`, lastObject),
+    )
+
+  /**
+   * Convert an RdfQuad message, while respecting repeated terms.
+   * @param quad quad to convert
+   * @return converted quad
+   */
+  protected final def convertQuad(quad: RdfQuad): TQuad =
+    converter.makeQuad(
+      convertTermWrapped(quad.subject, lastSubject),
+      convertTermWrapped(quad.predicate, lastPredicate),
+      convertTermWrapped(quad.`object`, lastObject),
+      convertGraphTermWrapped(quad.graph),
+    )
+
+  // Private methods
+  private final def convertLiteral(literal: RdfLiteral): TNode = literal.literalKind match
+    case RdfLiteral.LiteralKind.Empty =>
+      converter.makeSimpleLiteral(literal.lex)
+    case RdfLiteral.LiteralKind.Langtag(lang) =>
+      converter.makeLangLiteral(literal.lex, lang)
+    case RdfLiteral.LiteralKind.Datatype(dtId) =>
+      converter.makeDtLiteral(literal.lex, dtLookup.get(dtId))
+
+  private final def convertTerm(term: SpoTerm): TNode =
+    if term == null then
+      throw new RdfProtoDeserializationError("Term value is not set inside a quoted triple.")
+    else if term.isIri then
+      nameDecoder.decode(term.iri)
+    else if term.isBnode then
+      converter.makeBlankNode(term.bnode)
+    else if term.isLiteral then
+      convertLiteral(term.literal)
+    else if term.isTripleTerm then
+      val inner = term.tripleTerm
+      // ! No support for repeated terms in quoted triples
+      converter.makeTripleNode(
+        convertTerm(inner.subject),
+        convertTerm(inner.predicate),
+        convertTerm(inner.`object`),
+      )
+    else
+      throw new RdfProtoDeserializationError("Unknown term type.")
diff --git a/core/src/main/scala/eu/ostrzyciel/jelly/core/internal/ProtoDecoderImpl.scala b/core/src/main/scala/eu/ostrzyciel/jelly/core/internal/ProtoDecoderImpl.scala
