Content Wrappers
Whenever possible, the same data structures are used to represent the same types of data, regardless of the API operation (reading, creating, or modifying). However, often more data is available in output than in input. For example, when a value is read from the triplestore, its IRI is available, but when it is being created, it does not yet have an IRI.
The implementation of API v2 therefore uses content wrappers. For each type,
there is a case class that represents the lowest common denominator of the
type, the data that will be present regardless of the API operation. For
example, the trait ValueContentV2 represents a Knora value, regardless
of whether it is received as input or returned as output. Case classes
such as DateValueContentV2 and TextValueContentV2 implement this trait.
An instance of this lowest-common-denominator class, or "content class", can then
be wrapped in an instance of an operation-specific class that carries additional
data. For example, when a Knora value is returned from the triplestore, a
ValueContentV2 is wrapped in a ReadValueV2, which additionally contains the
value's IRI. When a value is created, it is wrapped in a CreateValueV2, which
has the resource IRI and the property IRI, but not the value IRI.
A read wrapper can be wrapped in another read wrapper; for
example, a ReadResourceV2 contains ReadValueV2 objects.
In general, DSP-API v2 responders deal only with the internal schema.
(The exception is OntologyResponderV2, which can return ontology information
that exists only in an external schema.) Therefore, a content class needs
to be able to convert itself from the internal schema to an external schema
(when it is being used for output) and vice versa (when it is being used for
input). Each content class class should therefore extend KnoraContentV2, and
thus have a toOntologySchema method or converting itself between internal and
external schemas, in either direction:
/**
* A trait for content classes that can convert themselves between internal and internal schemas.
*
* @tparam C the type of the content class that extends this trait.
*/
trait KnoraContentV2[C <: KnoraContentV2[C]] {
this: C =>
def toOntologySchema(targetSchema: OntologySchema): C
}
Since read wrappers are used only for output, they need to be able convert
themselves only from the internal schema to an external schema. Each read wrapper class
should extend KnoraReadV2, and thus have a method for doing this:
/**
* A trait for read wrappers that can convert themselves to external schemas.
*
* @tparam C the type of the read wrapper that extends this trait.
*/
trait KnoraReadV2[C <: KnoraReadV2[C]] {
this: C =>
def toOntologySchema(targetSchema: ApiV2Schema): C
}