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 List<JsonQueryElement>
    breadcrumb
    The chain of callers of this instance analyzer.
    protected boolean
    entryPoint
    Whether this query element represents the root entry point of the query.
    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 final org.gcube.com.fasterxml.jackson.databind.JsonNode
    jsonNode
    The JSON query subtree node representing this element.
    protected org.slf4j.Logger
    logger
    The logger instance for query generation auditing.
    protected final org.gcube.com.fasterxml.jackson.databind.ObjectMapper
    objectMapper
    In-use Jackson object mapper.
    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 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.

  • 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
    addConstraints(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode, LogicalOperator queryLogicalOperator, String fieldNamePrefix)
    Builds and appends constraints from a JSON node using a logical operator.
    protected void
    addFieldToEmit(String fieldToEmit)
    Add a field to emit only if this instance is the entry point.
    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
    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
    getKey(String fieldName, String fieldNamePrefix)
    Formats and returns a fully-qualified property field key path.
    int
    getPosition()
    Returns the position level of this element.
    Map<String,Object>
    getQueryParameters()
    Returns a snapshot of the parameters generated while translating this query tree.
    protected String
    getScalarValue(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode)
    Binds a single scalar JSON node value 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)
    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.
    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
    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.
    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.

    • objectMapper

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

    • 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.

    • 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

    • 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 breadcrumb.get(0);

    • 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.

    • 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

    • 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

    • 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)
      Add a field to emit only if this instance is the entry point.
      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, LogicalOperator queryLogicalOperator, String fieldNamePrefix) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException
      Builds and appends constraints from a JSON node using a logical operator.
      Parameters:
      jsonNode - the constraints JSON node
      queryLogicalOperator - the logical operator to connect constraints
      fieldNamePrefix - the field name prefix
      Returns:
      the formatted constraints string buffer
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the constraints are invalid or syntactically incorrect

    • 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
      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
      Returns:
      the formatted filter condition string buffer
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the property value is invalid or unsupported

    • 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)
      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). Scalar nodes produce one placeholder.

      Parameters:
      jsonNode - the JSON value node
      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

    • 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
      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

    • 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