Skip to content

Implementation Details

Modules

block-beta
    columns 1
    block: ext
        cli
        web
        model
    end
    block: core
        columns 3
        thing
        io
        common
    end
    block: third_party
        columns 5
        RDF4j
        Guava
        Protobuf
        gRPC
        Netty
        SnakeYAML
        Tika
        OkHttp
        PicoCLI
        ch.vorburger.Exec
    end

Enola Thing (ET 👽)

All ETs have 0.. n properties. Each such Property is identified by an IRI, and has a value. Each such value has a Type. These types include e.g. text (string), numbers, or dates - but also lists, and “nested” sub-properties. There is actually no fixed set of known such types; applications can define their own.

All ET have an IRI. Note that you may see what looks like an exception to this rule with the “nested” ETs, which RDF and LD call “blank nodes”; in Enola we strictly speaking conceptually don’t call those things, just “maps of properties”.

All this is, of course, heavily inspired by TBL’s vision of the ”Semantic Web” of ”Linked Data”, such as also expressed by standards such as RDF or JSON-LD.

ETs have a number of different (but ultimately semantically equivalent) representations, both internally in Enola’s code as well as externally serialized in resources.

Internal Data Types

IRIs

WIP

IRIs are (currently) mostly a String, but sometimes an Object.

When an IRI is just an Object, then its toString() is guaranteed to return a valid textual representation of the IRI.

The intention is to eventually replace all String typed IRI with only Object.

This allows for future optimizations of internal IRI types.

Wrappers

Warning

This section describes a work-in-progress (WIP) which is not yet fully implemented as documented here.

Enola generates wrapper Java interfaces for RDFS Classes and Properties:

  • Generated RDF Property interfaces:
    • by default are named Has*{Label}
    • extends based on any rdfs:subPropertyOf, or IImmutableThing (see Thing)
    • have getter methods with default implementations, which delegate to the suitable Thing.get() API, using the Property IRI
    • contain an inner Builder interface (but no builder(), as only used via classes)
  • Generated RDF Property Builder interfaces:
    • have setter and add* methods with default implementations, which delegate to the suitable Thing API, using the Property IRI
  • Generated RDF Class interfaces:
    • extends all its RDF Property interfaces, as well as any rdfs:subClassOf
    • by default are named {Label} for classes
    • contain an inner Builder interface, and a static builder() method to obtain an implementation of it, with @type set
    • override copy() with a covariant variant type of this class’s Builder
  • Generated RDF Class Builder interfaces:
    • override iri(Object iri) and all setters with a covariant variant type of the Builder (for chaining)
    • extends all its RDF Property Builder interfaces

Java ☕ Thing

  • Java Type: dev.enola.thing.Thing

The Java Thing API is an interface which has several available implementations. The simplest one is the dev.enola.thing.impl.ImmutableThing with its Builder.

Proto Thing

Proto Message

Any Protocol Buffer can be converted to a Thing by Enola.

RDF4j Model

External Serialization Formats

RDF Turtle 🐢

Proto Thing YAML

  • Media Type: text/enola.dev#thing+yaml (from dev.enola.thing.io.ThingMediaTypes)
  • Filename extension: .thing.yaml
  • Example: picasso.thing.yaml

Proto Thing Text

  • Media Type: text/protobuf?proto-message=dev.enola.thing.Thing (from dev.enola.thing.io.ThingMediaTypes)
  • Filename extension: .textproto

Conversions

graph BT
  ProtoThing[Proto Thing]
  ProtoMessage[Proto Message]
  RDF4jModel(RDF4j Model)
  RDFTurtle["RDF Turtle 🐢"]
  JavaThing("Java ☕ Thing")

  ProtoThing-- "ThingAdapter" -->JavaThing
  JavaThing-- "JavaThingToProtoThingConverter" -->ProtoThing
  ProtoMessage-- "MessageToThingConverter" -->ProtoThing

  JavaThing<-- "ThingConverterInto" -->JavaThing

  RDF4jModel-- "RdfProtoThingsConverter" -->ProtoThing
  ProtoThing-- "ProtoThingRdfConverter" -->RDF4jModel
  RDF4jModel-- "RdfWriterConverter" -->RDFTurtle
  RDFTurtle-- "RdfReaderConverterInto" -->RDF4jModel

  JavaThing-- "JavaThingRdfConverter" -->RDF4jModel

Store & Repository

TODO Document!