Design Documentation for OntologyCache Service

[tobiasschweizer]

OntologyCacheService

Scope

The service OntologyCacheService requests ontology entity definitions from Knora and caches them. The service works with the Knora v2 complex API.

Whenever resource class Iris or property Iris (entity definitions) have to be resolved, this service can be used. Entity definitions are contained in responses returned by the Knora v2 complex API, e.g., when doing a full resource request or a search.

Methods

• getOntologiesMetadata(): Observable<Array<OntologyMetadata>>: Returns metadata about all existing ontologies. OntologyMetadata has two members: the id (Iri) and label of each ontology.
• getEntityDefinitionsForOntologies(ontologyIris: string[]): Observable<OntologyInformation>: Returns the entity definitions (resource classes and properties) for the given ontology Iris.
• getResourceClassDefinitions(resourceClassIris: string[]): Observable<OntologyInformation>: Returns the resource class definitions for the given resource class Iris.
• getPropertyDefinitions(propertyIris: string[]): Observable<OntologyInformation>: Returns the property definitions for the given property Iris.

OntologyInformation

Whenever entity definitions are requested, an instance of OntologyInformation is returned. OntologyInformation contains only the information requested, also if more information is cached.

Reading information

OntologyInformation offers methods to access this information:

• getResourceClassForOntology(): ResourceClassIrisForOntology: Returns a map of ontology Iris to arrays of resource class Iris contained in the given ontology.
• getResourceClasses(): ResourceClasses: Returns all resource class definitions as a map of resource class Iris to resource class definitions.
• getResourceClassesAsArray(): Array<ResourceClass>: Returns the resource class definitions as an array.
• getLabelForResourceClass(resClass: string): string: Gets the label of a resource class.
• getProperties(): Properties: Returns all the property definitions as a map of property Iris to property definitions.
• getPropertiesAsArray(): Array<Property>: Returns all property definitions as an array.
• getLabelForProperty(property: string): string: Returns the label for the specified property.

Updating information

When doing a search, results have to be fetched by page by page. With each new page, unknown entity Iris may have to be resolved. The new information can be attached to the existing information using the method updateOntologyInformation(ontologyInfo: OntologyInformation): void. Just call this method on the existing instance of OntologyInformation, passing the OntologyInformation obtained.

[tobiasschweizer]

Design

OntologyCache

Whenever information is requested from OntologyCacheService, the information will be returned from the cache or requested from Knora and cached. OntologyCacheService holds a single instance of OntologyCache containing all the cached information. This instance is never exposed to the outside but only used internally. Requested information will be sent back as an instance of OntologyInformation.

Requesting information from Knora

Whenever information is requested from Knora, whole ontologies are requested. Given the Iri of a resource class or a property, the ontology it belongs to can be determined automatically and requested from Knora.

OntologyService performs the actual HTTP requests to Knora and returns the result to OntologyCacheService as JSON-LD. OntologyCacheService takes care of processing the JSON-LD and expand the Iris.

Writing to the cache

Whenever information is requested that is not cached already, the information is requested from Knora, written to the cache and then served from the cache. This last steps works the same way when already cached information is served.

Properties from other ontologies

When a definition of a resource class is requested that has cardinalities for properties that are defined in another ontology, that ontology is requested from Knora and cached automatically by OntologyCacheService. With a resource definitions, the definitions for all properties the resource class has cardinalities for are served too.

This works in a hierarchical way: getResourceClassDefinitions is called when calling getEntityDefinitionsForOntologies and getResourceClassDefinitions calls getPropertyDefinitions.

[tobiasschweizer]

@flavens @kilchenmann @andreas-aeschlimann Could you give me a feedback if this is good enough? Is there anything unclear or missing?

[flavens]

@tobiasschweizer I do not really understand §"Writing to the cache"

[tobiasschweizer]

I do not really understand §"Writing to the cache"

"Writing to the cache" means that the information obtained from Knora is stored in an instance of OntologyCache. Every time new information is queried, it is added.

OntologyCacheService holds a single instance of OntologyCache (cacheOntology).

[tobiasschweizer]

Dependency: OntologyService