Package org.gcube.informationsystem.resourceregistry.types

Class TypeRepository

java.lang.Object

org.gcube.informationsystem.resourceregistry.types.TypeRepository

public class TypeRepository
extends Object

Orchestrator and repository layer for managing resource and facet Schema Types. Coordinates database access via TypeManagement and passive key-value caching via RedisTypeCache, adhering strictly to the All-or-Nothing cache consistency strategy.

Author:

Luca Frosini (ISTI - CNR)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	TypeRepository.TypeQueryResult	Result payload and shape produced by a Type JSON query.

Constructor Summary

Constructors

Constructor	Description
TypeRepository()	Constructor to instantiate TypeRepository.

Method Summary

Modifier and Type	Method	Description
TypeCreationResult	create(String json, org.gcube.informationsystem.types.reference.Type type, boolean preservePassedMetadata)	Registers a new type, optionally preserving the metadata object already present in the submitted JSON instead of autofilling it from the current caller and clock.
TypeCreationResult	create(String json, org.gcube.informationsystem.types.reference.Type type, boolean preservePassedMetadata, boolean allowUnresolvedResourceReferences)	Registers a new type, optionally allowing a ResourceSchema's own forward-declared consistsOf/isRelatedTo relation-type reference (and, for isRelatedTo only, its target Resource type) to not exist yet.
TypeCreationResult	create(String json, org.gcube.informationsystem.types.reference.Type type, org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy)	Registers a new Type definition in the database and adds it to the cache.
boolean	delete(String typeName)	Deletes the specified type schema and its definition from the database.
boolean	isCacheBypass()	Returns whether the Redis cache is currently bypassed.
SchemaSnapshot	loadSchemaSnapshot()	Loads every Type definition from the database as an immutable, version-stamped SchemaSnapshot.
int	populateCacheFrom(SchemaSnapshot snapshot)	Repopulates the Redis type cache from a snapshot, in a single pipelined batch.
String	query(String jsonQuery, int limit, int offset, int depth, org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy)	Executes a JSON query against the Types collection (schema definitions), returning matching Type definitions.
TypeRepository.TypeQueryResult	queryWithDetails(String jsonQuery, int limit, int offset, int depth, org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy, boolean maskMetadata)	Executes a Type JSON query and reports whether its result is projection-based.
String	read(String typeName, int depth, org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy)	Reads the serialized JSON representation of a Type and optionally all of its subtypes down to a specified depth.
String	read(String typeName, int depth, org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy, boolean maskMetadata)	Reads a Type by name while applying metadata inclusion and identity masking.
void	setCacheBypass(boolean bypass)	Configures whether the Redis cache should be completely bypassed.
String	update(String typeName, String json, org.gcube.informationsystem.types.reference.Type type, boolean skipVersionCheckOnUpdate)	Updates an existing Type definition in the database and invalidates the cache.
void	warmUpCache()	Loads a snapshot and repopulates the Redis type cache from it.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

TypeRepository

public TypeRepository()

Constructor to instantiate TypeRepository.

Method Details

setCacheBypass

public void setCacheBypass(boolean bypass)

Configures whether the Redis cache should be completely bypassed.

Parameters:

bypass - true to force direct OrientDB database queries, false otherwise

isCacheBypass

public boolean isCacheBypass()

Returns whether the Redis cache is currently bypassed.

Returns:

true if cache is bypassed, false otherwise

read

