Package org.gcube.informationsystem.resourceregistry.persistence.orientdb.queries.templates

Class QueryTemplateManagement

java.lang.Object
org.gcube.informationsystem.resourceregistry.persistence.orientdb.base.ElementManagement<com.orientechnologies.orient.core.record.OVertex,ET>
org.gcube.informationsystem.resourceregistry.persistence.orientdb.base.EntityElementManagement<org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate,org.gcube.informationsystem.types.reference.entities.EntitySchema>
org.gcube.informationsystem.resourceregistry.persistence.orientdb.queries.templates.QueryTemplateManagement
public class QueryTemplateManagement extends EntityElementManagement<org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate,org.gcube.informationsystem.types.reference.entities.EntitySchema>
Author:
Luca Frosini (ISTI - CNR)

  • Field Details

    • name

      protected String name
      The name of the query template.

    • params

      protected org.gcube.com.fasterxml.jackson.databind.JsonNode params
      The parameters for the query template.

    • hierarchical

      protected boolean hierarchical
      Whether the executed template's underlying query should search descendant Contexts too.

    • activeOnlyHierarchical

      protected boolean activeOnlyHierarchical
      Whether hierarchical execution must use the active-only reader channel.

    • contextsPolicy

      protected org.gcube.informationsystem.resourceregistry.api.rest.ContextsPolicy contextsPolicy
      The contexts inclusion policy applied to the executed template's results.

    • membershipView

      protected MembershipView membershipView
      The view that selects the memberships listed by the contexts map of each result.

    • projection

      protected boolean projection
      Whether the last query(String) or run() call executed an _emit projection.

    • ignoredParams

      protected Set<String> ignoredParams
      The supplied execution keys that declare no variable, set by the last run() call.

  • Constructor Details

    • QueryTemplateManagement

      public QueryTemplateManagement()
      Creates a new QueryTemplateManagement instance.

    • QueryTemplateManagement

      public QueryTemplateManagement(com.orientechnologies.orient.core.db.document.ODatabaseDocument oDatabaseDocument) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates a new QueryTemplateManagement instance bound to the specified database.
      Parameters:
      oDatabaseDocument - the database connection
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if initialization fails

  • Method Details

    • checkNameMatch

      protected void checkNameMatch() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Validates that the template name matches the JSON property.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateException - if the name is missing or differs
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

    • setName

      public void setName(String name) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Sets the name of the query template and validates its consistency.
      Parameters:
      name - the template name to set
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if name validation fails

    • checkJsonNode

      protected void checkJsonNode() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Validates the submitted definition against the Query Template contract and replaces it with its normalized form before the generic checks.
      Overrides:
      checkJsonNode in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the definition is invalid

    • checkERMatch

      protected void checkERMatch() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Validates that the schema type of the JSON node matches the configured type name.
      Overrides:
      checkERMatch in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the schema types do not match

    • getName

      public String getName()
      Returns the name of the query template.
      Returns:
      the template name

    • getWorkingEnvironment

      protected Environment getWorkingEnvironment() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Returns the active database working environment.
      Specified by:
      getWorkingEnvironment in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Returns:
      the working environment
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the environment cannot be resolved

    • createCompleteJsonNode

      protected org.gcube.com.fasterxml.jackson.databind.JsonNode createCompleteJsonNode() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Abstract method to create the complete JSON node representation of the element.
      Specified by:
      createCompleteJsonNode in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Returns:
      the complete JSON node representing the element and its relationships
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on serialization or mapping error

    • getSelectQuery

      protected StringBuffer getSelectQuery()
      Helper method to build the SQL SELECT query for resolving a template by name.
      Returns:
      the built SELECT query

    • checkIfNameAlreadyExists

      protected void checkIfNameAlreadyExists() throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateAlreadyPresentException
      Checks if a template with the current name already exists in the database.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateAlreadyPresentException - if a template with the same name exists

    • tryTemplate

      protected void tryTemplate() throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException
      Validates the query produced by substituting every default value: its root must be an Entity or Relation Type and the query must build. The query is never executed, so the validation does not depend on the token Context or its state.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the query produced by the default values is invalid

    • retrieveElement

      public com.orientechnologies.orient.core.record.OVertex retrieveElement() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Directly queries and retrieves the OrientDB element from the database.
      Overrides:
      retrieveElement in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      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

    • 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
      Description copied from class: ElementManagement
      Atomically creates or updates the element in the database (idempotent upsert).
      Overrides:
      createOrUpdate in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      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

    • createOrUpdateWithResult

      public QueryTemplateCreationResult createOrUpdateWithResult() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Applies PUT /query-templates/{name}, the versioned upsert of a Query Template: creates it when the name is absent, updates it when the submitted version is an accepted advancement, and leaves it untouched when the submitted definition is the persisted one.

      createOrUpdate() is the EntityElementManagement contract method shared with unrelated create/update paths that don't need the distinction; this method exists so PUT /query-templates/{name} can respond with the correct HTTP status (201 Created on genuine creation, 200 OK otherwise).

      Returns:
      the outcome, carrying the serialized Query Template JSON and a created/updated flag
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - if the update path cannot locate a required resource
      org.gcube.informationsystem.resourceregistry.api.exceptions.instances.AvailableInAnotherContextException - if the Query Template is available in another context
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateAlreadyPresentException - if the submission conflicts with the persisted Query Template, or a concurrent submission created the same name
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on any other persistence failure

    • checkUpdatable

      protected boolean checkUpdatable() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks that the submitted definition may replace the persisted one, following the Versioned Upsert Semantics and the Version Advancement rules. The comparison covers the complete definition except id and metadata.
      Returns:
      true when the submitted definition is the persisted one (same version and identical definition), so nothing has to be written
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateAlreadyPresentException - if the submitted id differs from the persisted one, or the submission conflicts with the persisted version, definition or changelog
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if the persisted Query Template cannot be read, or has no version

    • reallyCreate

      protected com.orientechnologies.orient.core.record.OVertex reallyCreate() throws org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException, org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Persists a new element in the database (subclass hook).
      Specified by:
      reallyCreate in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      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
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException

    • reallyUpdate

      protected com.orientechnologies.orient.core.record.OVertex reallyUpdate() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Updates an existing element in the database (subclass hook).
      Specified by:
      reallyUpdate in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      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

    • reallyDelete

      protected void reallyDelete() throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Deletes an existing element from the database (subclass hook).
      Specified by:
      reallyDelete in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      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

    • getSpecificNotFoundException

      protected org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException getSpecificNotFoundException(org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException e)
      Description copied from class: ElementManagement
      Converts a generic NotFoundException into a subclass-specific NotFoundException.
      Specified by:
      getSpecificNotFoundException in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Parameters:
      e - the generic exception
      Returns:
      the specific NotFoundException

    • getSpecificAlreadyPresentException

      protected org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException getSpecificAlreadyPresentException(String message)
      Description copied from class: ElementManagement
      Converts a generic AlreadyPresentException into a subclass-specific AlreadyPresentException.
      Specified by:
      getSpecificAlreadyPresentException in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Parameters:
      message - the exception message
      Returns:
      the specific AlreadyPresentException

    • reallyGetAll

      public String reallyGetAll() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Retrieves all elements from the database and returns them as a JSON array string.
      Specified by:
      reallyGetAll in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      Returns:
      JSON array string of all elements
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database traversal or serialization error

    • query

      public String query(String jsonQuery) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a JSON query against the QueryTemplate collection, returning matching QueryTemplate definitions (not their execution results).

      Honours the limit, offset, and metadataPolicy fields already configured on this instance via ElementManagement.setLimit(Integer), ElementManagement.setOffset(Integer), and ElementManagement.setMetadataPolicy(org.gcube.informationsystem.resourceregistry.api.rest.MetadataPolicy).

      Parameters:
      jsonQuery - the JSON query payload describing the QueryTemplate search criteria
      Returns:
      JSON array string of matching QueryTemplate 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

    • setParams

      public void setParams(String params) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException
      Sets the parameters from a JSON string.
      Parameters:
      params - the JSON string representing the parameters
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the payload is malformed or is not a JSON object

    • setParams

      public void setParams(org.gcube.com.fasterxml.jackson.databind.JsonNode params) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException
      Sets the parameters from a JsonNode.
      Parameters:
      params - the JsonNode representing the parameters
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the node is not a JSON object

    • setHierarchical

      public void setHierarchical(boolean hierarchical)
      Sets whether the executed template's underlying query should search descendant Contexts too.
      Parameters:
      hierarchical - true to expand the search boundary to descendant Contexts

    • setActiveOnlyHierarchical

      public void setActiveOnlyHierarchical(boolean activeOnlyHierarchical)
      Sets whether hierarchical execution must use the active-only reader channel.
      Parameters:
      activeOnlyHierarchical - true to hide non-active descendant Contexts

    • setContextsPolicy

      public void setContextsPolicy(org.gcube.informationsystem.resourceregistry.api.rest.ContextsPolicy contextsPolicy)
      Sets the contexts inclusion policy applied to the executed template's results.
      Parameters:
      contextsPolicy - the contexts policy to set

    • setMembershipView

      public void setMembershipView(MembershipView membershipView)
      Sets the view that selects the memberships listed by the contexts map of each result.
      Parameters:
      membershipView - the membership view to apply

    • run

      public String run() throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Runs the template query after substituting its variables with the provided values, which are validated first (an omitted variable takes its default unless it is required), honouring the limit, offset, polymorphic, hierarchical, contextsPolicy, and metadataPolicy fields already configured on this instance via their respective setters, including the inherited metadata-masking directive. The supplied keys that declare no variable are reported by getIgnoredParams().
      Returns:
      the result as JSON string
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the template execution parameters are invalid (a required variable omitted, an explicit null, a type or constraint violation)
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during query execution

    • isProjection

      public boolean isProjection()
      Reports whether the last query(String) or run() call was projection-based (i.e. the query contained an _emit block). See InstancesJsonQueryExecutor.isProjection().
      Returns:
      true if the last query was projection-based, false otherwise

    • getIgnoredParams

      public Set<String> getIgnoredParams()
      Returns the supplied execution keys that declare no variable of the template, as found by the last run() call.
      Returns:
      the ignored keys, empty when every supplied key declares a variable

    • sanityCheck

      public void sanityCheck() throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Description copied from class: ElementManagement
      Performs runtime validation of the schema constraints this service enforces from the definition rather than through OrientDB: the mandatory properties, and the min and max bounds of the numeric values a creation or an update wrote.
      Overrides:
      sanityCheck in class ElementManagement<com.orientechnologies.orient.core.record.OVertex,org.gcube.informationsystem.types.reference.entities.EntitySchema>
      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