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.

    • includeContexts

      protected boolean includeContexts
      Whether the executed template's results should include the list of contexts where each instance is available.

    • contextVisibilityPolicy

      protected ContextVisibilityPolicy contextVisibilityPolicy
      The context visibility policy applied to the executed template's results.

    • currentContextPath

      protected String currentContextPath
      The caller's current Context path, used when contextVisibilityPolicy is not ContextVisibilityPolicy.ALL.

    • filterNonActiveDescendants

      protected boolean filterNonActiveDescendants
      Whether non-active descendant memberships must be omitted from included context maps.

    • projection

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

  • 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
      Description copied from class: ElementManagement
      Validates the input JSON node and extracts the UUID and schema type.
      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 JSON structure is invalid or violates constraints

    • 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, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Validates the template definition by executing a trial run.
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the query or its default substitutions are invalid
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if validation encounters a registry failure

    • 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
      Creates a new Query Template, or updates an existing one with the same name, also reporting whether a brand new Query Template was registered.

      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 on update).

      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.ResourceRegistryException - on any other persistence failure

    • 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

    • setIncludeContexts

      public void setIncludeContexts(boolean includeContexts)
      Sets whether the executed template's results should include the list of contexts where each returned instance is available.
      Parameters:
      includeContexts - true to include context availability information

    • setContextVisibilityPolicy

      public void setContextVisibilityPolicy(ContextVisibilityPolicy contextVisibilityPolicy)
      Sets the context visibility policy applied to the executed template's results.
      Parameters:
      contextVisibilityPolicy - the visibility policy to apply

    • setCurrentContextPath

      public void setCurrentContextPath(String currentContextPath)
      Sets the caller's current Context path, used when contextVisibilityPolicy is not ContextVisibilityPolicy.ALL.
      Parameters:
      currentContextPath - the caller's current Context path

    • setFilterNonActiveDescendants

      public void setFilterNonActiveDescendants(boolean filterNonActiveDescendants)
      Sets whether non-active descendant memberships must be omitted from included context maps.
      Parameters:
      filterNonActiveDescendants - true to omit non-active descendant memberships

    • 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 (falling back to each omitted variable's own default value, per QueryTemplate.getJsonQuery(JsonNode)), honouring the limit, offset, polymorphic, hierarchical, includeContexts, and metadataPolicy fields already configured on this instance via their respective setters, including the inherited metadata-masking directive.
      Returns:
      the result as JSON string
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the template execution parameters are invalid (e.g. a mandatory template variable with no default value was not provided)
      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

    • 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 mandatory and not-null schema constraints that cannot be enforced directly by OrientDB in distributed mode.
      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