Package org.gcube.informationsystem.resourceregistry.persistence.orientdb.base

Class ElementManagement<El extends com.orientechnologies.orient.core.record.OElement,T extends org.gcube.informationsystem.types.reference.Type>

java.lang.Object
org.gcube.informationsystem.resourceregistry.persistence.orientdb.base.ElementManagement<El,T>
Type Parameters:
El - the specific OrientDB OElement subtype (vertex or edge) this class manages
T - the corresponding schema Type definition interface
Direct Known Subclasses:
EntityElementManagement, PropertySchemaManagement, RelationElementManagement
public abstract class ElementManagement<El extends com.orientechnologies.orient.core.record.OElement,T extends org.gcube.informationsystem.types.reference.Type> extends Object
Common OrientDB persistence base class for every managed element category (Context, Type, and Instance — Entity/Relation alike): CRUD orchestration (create/read/update/delete, paginated list, existence check), JSON <-> OrientDB property mapping, schema/UUID consistency checks, and metadata handling (autofill vs preservePassedMetadata, privacy masking).

This class carries no security-role, token, or permission logic of its own: every behavioral choice it makes is driven exclusively by the explicit flags/values a caller sets on it before invoking an operation (e.g. metadataPolicy, maskMetadata, updateMode, dryRun) — authorization is the exclusive responsibility of the Policy Enforcement Point layer, which configures an instance of this class and never the other way around.

