Package org.gcube.informationsystem.resourceregistry.queries.json.base

Class JsonQueryElement

java.lang.Object
org.gcube.informationsystem.resourceregistry.queries.json.base.JsonQueryElement
Direct Known Subclasses:
JsonQueryContext, JsonQueryEntitySchema, JsonQueryERElement, JsonQueryPropertySchema, JsonQueryQueryTemplate, JsonQueryRelationSchema
public abstract class JsonQueryElement extends Object
Base class translating a JSON query subtree into an SQL/MATCH fragment.

Covers every collection queryable via the JSON Query engine, whether or not it participates in graph relation traversal. Relation-traversal-specific concerns (edge direction, back-reference traversal) live exclusively in JsonQueryERElement, the subclass used by Resources/Facets/Relations — a flat, standalone collection (e.g. QueryTemplate, Context) extends this class directly.

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 of the query element.
    protected String
    alias
    Contains the alias if needed by the class
    protected static final Set<String>
    BACKEND_LINK_FIELD_PREFIXES
    The prefixes of the backend fields linking an Entity to its Relations.
    protected static final Set<String>
    BACKEND_LINK_FIELDS
    The backend fields linking a Relation to its source and target.
    protected static final String
    BACKEND_TYPE_NAME_FIELD
    The backend property holding the Type name of an element, which the representation names Element.TYPE_PROPERTY.
    protected List<JsonQueryElement>
    breadcrumb
    The chain of callers of this instance analyzer.
    protected static final String
    CREATED_BY_PATH
    The path of the identity of the creator, sensitive for the callers that read it redacted.
    protected final DeclaredPropertyResolver
    declaredPropertyResolver
    The resolver of the declared property domains, owned by the entry-point element.
    protected static final Pattern
    ELEMENT_INDEX_PATTERN
    The index of an element in a field name.
    protected String
    encryptedTypeParameters
    The bound names of the Encrypted Type and of its subtypes, null until a predicate needs them; owned by the entry-point element.
    protected boolean
    entryPoint
    Whether this query element represents the root entry point of the query.
    protected static final String
    FALSE_CONDITION
    The condition emitted for a predicate that never matches.
    protected static final Pattern
    FIELD_NAME_PATTERN
    The grammar of a field name: a dot-separated path of plain identifiers, each optionally followed by the index of an element.
    protected final Set<String>
    fieldNamesToRemove
    The set of field names to ignore/remove during query translation.
    protected List<String>
    fieldsToEmit
    This field is used by entry point only.
    protected static final String
    IS_NULL
    The condition suffix emitted for a direct null value.
    protected final org.gcube.com.fasterxml.jackson.databind.JsonNode
    jsonNode
    The JSON query subtree node representing this element.
    protected static final String
    LAST_UPDATE_BY_PATH
    The path of the identity of the last updater, sensitive for the callers that read it redacted.
    protected org.slf4j.Logger
    logger
    The logger instance for query generation auditing.
    protected boolean
    maskMetadata
    Whether the caller reads the sensitive metadata identity fields redacted; owned by the entry-point element.
    protected final org.gcube.com.fasterxml.jackson.databind.ObjectMapper
    objectMapper
    In-use Jackson object mapper.
    protected final OperandValidator
    operandValidator
    The validator of the operator operands.
    static final String
    OPERATOR_PREFIX
    The prefix of every query operator and directive key.
    protected boolean
    polymorphic
    Whether the root match may include registered subtypes.
    protected int
    position
    The breadcrumb.size() provide the level of nesting.
    protected boolean
    projection
    Instruct the JSON query analyzer if it is a projection.
    protected int
    queryParameterIndex
    Monotonic parameter index owned by the entry-point element.
    protected Map<String,Object>
    queryParameters
    Caller-supplied scalar values bound to the generated OrientDB query.
    protected static final String
    RECORD_ATTRIBUTE_PREFIX
    The prefix of the backend record attributes, none of which is a field of the representation.
    protected int
    size
    it indicates the number of properties in this.jsonNode This number is manipulated while analyzing the jsonNode to properly create the query.
    protected final String
    type
    The schema type name of the query element.
    protected final Map<String,String>
    unqueryableFields
    The fields of the query element that a query can neither filter on nor project, each with the reason reported to the caller.

  • Constructor Summary

    Constructors
    Constructor
    Description
    JsonQueryElement(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonQuery, org.gcube.informationsystem.base.reference.AccessType accessType)
    Creates a new JsonQueryElement instance for the specified JSON query subtree.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected StringBuffer
    addComparisonConstraint(ComparisonOperator comparisonOperator, org.gcube.com.fasterxml.jackson.databind.JsonNode operand, String fieldNamePrefix)
    Builds the condition of a comparison, presence, collection or map operator applied to the property identified by the field name prefix.
    protected StringBuffer
    addConstraints(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, String fieldNamePrefix)
    Builds the conjunction of the constraints expressed by the fields of a JSON object.
    protected void
    addFieldToEmit(String fieldToEmit)
    Adds a field to emit to the entry point, which generates the RETURN clause of the query.
    protected StringBuffer
    addLogicalConstraints(LogicalOperator logicalOperator, org.gcube.com.fasterxml.jackson.databind.JsonNode operand, String fieldNamePrefix)
    Builds the condition of a logical operator.
    StringBuffer
    createMatchQuery(StringBuffer stringBuffer)
    Builds and appends the complete SQL MATCH query for this subtree.
    StringBuffer
    createQuery(StringBuffer stringBuffer)
    Translates this query element into a corresponding SQL query buffer (defaults to MATCH query).
    protected StringBuffer
    evaluateNode(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, String fieldName, String fieldNamePrefix)
    Evaluates a single JSON property node and appends its filter condition to the query.
    protected StringBuffer
    excludeEncrypted(String key, PropertyDomain domain, StringBuffer condition)
    Makes a predicate on a field the Type definition does not declare false wherever the field, or a field its path goes through, holds an Encrypted value.
    protected StringBuffer
    generateAlias()
    Returns the unique alias buffer for this query element.
    String
    getAlias()
    Returns the alias associated with this element.
    String
    getAlias(boolean generateifNull)
    Returns the alias associated with this element, optionally generating it if not present.
    List<JsonQueryElement>
    getBreadcrumb()
    Returns the list of parent query elements visited.
    protected List<JsonQueryElement>
    getChildrenBreadcrumb()
    Returns the list of query elements visited down to the current node.
    protected String
    getFieldOperand(String key)
    Returns the left-hand operand of a predicate on a field: the field itself, or the bound constant Element.REDACTED when the caller reads the field redacted, so that the predicate never depends on the stored identity.
    protected String
    getFieldReference(String key)
    Returns the SQL reference of a projected field: the field of this element, or the bound constant Element.REDACTED when the caller reads the field redacted.
    protected String
    getKey(String fieldName, String fieldNamePrefix)
    Formats and returns a fully-qualified property field key path.
    int
    getPosition()
    Returns the position level of this element.
    protected PropertyDomain
    getPropertyDomain(String key)
    Returns the domain the Type definition of this element declares for a field.
    Map<String,Object>
    getQueryParameters()
    Returns a snapshot of the parameters generated while translating this query tree.
    static String
    getRequiredType(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonQuery)
    Returns the type declared by a level of the query that describes an instance.
    protected String
    getScalarValue(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode)
    Binds a single scalar JSON node value as an OrientDB named parameter.
    protected String
    getScalarValue(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, PropertyDomain domain)
    Binds a single scalar JSON node value, compared with a property of the given declared domain, as an OrientDB named parameter.
    protected abstract StringBuffer
    getSpecificMatchQuery(List<JsonQueryElement> childrenBreadcrumb)
    Generates the specific MATCH query snippet for this element's subclass (subclass hook).
    String
    getType()
    Returns the schema type name of this element.
    protected String
    getValue(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, PropertyDomain domain)
    Converts a JSON value to one or more OrientDB named-parameter placeholders.
    boolean
    isEntryPoint()
    Returns whether this query element represents the root entry point of the query.
    boolean
    isProjection()
    Returns whether this query element is part of a projection.
    protected boolean
    isSensitiveField(String key)
    Returns whether the caller reads the field as the constant Element.REDACTED: the metadata.createdBy and metadata.lastUpdateBy of the element of this level, when the query is evaluated for a caller who is shown them redacted.
    protected String
    resolveFieldName(String fieldName)
    Validates a field name and returns the name written in the generated query.
    void
    setBreadcrumb(List<JsonQueryElement> breadcrumb)
    Sets the list of parent query elements visited.
    void
    setEntryPoint(boolean entryPoint)
    Sets whether this query element represents the root entry point of the query.
    void
    setMaskMetadata(boolean maskMetadata)
    Configures the representation the query is evaluated on.
    void
    setPolymorphic(boolean polymorphic)
    Configures whether the entry-point match includes registered subtypes.
    void
    setPosition(int position)
    Sets the position level of this element.
    void
    setProjection(boolean projection)
    Sets whether this query element is part of a projection.
    protected void
    validateEmittedField(String key)
    Rejects the projection of a path inside an Encrypted property: an Encrypted property is projected as a whole, so that its value is returned encrypted for the caller as a read does.
    protected void
    validateLogicalCondition(LogicalOperator logicalOperator, org.gcube.com.fasterxml.jackson.databind.JsonNode condition, String fieldNamePrefix)
    Rejects, in a condition object of a logical operator, the keys that do not express a predicate: the structural keys of the query element (e.g.
    static void
    validateType(String type, org.gcube.informationsystem.base.reference.AccessType requiredAccessType)
    Validates whether the specified schema type belongs to the required access type category.
    protected StringBuffer
    wrapMatchQuery(StringBuffer buffer)
    Wraps and formats the completed MATCH query snippet with standard SELECT / EXPAND / RETURN blocks.

    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 query generation auditing.

    • OPERATOR_PREFIX

      public static final String OPERATOR_PREFIX
      The prefix of every query operator and directive key.
      See Also:

    • FALSE_CONDITION

      protected static final String FALSE_CONDITION
      The condition emitted for a predicate that never matches.
      See Also:

    • IS_NULL

      protected static final String IS_NULL
      The condition suffix emitted for a direct null value.
      See Also:

    • CREATED_BY_PATH

      protected static final String CREATED_BY_PATH
      The path of the identity of the creator, sensitive for the callers that read it redacted.
      See Also:

    • LAST_UPDATE_BY_PATH

      protected static final String LAST_UPDATE_BY_PATH
      The path of the identity of the last updater, sensitive for the callers that read it redacted.
      See Also:

    • FIELD_NAME_PATTERN

      protected static final Pattern FIELD_NAME_PATTERN
      The grammar of a field name: a dot-separated path of plain identifiers, each optionally followed by the index of an element.

    • ELEMENT_INDEX_PATTERN

      protected static final Pattern ELEMENT_INDEX_PATTERN
      The index of an element in a field name.

    • BACKEND_TYPE_NAME_FIELD

      protected static final String BACKEND_TYPE_NAME_FIELD
      The backend property holding the Type name of an element, which the representation names Element.TYPE_PROPERTY.
      See Also:

    • RECORD_ATTRIBUTE_PREFIX

      protected static final String RECORD_ATTRIBUTE_PREFIX
      The prefix of the backend record attributes, none of which is a field of the representation.
      See Also:

    • objectMapper

      protected final org.gcube.com.fasterxml.jackson.databind.ObjectMapper objectMapper
      In-use Jackson object mapper.

    • operandValidator

      protected final OperandValidator operandValidator
      The validator of the operator operands.

    • type

      protected final String type
      The schema type name of the query element.

    • jsonNode

      protected final org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode
      The JSON query subtree node representing this element.

    • accessType

      protected final org.gcube.informationsystem.base.reference.AccessType accessType
      The access type category of the query element.

    • fieldNamesToRemove

      protected final Set<String> fieldNamesToRemove
      The set of field names to ignore/remove during query translation.

    • unqueryableFields

      protected final Map<String,String> unqueryableFields
      The fields of the query element that a query can neither filter on nor project, each with the reason reported to the caller.

    • entryPoint

      protected boolean entryPoint
      Whether this query element represents the root entry point of the query.

    • polymorphic

      protected boolean polymorphic
      Whether the root match may include registered subtypes.

    • projection

      protected boolean projection
      Instruct the JSON query analyzer if it is a projection. It is set on the level carrying the projection and on the entry point.

    • position

      protected int position
      The breadcrumb.size() provide the level of nesting. The position which element number at the same level. E.g. the index of a ConsistsOf when the caller is a Resource. It is used in conjunction with breadcrumb.size() to attach a number to the alias. This allows to generate a predictive not clashing alias instead of using random string/number. This is useful for testing purposes.

    • alias

      protected String alias
      Contains the alias if needed by the class

    • fieldsToEmit

      protected List<String> fieldsToEmit
      This field is used by entry point only. Any class at any level can retrieve the entry point using getRootElement();

    • queryParameters

      protected Map<String,Object> queryParameters
      Caller-supplied scalar values bound to the generated OrientDB query.

    • queryParameterIndex

      protected int queryParameterIndex
      Monotonic parameter index owned by the entry-point element.

    • maskMetadata

      protected boolean maskMetadata
      Whether the caller reads the sensitive metadata identity fields redacted; owned by the entry-point element.

    • declaredPropertyResolver

      protected final DeclaredPropertyResolver declaredPropertyResolver
      The resolver of the declared property domains, owned by the entry-point element.

    • encryptedTypeParameters

      protected String encryptedTypeParameters
      The bound names of the Encrypted Type and of its subtypes, null until a predicate needs them; owned by the entry-point element.

    • size

      protected int size
      it indicates the number of properties in this.jsonNode This number is manipulated while analyzing the jsonNode to properly create the query.

  • Constructor Details

    • JsonQueryElement

      public JsonQueryElement(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonQuery, org.gcube.informationsystem.base.reference.AccessType accessType) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates a new JsonQueryElement instance for the specified JSON query subtree.
      Parameters:
      jsonQuery - the JSON query node representing this element
      accessType - the access type category
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if schema validation fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database or lookup error

  • Method Details

    • getRequiredType

      public static String getRequiredType(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonQuery) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException
      Returns the type declared by a level of the query that describes an instance.
      Parameters:
      jsonQuery - the JSON object of the level
      Returns:
      the declared type name
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the level is not a JSON object or does not declare a string type

    • validateType

      public static void validateType(String type, org.gcube.informationsystem.base.reference.AccessType requiredAccessType) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Validates whether the specified schema type belongs to the required access type category.
      Parameters:
      type - the schema type name to validate
      requiredAccessType - the expected access type category
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if the schema type is not registered
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • getType

      public String getType()
      Returns the schema type name of this element.
      Returns:
      the schema type name

    • isEntryPoint

      public boolean isEntryPoint()
      Returns whether this query element represents the root entry point of the query.
      Returns:
      true if this is the entry point, false otherwise

    • setEntryPoint

      public void setEntryPoint(boolean entryPoint)
      Sets whether this query element represents the root entry point of the query.
      Parameters:
      entryPoint - true if this is the entry point, false otherwise

    • setPolymorphic

      public void setPolymorphic(boolean polymorphic)
      Configures whether the entry-point match includes registered subtypes.
      Parameters:
      polymorphic - true for polymorphic matching; false for the exact Type

    • setMaskMetadata

      public void setMaskMetadata(boolean maskMetadata)
      Configures the representation the query is evaluated on. When set on the entry point, every predicate and projection of the query tree reads metadata.createdBy and metadata.lastUpdateBy as the constant Element.REDACTED, the value the caller is shown, instead of the stored identity.
      Parameters:
      maskMetadata - true if the caller reads the sensitive metadata identity fields redacted

    • isProjection

      public boolean isProjection()
      Returns whether this query element is part of a projection.
      Returns:
      true if this is a projection, false otherwise

    • setProjection

      public void setProjection(boolean projection)
      Sets whether this query element is part of a projection.
      Parameters:
      projection - true if this is a projection, false otherwise

    • getBreadcrumb

      public List<JsonQueryElement> getBreadcrumb()
      Returns the list of parent query elements visited.
      Returns:
      the list of parent query elements

    • setBreadcrumb

      public void setBreadcrumb(List<JsonQueryElement> breadcrumb)
      Sets the list of parent query elements visited.
      Parameters:
      breadcrumb - the list of parent query elements to set

    • getQueryParameters

      public Map<String,Object> getQueryParameters()
      Returns a snapshot of the parameters generated while translating this query tree.
      Returns:
      generated OrientDB named parameters

    • getPosition

      public int getPosition()
      Returns the position level of this element.
      Returns:
      the position level

    • setPosition

      public void setPosition(int position)
      Sets the position level of this element.
      Parameters:
      position - the position level to set

    • getAlias

      public String getAlias()
      Returns the alias associated with this element.
      Returns:
      the alias string

    • getAlias

      public String getAlias(boolean generateifNull)
      Returns the alias associated with this element, optionally generating it if not present.
      Parameters:
      generateifNull - true to generate alias if null
      Returns:
      the alias string

    • generateAlias

      protected StringBuffer generateAlias()
      Returns the unique alias buffer for this query element.
      Returns:
      the alias string buffer

    • addFieldToEmit

      protected void addFieldToEmit(String fieldToEmit)
      Adds a field to emit to the entry point, which generates the RETURN clause of the query.
      Parameters:
      fieldToEmit - the field name or alias to emit in projection

    • createQuery

      public StringBuffer createQuery(StringBuffer stringBuffer) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Translates this query element into a corresponding SQL query buffer (defaults to MATCH query).
      Parameters:
      stringBuffer - the buffer to append to
      Returns:
      the SQL query string buffer
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the schema type is not registered
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if query syntax or constraints are violated
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if schema traversal fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • addConstraints

      protected StringBuffer addConstraints(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, String fieldNamePrefix) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Builds the conjunction of the constraints expressed by the fields of a JSON object.

      An empty result means that the object adds no constraint, i.e. it always matches.

      Parameters:
      jsonNode - the JSON object holding the constraints
      fieldNamePrefix - the field name prefix, null at the level of the query element
      Returns:
      the formatted constraints string buffer
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the constraints are invalid or syntactically incorrect
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a Type definition cannot be read

    • addLogicalConstraints

      protected StringBuffer addLogicalConstraints(LogicalOperator logicalOperator, org.gcube.com.fasterxml.jackson.databind.JsonNode operand, String fieldNamePrefix) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Builds the condition of a logical operator.

      _and and _or join their condition objects, _not negates its single condition object. A condition object that adds no constraint always matches: it is skipped by _and, makes _or always match, and makes _not never match.

      Parameters:
      logicalOperator - the logical operator
      operand - the operand of the logical operator
      fieldNamePrefix - the field name prefix, null at the level of the query element
      Returns:
      the formatted condition string buffer; empty when the condition always matches
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the operand or one of its conditions is invalid
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a Type definition cannot be read

    • validateLogicalCondition

      protected void validateLogicalCondition(LogicalOperator logicalOperator, org.gcube.com.fasterxml.jackson.databind.JsonNode condition, String fieldNamePrefix) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException
      Rejects, in a condition object of a logical operator, the keys that do not express a predicate: the structural keys of the query element (e.g. type, consistsOf, source) and the projection directives.
      Parameters:
      logicalOperator - the logical operator owning the condition
      condition - the condition object
      fieldNamePrefix - the property the operator is placed in, null at the level of the query element
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the condition contains a key that is not a predicate

    • addComparisonConstraint

      protected StringBuffer addComparisonConstraint(ComparisonOperator comparisonOperator, org.gcube.com.fasterxml.jackson.databind.JsonNode operand, String fieldNamePrefix) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Builds the condition of a comparison, presence, collection or map operator applied to the property identified by the field name prefix.
      Parameters:
      comparisonOperator - the operator
      operand - the operand of the operator
      fieldNamePrefix - the property the operator applies to
      Returns:
      the formatted condition string buffer; empty when the condition always matches
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the operand is invalid, the operator is not applied to a property, or it does not apply to the declared domain of the property
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a Type definition cannot be read

    • excludeEncrypted

      protected StringBuffer excludeEncrypted(String key, PropertyDomain domain, StringBuffer condition) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Makes a predicate on a field the Type definition does not declare false wherever the field, or a field its path goes through, holds an Encrypted value. Which value an undeclared field holds is known only instance by instance, so the predicate cannot be rejected as the one on a declared Encrypted property is: it is kept from comparing the content of the Encrypted value instead.
      Parameters:
      key - the fully-qualified field key
      domain - the declared domain of the field, null if the Type definition does not declare it
      condition - the condition of the predicate
      Returns:
      the condition, false where the path meets an Encrypted value
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a Type definition cannot be read

    • resolveFieldName

      protected String resolveFieldName(String fieldName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException
      Validates a field name and returns the name written in the generated query. A field name is a dot-separated path of plain identifiers, each optionally followed by the index of an element, naming a field of the representation. The backend record attributes (every name with an @-prefixed segment) and the backend fields linking Entities and Relations are not fields of the representation.
      Parameters:
      fieldName - the field name as written in the query
      Returns:
      the field name to write in the generated query
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the field name is not valid

    • isSensitiveField

      protected boolean isSensitiveField(String key)
      Returns whether the caller reads the field as the constant Element.REDACTED: the metadata.createdBy and metadata.lastUpdateBy of the element of this level, when the query is evaluated for a caller who is shown them redacted.

      Only the element's own metadata is masked, i.e. the key that is exactly metadata.createdBy or metadata.lastUpdateBy from the element of the level (written dotted or as a nested metadata object, in a predicate, in _emit or as an operand): that is the only place where the representation holds the identity of who wrote an element, and the only one the read path redacts. A key with the same name deeper in a path (e.g. details.metadata.createdBy) lies inside an untyped custom object: it is data the user wrote, the read path returns it as it is, and so the query reads it as it is. No other path reaches the metadata of another element: every level of a query masks its own, and the backend link fields (in, out, in_*, out_*) that could traverse to another element cannot be named in a query (see resolveFieldName(String)).

      Parameters:
      key - the fully-qualified field key, from the element of this level
      Returns:
      true if the field must be read as the redacted constant

    • getFieldOperand

      protected String getFieldOperand(String key)
      Returns the left-hand operand of a predicate on a field: the field itself, or the bound constant Element.REDACTED when the caller reads the field redacted, so that the predicate never depends on the stored identity.
      Parameters:
      key - the fully-qualified field key
      Returns:
      the SQL operand

    • getPropertyDomain

      protected PropertyDomain getPropertyDomain(String key) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Returns the domain the Type definition of this element declares for a field. A path addressing one element of a collection by its index has no declared domain, unless it addresses an Encrypted value.
      Parameters:
      key - the fully-qualified field key
      Returns:
      the declared domain, or null if the Type definition does not declare the field
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a Type definition cannot be read

    • evaluateNode

      protected StringBuffer evaluateNode(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, String fieldName, String fieldNamePrefix) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Evaluates a single JSON property node and appends its filter condition to the query.
      Parameters:
      jsonNode - the JSON value node
      fieldName - the property field name
      fieldNamePrefix - the property field name prefix, null at the level of the query element
      Returns:
      the formatted filter condition string buffer; null or empty when the node adds no constraint
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the property value is invalid or unsupported
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a Type definition cannot be read

    • getKey

      protected String getKey(String fieldName, String fieldNamePrefix)
      Formats and returns a fully-qualified property field key path.
      Parameters:
      fieldName - the property field name
      fieldNamePrefix - the property field name prefix
      Returns:
      the fully-qualified field key string

    • getValue

      protected String getValue(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, PropertyDomain domain)
      Converts a JSON value to one or more OrientDB named-parameter placeholders.

      Array nodes (the right-hand operand of collection operators like _in, _containsAll, _containsAny) are formatted as an OrientDB collection expression (e.g. [:queryValue0, :queryValue1]), with every element bound via getScalarValue(JsonNode, PropertyDomain). Scalar nodes produce one placeholder.

      Parameters:
      jsonNode - the JSON value node
      domain - the declared domain of the compared property, null if it is not declared
      Returns:
      the generated named-parameter expression

    • getScalarValue

      protected String getScalarValue(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode)
      Binds a single scalar JSON node value as an OrientDB named parameter.
      Parameters:
      jsonNode - the JSON scalar value node
      Returns:
      the named parameter placeholder

    • getScalarValue

      protected String getScalarValue(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, PropertyDomain domain)
      Binds a single scalar JSON node value, compared with a property of the given declared domain, as an OrientDB named parameter. A value compared with a Date is bound as a Date, so that the comparison is chronological.
      Parameters:
      jsonNode - the JSON scalar value node
      domain - the declared domain of the compared property, null if it is not declared
      Returns:
      the named parameter placeholder

    • getFieldReference

      protected String getFieldReference(String key)
      Returns the SQL reference of a projected field: the field of this element, or the bound constant Element.REDACTED when the caller reads the field redacted.
      Parameters:
      key - the fully-qualified field key
      Returns:
      the SQL reference

    • validateEmittedField

      protected void validateEmittedField(String key) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Rejects the projection of a path inside an Encrypted property: an Encrypted property is projected as a whole, so that its value is returned encrypted for the caller as a read does.
      Parameters:
      key - the fully-qualified field key
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the key is a path inside an Encrypted property
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a Type definition cannot be read

    • getChildrenBreadcrumb

      protected List<JsonQueryElement> getChildrenBreadcrumb()
      Returns the list of query elements visited down to the current node.
      Returns:
      the list of visited query elements

    • wrapMatchQuery

      protected StringBuffer wrapMatchQuery(StringBuffer buffer) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Wraps and formats the completed MATCH query snippet with standard SELECT / EXPAND / RETURN blocks.
      Parameters:
      buffer - the accumulated MATCH query snippet
      Returns:
      the fully formatted SQL MATCH query string buffer
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the query parameters or projection is invalid
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if a Type definition cannot be read

    • getSpecificMatchQuery

      protected abstract StringBuffer getSpecificMatchQuery(List<JsonQueryElement> childrenBreadcrumb) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Generates the specific MATCH query snippet for this element's subclass (subclass hook).
      Parameters:
      childrenBreadcrumb - the list of child query elements visited
      Returns:
      the MATCH query snippet string buffer
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if schema validation fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error

    • createMatchQuery

      public StringBuffer createMatchQuery(StringBuffer stringBuffer) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Builds and appends the complete SQL MATCH query for this subtree.
      Parameters:
      stringBuffer - the buffer to append to
      Returns:
      the complete SQL MATCH query string buffer
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if schema traversal fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - on database error