public String read(String typeName,
 int depth,
 org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads the serialized JSON representation of a Type and optionally all of its subtypes down to a specified depth.

Parameters:

typeName - the case-sensitive type name to look up

depth - the depth of subclasses to include (0 = none, N = N levels, -1 = all recursively)

metadataPolicy - the metadata inclusion policy to apply

Returns:

serialized JSON array representing the type schema(s)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the lookup fails

read

public String read(String typeName,
 int depth,
 org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy,
 boolean maskMetadata)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a Type by name while applying metadata inclusion and identity masking.

Parameters:

typeName - the case-sensitive type name to look up

depth - the depth of subclasses to include (0 = none, N = N levels, -1 = all recursively)

metadataPolicy - the metadata inclusion policy to apply

maskMetadata - whether sensitive metadata identity fields must be redacted

Returns:

serialized JSON array representing the type schema(s)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the lookup fails

query

public String query(String jsonQuery,
 int limit,
 int offset,
 int depth,
 org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy)
             throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Executes a JSON query against the Types collection (schema definitions), returning matching Type definitions.

Parameters:

jsonQuery - the JSON query payload describing the Type definition search criteria

limit - the maximum number of results to return

offset - the number of results to skip

depth - the descendant-closure depth for Type-name matching (0 = exact name only, N = N levels of descendants, -1 = all descendants recursively)

metadataPolicy - the metadata inclusion policy to apply

Returns:

JSON array string of matching Type definitions

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the query is invalid or syntactically incorrect

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or processing failure

queryWithDetails

public TypeRepository.TypeQueryResult queryWithDetails(String jsonQuery,
 int limit,
 int offset,
 int depth,
 org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy,
 boolean maskMetadata)
                                                throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Executes a Type JSON query and reports whether its result is projection-based.

Parameters:

jsonQuery - the JSON query payload describing the Type definition search criteria

limit - the maximum number of results to return

offset - the number of results to skip

depth - the descendant-closure depth for Type-name matching

metadataPolicy - the metadata inclusion policy to apply to full representations

maskMetadata - whether sensitive metadata identity fields must be redacted

Returns:

the serialized result and its projection flag

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the query is invalid or syntactically incorrect

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or processing failure

create

public TypeCreationResult create(String json,
 org.gcube.informationsystem.types.reference.Type type,
 org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy)
                          throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Registers a new Type definition in the database and adds it to the cache. If the type name already exists, the repository performs an exact congruency check. If the existing schema is identical to the provided one, it returns a TypeCreationResult with created = false (no-op). If the schemas differ, it throws a SchemaAlreadyPresentException (409 Conflict).

Parameters:

json - the raw type JSON definition

type - the deserialized Type model instance

metadataPolicy - the metadata inclusion policy applied to the returned representation

Returns:

the TypeCreationResult wrapping the schema representation and creation outcome

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the creation fails or schema mismatch occurs

create

public TypeCreationResult create(String json,
 org.gcube.informationsystem.types.reference.Type type,
 boolean preservePassedMetadata)
                          throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Registers a new type, optionally preserving the metadata object already present in the submitted JSON instead of autofilling it from the current caller and clock. Used exclusively by System Restore to reproduce the original audit trail of a dumped type.

Parameters:

json - the raw type JSON definition

type - the deserialized Type model instance

preservePassedMetadata - true to preserve submitted metadata, false to autofill

Returns:

the TypeCreationResult wrapping the schema representation and creation outcome

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the creation fails or schema mismatch occurs

create

public TypeCreationResult create(String json,
 org.gcube.informationsystem.types.reference.Type type,
 boolean preservePassedMetadata,
 boolean allowUnresolvedResourceReferences)
                          throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Registers a new type, optionally allowing a ResourceSchema's own forward-declared consistsOf/isRelatedTo relation-type reference (and, for isRelatedTo only, its target Resource type) to not exist yet. Used exclusively by System Restore, whose dump is a flat snapshot of an already-consistent historical state that a live system could only have reached incrementally (e.g. a Resource created first, then updated later to declare a relation that did not exist until afterwards) — replaying it as a single unordered batch of creations otherwise hits an unresolvable ordering cycle between a Resource and a relation type that in turn requires that same Resource to exist as its own source/target (see type-update-and-deprecation/decision-log.md, 2026-08-24). The bypass is deliberately narrow: a consistsOf entry's target (always a Facet) and a RelationSchema's own source/target remain always strictly checked, in both modes — only the two ends of the genuine ordering cycle are relaxed here, never validated dangling.

Parameters:

json - the raw type JSON definition

type - the deserialized Type model instance

preservePassedMetadata - true to preserve submitted metadata, false to autofill

allowUnresolvedResourceReferences - true to skip existence checks for a ResourceSchema's own consistsOf/isRelatedTo relation-type reference and isRelatedTo target Resource type; false for the ordinary strict behavior

Returns:

the TypeCreationResult wrapping the schema representation and creation outcome

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the creation fails or schema mismatch occurs

update

public String update(String typeName,
 String json,
 org.gcube.informationsystem.types.reference.Type type,
 boolean skipVersionCheckOnUpdate)
              throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing Type definition in the database and invalidates the cache.

Parameters:

typeName - the name of the type to update

json - the raw updated type JSON definition

type - the deserialized updated Type model instance

skipVersionCheckOnUpdate - true to skip version increment checks, false to enforce them

Returns:

the serialized JSON representation of the updated type

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the update fails

delete

public boolean delete(String typeName)
               throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes the specified type schema and its definition from the database.

Parameters:

typeName - the case-sensitive name of the type to delete

Returns:

true if deletion succeeded

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if no type with the specified name exists

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - if the type has concrete instances, subtypes, or references from another type definition or from the template of a Query Template

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if deletion fails

loadSchemaSnapshot

public SchemaSnapshot loadSchemaSnapshot()
                                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Loads every Type definition from the database as an immutable, version-stamped SchemaSnapshot.

This is the expensive operation the whole caching design exists to avoid repeating: it walks the type graph and reassembles every definition. It is therefore performed only in the background, by the schema projection worker, and never on a request path.

The version is read before loading, so that a change landing mid-load produces a snapshot stamped with the older version, which is then rebuilt — rather than a partially stale snapshot stamped as current.

Returns:

the loaded snapshot

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the database load fails

populateCacheFrom

public int populateCacheFrom(SchemaSnapshot snapshot)

Repopulates the Redis type cache from a snapshot, in a single pipelined batch.

Parameters:

snapshot - the snapshot to write

Returns:

the number of types written, or 0 if nothing was written

warmUpCache

public void warmUpCache()
                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Loads a snapshot and repopulates the Redis type cache from it.

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the database load fails