Author:
Luca Frosini (ISTI - CNR)

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final org.gcube.informationsystem.base.reference.AccessType
    accessType
    The access type category.
    protected final Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode>
    affectedInstances
    Accumulates the UUID -> JSON representation of every instance actually affected by a Delete, addToContext, or removeFromContext cascade, so the caller can be told what changed (e.g. an Operation Envelope).
    static final String
    AT
    Symbol constant for at.
    protected CachedType<T>
    cachedType
    The cached schema type definition.
    protected org.gcube.com.fasterxml.jackson.databind.JsonNode
    complete
    The complete serialized JSON node representing the element and its relationships.
    static final String
    DELETED
    String constant representing deleted state.
    static final String
    DOLLAR
    Symbol constant for dollar.
    protected boolean
    dryRun
    Flag indicating whether this operation is a simulation (dry run) which should end with a transaction rollback instead of a commit.
    protected El
    element
    The loaded OrientDB record element instance.
    protected Class<El>
    elementClass
    The specific class of the OrientDB element.
    protected boolean
    entryPoint
    Whether this management instance is the entry point of the current operation, as opposed to a subordinated one triggered on a related instance during cascading.
    protected List<IgnoredFields>
    ignoredFields
    Collects the fields each written instance dropped because its category does not accept them.
    protected final Set<String>
    ignoreKeys
    Keys to ignore during property mapping.
    protected final Set<String>
    ignoreStartWithKeys
    Key prefixes to ignore during property mapping.
    protected org.gcube.com.fasterxml.jackson.databind.JsonNode
    jsonNode
    The input JSON payload node representing the element.
    protected Integer
    limit
    Pagination limit for list operations.
    protected org.slf4j.Logger
    logger
    The logger instance for auditing and diagnostics.
    protected boolean
    maskMetadata
    When true, metadata's createdBy/lastUpdateBy fields are privacy-masked (see applyPrivacyMask(ObjectNode)) while serializing this element.
    protected org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy
    metadataPolicy
    Metadata projection policy for this management operation, set explicitly by the caller (typically the PEP layer).
    protected com.orientechnologies.orient.core.metadata.schema.OClass
    oClass
    The OrientDB schema class.
    protected com.orientechnologies.orient.core.db.document.ODatabaseDocument
    oDatabaseDocument
    The active database document session.
    protected Integer
    offset
    Pagination offset for list operations.
    protected Operation
    operation
    It is assigned only in the entry point
    protected boolean
    polymorphic
    Whether the queries should include subclasses polymorphic results.
    protected boolean
    preservePassedMetadata
    When true, internalCreate() preserves the metadata object already present in the submitted JSON (creator, creation/last-update timestamps) instead of autofilling it from the current caller and clock.
    protected boolean
    reload
    Whether to force a reload from the database.
    protected boolean
    sanityCheckDeferred
    Defers sanity checks for atomic orchestration flows that validate the final graph state explicitly before committing.
    protected org.gcube.com.fasterxml.jackson.databind.JsonNode
    self
    The serialized JSON node representing only the element's direct properties.
    protected String
    typeName
    The name of the schema type.
    static final String
    UNDERSCORE
    Symbol constant for underscore.
    protected UpdateMode
    updateMode
    Defines whether an update should merge into or replace the existing state.
    protected UUID
    uuid
    The UUID identifier of the element.
    protected Environment
    workingEnvironment
    The active database working environment.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    ElementManagement(org.gcube.informationsystem.base.reference.AccessType accessType)
    Creates a new ElementManagement instance for the specified access type.
    protected
    ElementManagement(org.gcube.informationsystem.base.reference.AccessType accessType, String typeName)
    Creates a new ElementManagement instance for the specified access type and type name.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected void
    addIgnoredFields(Set<String> fields)
    Records the fields this instance dropped, if any.
    String
    all()
    Retrieves and returns all elements of this type from the database as a JSON array string.
    static org.gcube.com.fasterxml.jackson.databind.node.ObjectNode
    applyPrivacyMask(org.gcube.com.fasterxml.jackson.databind.node.ObjectNode metadataJson)
    Masks privacy-sensitive fields in the given metadata JSON node by replacing Metadata.CREATED_BY_PROPERTY and Metadata.LAST_UPDATE_BY_PROPERTY with the Element.REDACTED placeholder.
    static org.gcube.com.fasterxml.jackson.databind.node.ObjectNode
    applyPrivacyMask(org.gcube.com.fasterxml.jackson.databind.node.ObjectNode metadataJson, boolean keepUserMeta)
    Masks privacy-sensitive fields in the given metadata JSON node, with optional identity-aware behaviour controlled by keepUserMeta.
    protected void
    checkERMatch()
    Validates that the schema type of the JSON node matches the configured type name.
    protected void
    checkJsonNode()
    Validates the input JSON node and extracts the UUID and schema type.
    protected void
    checkUUIDMatch()
    Validates that the UUID inside the JSON node matches the configured element UUID.
    protected void
    checkUUIDNotAlreadyInUse()
    Rejects UUID reuse before creating a brand-new element: a UUID is occupied by any element of any type in any Context, and a creation with an occupied UUID is a conflict.
    protected void
    cleanCachedSerialization()
    Invalidates the cached direct and complete JSON representations.
    protected void
    concludeTransaction(String successMessage)
    Concludes the active database transaction.
    String
    create()
    Creates a new element in the database.
    protected abstract org.gcube.com.fasterxml.jackson.databind.JsonNode
    createCompleteJsonNode()
    Abstract method to create the complete JSON node representation of the element.
    String
    createOrUpdate()
    Atomically creates or updates the element in the database (idempotent upsert).
    ElementCreationResult
    createOrUpdateElementWithResult()
    Atomically creates or updates the element and preserves the resulting operation kind.
    void
    delete()
    Deletes this element from the database.
    boolean
    exists()
    Returns whether the element with the configured UUID exists in the database.
    org.gcube.informationsystem.base.reference.AccessType
    getAccessType()
    Returns the access type category of this element.
    Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode>
    getAffectedInstances()
    Returns the map of instances affected by operations on this element.
    protected Set<org.gcube.informationsystem.types.reference.properties.PropertyDefinition>
    getAllProperties()
    Retrieves and returns all property definitions for this schema type, including those inherited from all of its supertypes.
    protected CachedType<T>
    getCachedType()
    Returns the cached schema type definition, initializing it if not present.
    static com.orientechnologies.orient.core.db.document.ODatabaseDocument
    getCurrentODatabaseDocumentFromThreadLocal()
    Returns the ODatabaseDocument currently bound to this thread by OrientDB's thread-local stack, or null if no database is active on this thread.
    El
    getElement()
    Returns the OrientDB element instance, retrieving and caching it if not already present.
    List<IgnoredFields>
    getIgnoredFields()
    Returns the fields dropped by the instances written by this operation.
    Integer
    getLimit()
    Gets the pagination limit.
    protected String
    getMandatoryErrorMessage(String fieldName)
    Formats and returns the error message for a missing mandatory field schema violation.
    static String
    getMandatoryErrorMessage(String typeName, String fieldName)
    Formats and returns the error message for a missing mandatory field of the given type.
    org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy
    getMetadataPolicy()
    Returns the metadata projection policy.
    protected com.orientechnologies.orient.core.metadata.schema.OClass
    getOClass()
    Returns the schema class (OClass) associated with this element.
    Integer
    getOffset()
    Gets the pagination offset.
    protected org.gcube.com.fasterxml.jackson.databind.JsonNode
    getPropertyForJson(String key, Object object)
    Converts an OrientDB property value object into a Jackson JsonNode for JSON serialization.
    Map<String,org.gcube.com.fasterxml.jackson.databind.JsonNode>
    getPropertyMap(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, Set<String> ignoreKeys, Set<String> ignoreStartWith)
    Extracts and returns a flat key-value map of properties from a JSON representation node, skipping any ignored keys and prefixes.
    protected abstract org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException
    getSpecificAlreadyPresentException(String message)
    Converts a generic AlreadyPresentException into a subclass-specific AlreadyPresentException.
    protected abstract org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException
    getSpecificNotFoundException(org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException e)
    Converts a generic NotFoundException into a subclass-specific NotFoundException.
    String
    getTypeName()
    Returns the canonical type name of the element.
    UpdateMode
    getUpdateMode()
    Returns the update mode used by update operations.
    UUID
    getUUID()
    Returns the UUID identifier of this element.
    protected abstract Environment
    getWorkingEnvironment()
    Returns the active database working environment.
    El
    internalCreate()
    Performs the internal database creation and registration of the element.
    El
    internalCreateOrUdate()
    Performs an internal idempotent database upsert (update if exists, otherwise create).
    void
    internalDelete()
    Deletes an existing element from the database.
    El
    internalUpdate()
    Performs the internal database update and metadata refresh of the element.
    static boolean
    isBackendLinkFieldName(String name)
    Returns whether a name is reserved to the backend fields linking Entities and Relations: in, out and every name starting with in_ or out_, in lower or upper case.
    boolean
    isDryRun()
    Returns whether this operation is running as a dry run simulation.
    boolean
    isMaskMetadata()
    Returns whether privacy masking is enabled for metadata fields.
    boolean
    isPolymorphic()
    Gets whether polymorphic queries are enabled.
    boolean
    isPreservePassedMetadata()
    Returns whether a submitted metadata object is preserved as-is on create, instead of being autofilled from the current caller and clock.
    boolean
    isReload()
    Returns whether to force a reload from the database.
    boolean
    isSanityCheckDeferred()
    Returns whether sanity checks are deferred to the caller.
    String
    read()
    Reads and returns the complete serialized JSON string of the element.
    protected abstract El
    reallyCreate()
    Persists a new element in the database (subclass hook).
    protected abstract void
    reallyDelete()
    Deletes an existing element from the database (subclass hook).
    abstract String
    reallyGetAll()
    Retrieves all elements from the database and returns them as a JSON array string.
    protected abstract El
    reallyUpdate()
    Updates an existing element in the database (subclass hook).
    protected boolean
    requireExplicitUUID()
    Returns whether a missing `id` on creation must be rejected rather than auto-generated.
    El
    retrieveElement()
    Directly queries and retrieves the OrientDB element from the database.
    El
    retrieveElementFromAnyContext()
    Queries and retrieves the OrientDB element from any database security context (bypassing RLS).
    void
    sanityCheck()
    Performs runtime validation of mandatory and not-null schema constraints that cannot be enforced directly by OrientDB in distributed mode.
    org.gcube.com.fasterxml.jackson.databind.JsonNode
    serializeAsAffectedInstance()
    Serializes this element as an element of an Operation Envelope.
    org.gcube.com.fasterxml.jackson.databind.JsonNode
    serializeAsEndpointReference(boolean includeMetadata, boolean includeContexts)
    Serializes this element as the endpoint reference of a Relation: type, supertypes and id, plus metadata and contexts only when requested; never its custom fields nor its relations.
    org.gcube.com.fasterxml.jackson.databind.JsonNode
    serializeAsJsonNode()
    Serializes and returns the complete JSON representation of this element (including relationships).
    org.gcube.com.fasterxml.jackson.databind.JsonNode
    serializeSelfAsJsonNode()
    Serializes and returns the raw/local JSON representation of this element (without relationships).
    void
    setAsEntryPoint()
    Marks this management instance as the entry point of the operation.
    void
    setDryRun(boolean dryRun)
    Sets whether this operation should run as a dry run simulation.
    void
    setElement(El element)
    Binds an existing OrientDB element instance to this manager.
    void
    setElementType(String elementType)
    Sets the element schema type name.
    void
    setIgnoredFields(List<IgnoredFields> ignoredFields)
    Shares the collector of dropped fields with the management of an enclosing instance.
    void
    setJson(String json)
    Sets the input JSON string representation of this element.
    void
    setJsonNode(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode)
    Sets the input JSON representation node of this element.
    void
    setLimit(Integer limit)
    Sets the pagination limit with safety validation.
    void
    setMaskMetadata(boolean maskMetadata)
    Sets whether privacy masking is enabled for metadata fields.
    void
    setMetadataPolicy(org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy)
    Sets the metadata projection policy.
    void
    setOClass(com.orientechnologies.orient.core.metadata.schema.OClass oClass)
    Sets the OrientDB schema class.
    void
    setODatabaseDocument(com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
    Sets the active database connection document session.
    void
    setOffset(Integer offset)
    Sets the pagination offset with safety validation.
    void
    setOperation(Operation operation)
    Sets the active operation type.
    void
    setPolymorphic(boolean polymorphic)
    Sets whether polymorphic queries are enabled.
    void
    setPreservePassedMetadata(boolean preservePassedMetadata)
    Sets whether a submitted metadata object is preserved as-is on create, instead of being autofilled from the current caller and clock.
    void
    setProperty(com.orientechnologies.orient.core.metadata.schema.OProperty oProperty, String key, org.gcube.com.fasterxml.jackson.databind.JsonNode value)
    Helper method to map and set a JSON property value onto the OrientDB vertex based on its schema type.
    void
    setReload(boolean reload)
    Sets whether to force a reload from the database.
    void
    setRequireExplicitUUID(boolean requireExplicitUUID)
    Sets whether a missing `id` on creation must be rejected rather than auto-generated.
    void
    setSanityCheckDeferred(boolean sanityCheckDeferred)
    Defers immediate sanity checks for atomic orchestration flows.
    void
    setUpdateMode(UpdateMode updateMode)
    Sets the update mode used by update operations.
    void
    setUUID(UUID uuid)
    Sets the UUID identifier of this element and validates it if a JSON node is already set.
    void
    setWorkingEnvironment(Environment workingContext)
    Sets the active database working environment.
    protected boolean
    typeSatified(String requiredType, String effectiveType)
    Validates whether the effective type satisfies the required type (supports schema inheritance).
    String
    update()
    Updates the element in the database using the provided JSON representation.
    com.orientechnologies.orient.core.record.OElement
    updateProperties(com.orientechnologies.orient.core.metadata.schema.OClass oClass, com.orientechnologies.orient.core.record.OElement element, org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, Set<String> ignoreKeys, Set<String> ignoreStartWithKeys)
    Updates the properties of an OrientDB OElement from a JSON payload node.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • logger

      protected org.slf4j.Logger logger
      The logger instance for auditing and diagnostics.

    • DELETED

      public static final String DELETED
      String constant representing deleted state.
      See Also:

    • AT

      public static final String AT
      Symbol constant for at.
      See Also:

    • UNDERSCORE

      public static final String UNDERSCORE
      Symbol constant for underscore.
      See Also:

    • DOLLAR

      public static final String DOLLAR
      Symbol constant for dollar.
      See Also:

    • ignoreKeys

      protected final Set<String> ignoreKeys
      Keys to ignore during property mapping.

    • ignoreStartWithKeys

      protected final Set<String> ignoreStartWithKeys
      Key prefixes to ignore during property mapping.

    • elementClass

      protected Class<El extends com.orientechnologies.orient.core.record.OElement> elementClass
      The specific class of the OrientDB element.

    • accessType

      protected final org.gcube.informationsystem.base.reference.AccessType accessType
      The access type category.

    • oDatabaseDocument

      protected com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument
      The active database document session.

    • uuid

      protected UUID uuid
      The UUID identifier of the element.

    • jsonNode

      protected org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode
      The input JSON payload node representing the element.

    • oClass

      protected com.orientechnologies.orient.core.metadata.schema.OClass oClass
      The OrientDB schema class.

    • typeName

      protected String typeName
      The name of the schema type.

    • self

      protected org.gcube.com.fasterxml.jackson.databind.JsonNode self
      The serialized JSON node representing only the element's direct properties.

    • complete

      protected org.gcube.com.fasterxml.jackson.databind.JsonNode complete
      The complete serialized JSON node representing the element and its relationships.

    • cachedType

      protected CachedType<T extends org.gcube.informationsystem.types.reference.Type> cachedType
      The cached schema type definition.

    • element

      protected El extends com.orientechnologies.orient.core.record.OElement element
      The loaded OrientDB record element instance.

    • reload

      protected boolean reload
      Whether to force a reload from the database.

    • metadataPolicy

      protected org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy
      Metadata projection policy for this management operation, set explicitly by the caller (typically the PEP layer). When null, shouldIncludeMetadataForCurrentNode() falls back to MetadataPolicy.DEFAULT; this class never resolves it from any ambient request context itself.

    • limit

      protected Integer limit
      Pagination limit for list operations.

    • offset

      protected Integer offset
      Pagination offset for list operations.

    • maskMetadata

      protected boolean maskMetadata
      When true, metadata's createdBy/lastUpdateBy fields are privacy-masked (see applyPrivacyMask(ObjectNode)) while serializing this element. Set explicitly by the caller (typically the PEP layer, based on the requester's role); defaults to false (no masking).

    • polymorphic

      protected boolean polymorphic
      Whether the queries should include subclasses polymorphic results.

    • entryPoint

      protected boolean entryPoint
      Whether this management instance is the entry point of the current operation, as opposed to a subordinated one triggered on a related instance during cascading.

      An operation can affect multiple instances (e.g. create, update, delete). Some follow-up actions must run only once per operation, on the entry point, rather than once per affected instance — for example, when a delete is invoked directly on a Resource, its sanity check must run once on the Resource itself, not be re-triggered by each of its describing Facets as they are cascaded into the same delete.

    • dryRun

      protected boolean dryRun
      Flag indicating whether this operation is a simulation (dry run) which should end with a transaction rollback instead of a commit.

    • sanityCheckDeferred

      protected boolean sanityCheckDeferred
      Defers sanity checks for atomic orchestration flows that validate the final graph state explicitly before committing.

    • preservePassedMetadata

      protected boolean preservePassedMetadata
      When true, internalCreate() preserves the metadata object already present in the submitted JSON (creator, creation/last-update timestamps) instead of autofilling it from the current caller and clock. Used exclusively by System Restore to reproduce the original audit trail of a dumped instance.

    • operation

      protected Operation operation
      It is assigned only in the entry point

    • updateMode

      protected UpdateMode updateMode
      Defines whether an update should merge into or replace the existing state.

    • affectedInstances

      protected final Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode> affectedInstances
      Accumulates the UUID -> JSON representation of every instance actually affected by a Delete, addToContext, or removeFromContext cascade, so the caller can be told what changed (e.g. an Operation Envelope). Populated only when an instance's own processing completes successfully - post-order, at the end of the call.

      Not the same bookkeeping as the visited set in EntityManagement/ RelationManagement: visited is marked on entry, before recursing into children (pre-order), purely as an internal cycle guard, and is never reported to the caller. A UUID can be visited without ever becoming affected - e.g. a relation with addConstraint=unpropagate is visited and skipped, never added, so it never appears here.

    • ignoredFields

      protected List<IgnoredFields> ignoredFields
      Collects the fields each written instance dropped because its category does not accept them. Shared by the managements of the instances nested in the same payload (see setIgnoredFields(List)), so that the entry point reports them all.

    • workingEnvironment

      protected Environment workingEnvironment
      The active database working environment.

  • Constructor Details

    • ElementManagement

      protected ElementManagement(org.gcube.informationsystem.base.reference.AccessType accessType)
      Creates a new ElementManagement instance for the specified access type.
      Parameters:
      accessType - the access type category of the element

    • ElementManagement

      protected ElementManagement(org.gcube.informationsystem.base.reference.AccessType accessType, String typeName)
      Creates a new ElementManagement instance for the specified access type and type name.
      Parameters:
      accessType - the access type category of the element
      typeName - the name of the schema type

  • Method Details

    • isPolymorphic

      public boolean isPolymorphic()
      Gets whether polymorphic queries are enabled.
      Returns:
      true if polymorphic, false otherwise

    • setPolymorphic

      public void setPolymorphic(boolean polymorphic)
      Sets whether polymorphic queries are enabled.
      Parameters:
      polymorphic - true to enable polymorphic results, false otherwise

    • getLimit

      public Integer getLimit()
      Gets the pagination limit.
      Returns:
      the limit

    • setLimit

      public void setLimit(Integer limit)
      Sets the pagination limit with safety validation.
      Parameters:
      limit - the pagination limit to set (-1 for unlimited)
      Throws:
      IllegalArgumentException - if the limit is less than -1

    • getOffset

      public Integer getOffset()
      Gets the pagination offset.
      Returns:
      the offset

    • setOffset

      public void setOffset(Integer offset)
      Sets the pagination offset with safety validation.
      Parameters:
      offset - the pagination offset to set
      Throws:
      IllegalArgumentException - if the offset is less than 0

    • getMetadataPolicy

      public org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy getMetadataPolicy()
      Returns the metadata projection policy.
      Returns:
      the metadata policy

    • setMetadataPolicy

      public void setMetadataPolicy(org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy metadataPolicy)
      Sets the metadata projection policy.
      Parameters:
      metadataPolicy - the metadata policy to set

    • isMaskMetadata

      public boolean isMaskMetadata()
      Returns whether privacy masking is enabled for metadata fields.
      Returns:
      true if masking is enabled, false otherwise

    • setMaskMetadata

      public void setMaskMetadata(boolean maskMetadata)
      Sets whether privacy masking is enabled for metadata fields.
      Parameters:
      maskMetadata - true to enable masking, false to disable

    • isPreservePassedMetadata

      public boolean isPreservePassedMetadata()
      Returns whether a submitted metadata object is preserved as-is on create, instead of being autofilled from the current caller and clock.
      Returns:
      true if passed metadata is preserved, false otherwise

    • setPreservePassedMetadata

      public void setPreservePassedMetadata(boolean preservePassedMetadata)
      Sets whether a submitted metadata object is preserved as-is on create, instead of being autofilled from the current caller and clock.
      Parameters:
      preservePassedMetadata - true to preserve submitted metadata, false to autofill

    • getAffectedInstances

      public Map<UUID,org.gcube.com.fasterxml.jackson.databind.JsonNode> getAffectedInstances()
      Returns the map of instances affected by operations on this element.
      Returns:
      the map of affected instances

    • getIgnoredFields

      public List<IgnoredFields> getIgnoredFields()
      Returns the fields dropped by the instances written by this operation.
      Returns:
      the dropped fields, one entry per instance that dropped any

    • setIgnoredFields

      public void setIgnoredFields(List<IgnoredFields> ignoredFields)
      Shares the collector of dropped fields with the management of an enclosing instance.
      Parameters:
      ignoredFields - the collector of the enclosing management

    • addIgnoredFields

      protected void addIgnoredFields(Set<String> fields)
      Records the fields this instance dropped, if any.
      Parameters:
      fields - the names of the dropped fields

    • setAsEntryPoint

      public void setAsEntryPoint()
      Marks this management instance as the entry point of the operation.

    • setOperation

      public void setOperation(Operation operation)
      Sets the active operation type.
      Parameters:
      operation - the operation type to set

    • getUpdateMode

      public UpdateMode getUpdateMode()
      Returns the update mode used by update operations.
      Returns:
      the update mode

    • setUpdateMode

      public void setUpdateMode(UpdateMode updateMode)
      Sets the update mode used by update operations.
      Parameters:
      updateMode - the update mode to use; UpdateMode.MERGE when null

    • isSanityCheckDeferred

      public boolean isSanityCheckDeferred()
      Returns whether sanity checks are deferred to the caller.
      Returns:
      true if sanity checks are deferred

    • setSanityCheckDeferred

      public void setSanityCheckDeferred(boolean sanityCheckDeferred)
      Defers immediate sanity checks for atomic orchestration flows.
      Parameters:
      sanityCheckDeferred - true to defer sanity checks

    • cleanCachedSerialization

      protected void cleanCachedSerialization()
      Invalidates the cached direct and complete JSON representations.

    • getUUID

      public UUID getUUID()
      Returns the UUID identifier of this element.
      Returns:
      the UUID identifier

    • isDryRun

      public boolean isDryRun()
      Returns whether this operation is running as a dry run simulation.
      Returns:
      true if dry run is enabled, false otherwise

    • setDryRun

      public void setDryRun(boolean dryRun)
      Sets whether this operation should run as a dry run simulation.
      Parameters:
      dryRun - true to simulate the operation, false to commit

    • concludeTransaction

      protected void concludeTransaction(String successMessage)
      Concludes the active database transaction. Commits the transaction if dryRun is disabled, or performs a rollback to simulate the changes if dryRun is enabled.
      Parameters:
      successMessage - the message to log upon successful commit

    • isReload

      public boolean isReload()
      Returns whether to force a reload from the database.
      Returns:
      true to force reload, false otherwise

    • setReload

      public void setReload(boolean reload)
      Sets whether to force a reload from the database.
      Parameters:
      reload - true to force reload, false otherwise

    • getAccessType

      public org.gcube.informationsystem.base.reference.AccessType getAccessType()
      Returns the access type category of this element.
      Returns:
      the access type category

    • getWorkingEnvironment

      protected abstract Environment getWorkingEnvironment() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns the active database working environment.
      Returns:
      the working environment
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the environment cannot be resolved

    • setWorkingEnvironment

      public void setWorkingEnvironment(Environment workingContext)
      Sets the active database working environment.
      Parameters:
      workingContext - the working environment to set

    • setUUID

      public void setUUID(UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Sets the UUID identifier of this element and validates it if a JSON node is already set.
      Parameters:
      uuid - the UUID to set
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the UUID does not match the JSON node identifier

    • setJsonNode

      public void setJsonNode(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Sets the input JSON representation node of this element.
      Parameters:
      jsonNode - the JSON node to set
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the JSON structure is invalid

    • setJson

      public void setJson(String json) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Sets the input JSON string representation of this element.
      Parameters:
      json - the JSON string to parse and set
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the JSON string is invalid

    • setODatabaseDocument

      public void setODatabaseDocument(com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument)
      Sets the active database connection document session.
      Parameters:
      oDatabaseDocument - the database session

    • setOClass

      public void setOClass(com.orientechnologies.orient.core.metadata.schema.OClass oClass)
      Sets the OrientDB schema class.
      Parameters:
      oClass - the schema class

    • getOClass

      protected com.orientechnologies.orient.core.metadata.schema.OClass getOClass() throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns the schema class (OClass) associated with this element.
      Returns:
      the OrientDB OClass
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if the schema cannot be resolved
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on any database error

    • getCachedType

      protected CachedType<T> getCachedType()
      Returns the cached schema type definition, initializing it if not present.
      Returns:
      the cached schema type definition

    • setElementType

      public void setElementType(String elementType) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Sets the element schema type name.
      Parameters:
      elementType - the schema type name to set
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the type name is empty or invalid

    • getTypeName

      public String getTypeName() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns the canonical type name of the element.
      Returns:
      the type name string
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the element belongs to another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or lookup failure

    • checkJsonNode

      protected void checkJsonNode() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Validates the input JSON node and extracts the UUID and schema type.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the JSON structure is invalid or violates constraints

    • checkERMatch

      protected void checkERMatch() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Validates that the schema type of the JSON node matches the configured type name.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the schema types do not match

    • checkUUIDMatch

      protected void checkUUIDMatch() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Validates that the UUID inside the JSON node matches the configured element UUID.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the UUIDs do not match

    • serializeAsAffectedInstance

      public org.gcube.com.fasterxml.jackson.databind.JsonNode serializeAsAffectedInstance() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Serializes this element as an element of an Operation Envelope. Every element of the envelope is a root element, so the root metadata and contexts policies enrich each of them; the cached representations are not touched.
      Returns:
      the serialized JSON node representation
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if serialization fails

    • serializeAsEndpointReference

      public org.gcube.com.fasterxml.jackson.databind.JsonNode serializeAsEndpointReference(boolean includeMetadata, boolean includeContexts) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Serializes this element as the endpoint reference of a Relation: type, supertypes and id, plus metadata and contexts only when requested; never its custom fields nor its relations.
      Parameters:
      includeMetadata - whether to include metadata (masked as configured)
      includeContexts - whether to include contexts
      Returns:
      the endpoint reference
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if serialization fails

    • serializeSelfAsJsonNode

      public org.gcube.com.fasterxml.jackson.databind.JsonNode serializeSelfAsJsonNode() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Serializes and returns the raw/local JSON representation of this element (without relationships).
      Returns:
      the serialized JSON node representation
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if serialization fails

    • createCompleteJsonNode

      protected abstract org.gcube.com.fasterxml.jackson.databind.JsonNode createCompleteJsonNode() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Abstract method to create the complete JSON node representation of the element.
      Returns:
      the complete JSON node representing the element and its relationships
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on serialization or mapping error

    • serializeAsJsonNode

      public org.gcube.com.fasterxml.jackson.databind.JsonNode serializeAsJsonNode() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Serializes and returns the complete JSON representation of this element (including relationships).
      Returns:
      the serialized JSON node representation
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if serialization fails

    • reallyCreate

      protected abstract El reallyCreate() throws org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Persists a new element in the database (subclass hook).
      Returns:
      the persisted OrientDB vertex
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - if the element already exists in the database
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on any database error

    • requireExplicitUUID

      protected boolean requireExplicitUUID()
      Returns whether a missing `id` on creation must be rejected rather than auto-generated.
      Returns:
      true if a missing `id` must be rejected rather than auto-generated

    • setRequireExplicitUUID

      public void setRequireExplicitUUID(boolean requireExplicitUUID)
      Sets whether a missing `id` on creation must be rejected rather than auto-generated.
      Parameters:
      requireExplicitUUID - true to reject a missing `id` instead of auto-generating one

    • internalCreate

      public El internalCreate() throws org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Performs the internal database creation and registration of the element. Metadata is autofilled from the current caller and clock, unless isPreservePassedMetadata() is true and the submitted JSON already carries a metadata object, in which case that object is persisted as-is.
      Returns:
      the newly created OrientDB vertex
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - if the element already exists
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or creation failure

    • checkUUIDNotAlreadyInUse

      protected void checkUUIDNotAlreadyInUse() throws org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException, org.gcube.informationsystem.resourceregistry.api.exceptions.UUIDAlreadyInUseException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Rejects UUID reuse before creating a brand-new element: a UUID is occupied by any element of any type in any Context, and a creation with an occupied UUID is a conflict. A UUID already bound to an element of the same type, in any Context, is an AlreadyPresentException; the same UUID bound to an element of a different type is a UUIDAlreadyInUseException.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - if an element of the same type already carries this UUID
      org.gcube.informationsystem.resourceregistry.api.exceptions.UUIDAlreadyInUseException - if the UUID is already bound to an element of a different type
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • reallyUpdate

      protected abstract El reallyUpdate() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Updates an existing element in the database (subclass hook).
      Returns:
      the updated OrientDB vertex
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist in the database
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on any database error

    • internalUpdate

      public El internalUpdate() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Performs the internal database update and metadata refresh of the element.
      Returns:
      the updated OrientDB vertex
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or update failure

    • internalCreateOrUdate

      public El internalCreateOrUdate() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Performs an internal idempotent database upsert (update if exists, otherwise create).
      Returns:
      the created or updated OrientDB vertex
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or upsert failure

    • reallyDelete

      protected abstract void reallyDelete() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Deletes an existing element from the database (subclass hook).
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist in the database
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on any database error

    • internalDelete

      public void internalDelete() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Deletes an existing element from the database.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • setElement

      public void setElement(El element) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Binds an existing OrientDB element instance to this manager.
      Parameters:
      element - the OrientDB element to bind
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the element is null or schema metadata lookup fails

    • getSpecificNotFoundException

      protected abstract org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException getSpecificNotFoundException(org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException e)
      Converts a generic NotFoundException into a subclass-specific NotFoundException.
      Parameters:
      e - the generic exception
      Returns:
      the specific NotFoundException

    • getSpecificAlreadyPresentException

      protected abstract org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException getSpecificAlreadyPresentException(String message)
      Converts a generic AlreadyPresentException into a subclass-specific AlreadyPresentException.
      Parameters:
      message - the exception message
      Returns:
      the specific AlreadyPresentException

    • getElement

      public El getElement() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns the OrientDB element instance, retrieving and caching it if not already present.
      Returns:
      the OrientDB element instance
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the element belongs to another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • retrieveElement

      public El retrieveElement() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Directly queries and retrieves the OrientDB element from the database.
      Returns:
      the loaded OrientDB element
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • retrieveElementFromAnyContext

      public El retrieveElementFromAnyContext() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Queries and retrieves the OrientDB element from any database security context (bypassing RLS).
      Returns:
      the loaded OrientDB element
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • reallyGetAll

      public abstract String reallyGetAll() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves all elements from the database and returns them as a JSON array string.
      Returns:
      JSON array string of all elements
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database traversal or serialization error

    • getCurrentODatabaseDocumentFromThreadLocal

      public static com.orientechnologies.orient.core.db.document.ODatabaseDocument getCurrentODatabaseDocumentFromThreadLocal()
      Returns the ODatabaseDocument currently bound to this thread by OrientDB's thread-local stack, or null if no database is active on this thread.
      Returns:
      the currently active ODatabaseDocument, or null

    • all

      public String all() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves and returns all elements of this type from the database as a JSON array string.
      Returns:
      JSON array string representing all matching elements
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the database query fails

    • exists

      public boolean exists() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns whether the element with the configured UUID exists in the database.
      Returns:
      true if the element exists, false otherwise
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the element belongs to another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • createOrUpdate

      public String createOrUpdate() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Atomically creates or updates the element in the database (idempotent upsert).
      Returns:
      the serialized JSON representation of the element
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element to update does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the element belongs to another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • createOrUpdateElementWithResult

      public ElementCreationResult createOrUpdateElementWithResult() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Atomically creates or updates the element and preserves the resulting operation kind.
      Returns:
      the serialized representation and whether a new element was created
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element to update does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the element belongs to another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • create

      public String create() throws org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates a new element in the database.
      Returns:
      the serialized JSON representation of the created element
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - if the element already exists
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • read

      public String read() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads and returns the complete serialized JSON string of the element.
      Returns:
      the serialized JSON string representation of the element
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the element belongs to another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or read failure

    • update

      public String update() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Updates the element in the database using the provided JSON representation.
      Returns:
      the serialized JSON string of the updated element
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the element belongs to another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or update failure

    • delete

      public void delete() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Deletes this element from the database.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the element does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the element belongs to another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - if deletion violates topological constraints
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • isBackendLinkFieldName

      public static boolean isBackendLinkFieldName(String name)
      Returns whether a name is reserved to the backend fields linking Entities and Relations: in, out and every name starting with in_ or out_, in lower or upper case. An instance of any category never stores a custom field so named.
      Parameters:
      name - the field name
      Returns:
      true if the name is reserved

    • getPropertyMap

      public Map<String,org.gcube.com.fasterxml.jackson.databind.JsonNode> getPropertyMap(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, Set<String> ignoreKeys, Set<String> ignoreStartWith) throws org.gcube.com.fasterxml.jackson.core.JsonProcessingException, IOException
      Extracts and returns a flat key-value map of properties from a JSON representation node, skipping any ignored keys and prefixes.
      Parameters:
      jsonNode - the JSON representation node
      ignoreKeys - the set of keys to ignore/exclude
      ignoreStartWith - the set of key prefixes to ignore/exclude
      Returns:
      the mapped properties
      Throws:
      org.gcube.com.fasterxml.jackson.core.JsonProcessingException - on Jackson parsing error
      IOException - on stream reading error

    • setProperty

      public void setProperty(com.orientechnologies.orient.core.metadata.schema.OProperty oProperty, String key, org.gcube.com.fasterxml.jackson.databind.JsonNode value) throws Exception
      Helper method to map and set a JSON property value onto the OrientDB vertex based on its schema type. A literal JSON null removes the property instead of being mapped to a value: under UpdateMode.MERGE per RFC 7396 §1, under UpdateMode.REPLACE because an explicit null means the same as an omitted key.
      Parameters:
      oProperty - the schema property definition
      key - the property key string
      value - the JSON value node to map
      Throws:
      Exception - if mapping or value assignment fails

    • updateProperties

      public com.orientechnologies.orient.core.record.OElement updateProperties(com.orientechnologies.orient.core.metadata.schema.OClass oClass, com.orientechnologies.orient.core.record.OElement element, org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, Set<String> ignoreKeys, Set<String> ignoreStartWithKeys) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Updates the properties of an OrientDB OElement from a JSON payload node. Under UpdateMode.REPLACE, property keys present on the element but omitted from jsonNode are removed. Under UpdateMode.MERGE (the field's default, see updateMode), omitted keys are left untouched. In both modes a literal JSON null removes the property, as RFC 7396 §1 has it for a merge, and as an omitted key already does under a full replace. Callers whose update semantics are always full-replace (e.g. schema/type, Context, and Query Template updates) must call setUpdateMode(UpdateMode) with UpdateMode.REPLACE before invoking this method, since the field otherwise defaults to MERGE.

      For a graph instance, the fields dropped because their name breaks the property naming rule (the reserved prefixes included) are recorded, those inside a nested Property value in dot notation (see getIgnoredFields()), a mandatory property left without a value by a creation or a replacement takes its declared defaultValue, and an update that changes a readonly property is a conflict.

      Parameters:
      oClass - the schema class of the element
      element - the OrientDB element to update
      jsonNode - the input JSON payload node
      ignoreKeys - the set of keys to ignore/exclude
      ignoreStartWithKeys - the set of key prefixes to ignore/exclude
      Returns:
      the updated OrientDB element
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - if an update changes a readonly property
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on property setting or mapping error

    • applyPrivacyMask

      public static org.gcube.com.fasterxml.jackson.databind.node.ObjectNode applyPrivacyMask(org.gcube.com.fasterxml.jackson.databind.node.ObjectNode metadataJson)
      Masks privacy-sensitive fields in the given metadata JSON node by replacing Metadata.CREATED_BY_PROPERTY and Metadata.LAST_UPDATE_BY_PROPERTY with the Element.REDACTED placeholder.

      This method is static so it can be reused by other classes (e.g., RedisContextCache) without duplicating the masking logic.

      Delegates to applyPrivacyMask(ObjectNode, boolean) with keepUserMeta=false, so all sensitive fields are always masked regardless of the current user's identity.

      Parameters:
      metadataJson - the metadata JSON node to mask.
      Returns:
      the same metadataJson instance, with privacy-sensitive fields replaced.

    • applyPrivacyMask

      public static org.gcube.com.fasterxml.jackson.databind.node.ObjectNode applyPrivacyMask(org.gcube.com.fasterxml.jackson.databind.node.ObjectNode metadataJson, boolean keepUserMeta)
      Masks privacy-sensitive fields in the given metadata JSON node, with optional identity-aware behaviour controlled by keepUserMeta.

      When keepUserMeta is false, both Metadata.CREATED_BY_PROPERTY and Metadata.LAST_UPDATE_BY_PROPERTY are unconditionally replaced with Element.REDACTED.

      When keepUserMeta is true, each field is only masked if its current value does not match the id of the calling user (retrieved from SecretManagerProvider), so a user can always read their own entries in clear.

      This method has no cache dependency either way: every caller — both cached reads (e.g. ContextRepository.filterContextNode(org.gcube.com.fasterxml.jackson.databind.node.ObjectNode, org.gcube.informationsystem.resourceregistry.contexts.ContextRepository.ContextProjection)) and live DB serialization (e.g. getPropertyForJson(String, Object)) — applies masking to a freshly fetched/copied node on each request, after the shared cache lookup, never before it; the shared caches themselves never store an already-masked value. So keepUserMeta=true would not leak between users even on a cached path. It is simply not wired to any caller yet: no REST/PEP layer currently requests a "reveal my own metadata" projection. Enabling it is caller-side work (threading a new projection flag from the PEP down to this call), not blocked on any caching-architecture change.

      Parameters:
      metadataJson - the metadata JSON node to mask.
      keepUserMeta - if true, fields matching the current user's id are left unmasked.
      Returns:
      the same metadataJson instance, with privacy-sensitive fields replaced where applicable.

    • getPropertyForJson

      protected org.gcube.com.fasterxml.jackson.databind.JsonNode getPropertyForJson(String key, Object object) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Converts an OrientDB property value object into a Jackson JsonNode for JSON serialization.
      Parameters:
      key - the name of the property
      object - the database property value
      Returns:
      the serialized JSON node, or null
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if mapping or privacy filtering fails

    • getMandatoryErrorMessage

      protected String getMandatoryErrorMessage(String fieldName)
      Formats and returns the error message for a missing mandatory field schema violation.
      Parameters:
      fieldName - the name of the mandatory field
      Returns:
      the formatted error message

    • getMandatoryErrorMessage

      public static String getMandatoryErrorMessage(String typeName, String fieldName)
      Formats and returns the error message for a missing mandatory field of the given type.
      Parameters:
      typeName - the name of the type declaring the field
      fieldName - the name of the mandatory field
      Returns:
      the formatted error message

    • typeSatified

      protected boolean typeSatified(String requiredType, String effectiveType) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Validates whether the effective type satisfies the required type (supports schema inheritance).
      Parameters:
      requiredType - the required schema type name
      effectiveType - the effective schema type name
      Returns:
      true if the effective type matches or extends the required type, false otherwise
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if the schema type definitions are invalid
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • getAllProperties

      protected Set<org.gcube.informationsystem.types.reference.properties.PropertyDefinition> getAllProperties() throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves and returns all property definitions for this schema type, including those inherited from all of its supertypes.
      Returns:
      the set of all property definitions
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if schema traversal fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • sanityCheck

      public void sanityCheck() throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Performs runtime validation of mandatory and not-null schema constraints that cannot be enforced directly by OrientDB in distributed mode.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - if a schema constraint is violated
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database lookup failure