Package org.gcube.informationsystem.resourceregistry.schema

Interface ResourceRegistrySchemaClient

All Known Implementing Classes:
ResourceRegistrySchemaClientImpl
public interface ResourceRegistrySchemaClient
Client interface for accessing Information System type schemas and model knowledge from the Resource Registry.

The interface is the authoritative caller-facing contract. Stable invocation options are represented by immutable request options, while HTTP metadata is available through the opt-in response executor without changing ordinary domain-oriented return values.

Author:
Luca Frosini (ISTI - CNR)

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addHeader(String name, boolean value)
    Deprecated.
    use per-request custom headers from ResourceRegistryRequestOptions
    void
    addHeader(String name, String value)
    Deprecated.
    use per-request custom headers from ResourceRegistryRequestOptions
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    org.gcube.informationsystem.types.reference.Type
    create(Class<ME> clz)
    Creates or idempotently confirms a type definition derived from a model element class.
    String
    create(String typeDefinition)
    Creates or idempotently confirms a type definition using its complete JSON representation.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    boolean
    delete(Class<ME> clz)
    Type-safe counterpart of delete(String) using the class-derived exact Type name.
    boolean
    delete(String typeName)
    Deletes an uninstantiated, childless, and unreferenced Type through DELETE /types/{type-name} and lazily invalidates initialized local knowledge.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    boolean
    exist(Class<ME> clz)
    Checks if a type definition exists in the Information System using a model element class.
    boolean
    exist(String typeName)
    Checks if a type definition exists in the Information System using the type name.
    boolean
    existTypeFromServer(String typeName)
    Checks if a type definition exists on the server through HEAD /types/{type-name}.
    org.gcube.informationsystem.model.knowledge.ModelKnowledge<org.gcube.informationsystem.types.reference.Type,org.gcube.informationsystem.types.knowledge.SchemaTypeInformation>
    getModelKnowledge()
    Retrieves the complete model knowledge containing type definitions and their information.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    org.gcube.informationsystem.dag.Node<org.gcube.informationsystem.types.reference.Type>
    getTypeDagNode(Class<ME> clz)
    Retrieves the type DAG node for a specific type identified by its model element class.
    org.gcube.informationsystem.dag.Node<org.gcube.informationsystem.types.reference.Type>
    getTypeDagNode(String typeName)
    Retrieves the type DAG node for a specific type identified by its name.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromServer(Class<ME> clz, int depth)
    Retrieves type definitions directly from the server using a model element class and depth.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromServer(Class<ME> clz, Boolean polymorphic)
    Deprecated.
    Use getTypeFromServer(Class, int) with depth instead.
    String
    getTypeFromServer(String typeName, int depth)
    Reads GET /types/{type-name} directly from the server with depth and metadataPolicy; invocation metadata policy overrides client configuration.
    String
    getTypeFromServer(String typeName, Boolean polymorphic)
    Deprecated.
    Use getTypeFromServer(String, int) with depth instead.
    boolean
    includeMeta()
    Returns whether metadata should be included in schema requests.
    String
    query(String jsonQuery)
    Executes a read-only JSON Query-By-Example payload against the global Types collection.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    List<org.gcube.informationsystem.types.reference.Type>
    read(Class<ME> clz, int level)
    Type-safe counterpart of read(String, int) using the class-derived type name.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    List<org.gcube.informationsystem.types.reference.Type>
    read(Class<ME> clz, Boolean polymorphic)
    Type-safe counterpart of read(String, Boolean) using the class-derived type name.
    String
    read(String typeName, int level)
    Reads a case-sensitive type from the local snapshot with breadth-first depth 0, a positive depth, or -1; values below -1 fall back to root-only depth 0.
    String
    read(String typeName, Boolean polymorphic)
    Reads a case-sensitive type from the local type snapshot; true includes every descendant, while false or null returns only the requested type.
    void
    renewModelKnowledge()
    Forces a renewal of the cached model knowledge by fetching the latest version from the Resource Registry.
    default org.gcube.informationsystem.resourceregistry.api.client.ResourceRegistryResponses
    serverResponses()
    Returns the opt-in response executor for associating operation values with immutable HTTP metadata captured from the same transport execution.
    void
    setIncludeMeta(boolean includeMeta)
    Sets whether metadata should be included in schema requests.

  • Method Details

    • serverResponses

      default org.gcube.informationsystem.resourceregistry.api.client.ResourceRegistryResponses serverResponses()
      Returns the opt-in response executor for associating operation values with immutable HTTP metadata captured from the same transport execution.
      Returns:
      stateless response executor

    • includeMeta

      boolean includeMeta()
      Returns whether metadata should be included in schema requests.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Returns:
      true if metadata should be included, false otherwise

    • setIncludeMeta

      void setIncludeMeta(boolean includeMeta)
      Sets whether metadata should be included in schema requests.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Parameters:
      includeMeta - true to include metadata, false to exclude it

    • getModelKnowledge

      org.gcube.informationsystem.model.knowledge.ModelKnowledge<org.gcube.informationsystem.types.reference.Type,org.gcube.informationsystem.types.knowledge.SchemaTypeInformation> getModelKnowledge()
      Retrieves the complete model knowledge containing type definitions and their information. The model knowledge provides access to all registered types and their hierarchical relationships.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Returns:
      the model knowledge containing type definitions and information

    • renewModelKnowledge

      void renewModelKnowledge()
      Forces a renewal of the cached model knowledge by fetching the latest version from the Resource Registry. This method should be called when the schema has been modified and the local cache needs to be updated.

      Invocation-specific options and immutable response metadata are available through serverResponses().

    • getTypeDagNode

      org.gcube.informationsystem.dag.Node<org.gcube.informationsystem.types.reference.Type> getTypeDagNode(String typeName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the type DAG node for a specific type identified by its name. The DAG node contains the type definition and its hierarchical position within the type system.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Parameters:
      typeName - the name of the type to retrieve
      Returns:
      the DAG node containing the type and its hierarchical information
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the specified type name does not exist in the schema
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the operation

    • getTypeDagNode

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> org.gcube.informationsystem.dag.Node<org.gcube.informationsystem.types.reference.Type> getTypeDagNode(Class<ME> clz) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the type DAG node for a specific type identified by its model element class. The DAG node contains the type definition and its hierarchical position within the type system.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clz - the class of the model element type to retrieve
      Returns:
      the DAG node containing the type and its hierarchical information
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the specified type does not exist in the schema
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the operation

    • addHeader

      @Deprecated void addHeader(String name, String value)
      Deprecated.
      use per-request custom headers from ResourceRegistryRequestOptions
      Adds a custom HTTP header to be included in requests.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Parameters:
      name - Header name
      value - Header value

    • addHeader

      @Deprecated void addHeader(String name, boolean value)
      Deprecated.
      use per-request custom headers from ResourceRegistryRequestOptions
      Adds a custom HTTP header to be included in requests.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Parameters:
      name - Header name
      value - boolean value

    • create

      String create(String typeDefinition) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates or idempotently confirms a type definition using its complete JSON representation.

      The operation is global and requires an IS-M or Infra-M role. It accepts no query parameters. A structurally identical retry is an idempotent no-op; a different definition with the same name is rejected. The returned JSON is always the persisted representation, whether newly created or already present.

      HTTP status (201 for creation or 200 for an identical retry), Content-Location, and any warnings are available through serverResponses().

      Parameters:
      typeDefinition - the non-null, complete JSON schema definition to create
      Returns:
      the persisted JSON representation; never null
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if the definition is malformed, violates schema constraints, uses a conflicting name or UUID, or is structurally different from an existing definition
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if authorization, transport, response processing, or another registry operation fails

    • create

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> org.gcube.informationsystem.types.reference.Type create(Class<ME> clz) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates or idempotently confirms a type definition derived from a model element class.

      This overload serializes the supplied class and delegates to create(String) with exactly the same authorization, idempotency, response-metadata, and failure semantics.

      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clz - the non-null model element class to create
      Returns:
      the persisted Type definition; never null
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if the class definition is invalid or schema generation fails
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if serialization, authorization, transport, response processing, or another registry operation fails

    • exist

      boolean exist(String typeName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a type definition exists in the Information System using the type name.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Parameters:
      typeName - the name of the type to check for existence (case-sensitive)
      Returns:
      true if the type exists in the system, false if not found
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the existence check

    • exist

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> boolean exist(Class<ME> clz) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a type definition exists in the Information System using a model element class.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clz - the class of the model element type to check for existence
      Returns:
      true if the type corresponding to the class exists in the system, false if not found
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the existence check

    • read

      String read(String typeName, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads a case-sensitive type from the local type snapshot; true includes every descendant, while false or null returns only the requested type.

      Each type occurs once in breadth-first order. A fully cached call reports the CACHE origin through serverResponses() and has no HTTP response metadata.

      Parameters:
      typeName - the exact type name
      polymorphic - whether to include all descendants; null means false
      Returns:
      a non-null JSON array containing the selected cached type definitions
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the requested type is absent from the snapshot
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if cache initialization, serialization, or retrieval fails

    • read

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> List<org.gcube.informationsystem.types.reference.Type> read(Class<ME> clz, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Type-safe counterpart of read(String, Boolean) using the class-derived type name.
      Type Parameters:
      ME - the model element type
      Parameters:
      clz - the class whose exact type name is read
      polymorphic - whether to include all descendants; null means false
      Returns:
      a non-null breadth-first list with each cached type exactly once
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the class-derived type is absent from the snapshot
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if cache initialization or retrieval fails

    • read

      String read(String typeName, int level) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads a case-sensitive type from the local snapshot with breadth-first depth 0, a positive depth, or -1; values below -1 fall back to root-only depth 0.
      Parameters:
      typeName - the exact type name
      level - 0 for the root, a positive descendant depth, or -1 for all descendants
      Returns:
      a non-null JSON array with each selected cached type exactly once
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the requested type is absent from the snapshot
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if cache initialization, serialization, or retrieval fails

    • read

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> List<org.gcube.informationsystem.types.reference.Type> read(Class<ME> clz, int level) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Type-safe counterpart of read(String, int) using the class-derived type name.
      Type Parameters:
      ME - the model element type
      Parameters:
      clz - the class whose exact type name is read
      level - 0 for the root, a positive descendant depth, or -1 for all descendants
      Returns:
      a non-null breadth-first list with each cached type exactly once
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the class-derived type is absent from the snapshot
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if cache initialization or retrieval fails

    • existTypeFromServer

      boolean existTypeFromServer(String typeName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a type definition exists on the server through HEAD /types/{type-name}.

      Invocation-specific options and immutable response metadata are available through serverResponses().

      Parameters:
      typeName - the exact, case-sensitive type name
      Returns:
      true if the type exists on the server, false otherwise
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for server communication errors

    • getTypeFromServer

      @Deprecated String getTypeFromServer(String typeName, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Deprecated.
      Use getTypeFromServer(String, int) with depth instead.
      Reads GET /types/{type-name} directly from the server; true maps to depth -1, while false or null maps to depth 0.
      Parameters:
      typeName - the exact, case-sensitive type name
      polymorphic - whether to request every descendant; null means false
      Returns:
      the non-null JSON response array
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the server returns not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if authorization, transport, or response processing fails

    • getTypeFromServer

      String getTypeFromServer(String typeName, int depth) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads GET /types/{type-name} directly from the server with depth and metadataPolicy; invocation metadata policy overrides client configuration. A successful response exposes Content-Location, direct-supertype links, and warnings through serverResponses(); an unknown exact name maps to 404.
      Parameters:
      typeName - the exact, case-sensitive type name
      depth - 0, a positive descendant depth, or -1
      Returns:
      the non-null JSON response array
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the server returns not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if authorization, transport, or response processing fails

    • getTypeFromServer

      @Deprecated <ME extends org.gcube.informationsystem.model.reference.ModelElement> List<org.gcube.informationsystem.types.reference.Type> getTypeFromServer(Class<ME> clz, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Deprecated.
      Use getTypeFromServer(Class, int) with depth instead.
      Retrieves type definitions directly from the server using a model element class.
      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clz - the class of the model element type to retrieve
      polymorphic - whether to include subtypes
      Returns:
      list of Type objects retrieved from the server
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type is not found on the server
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for server communication errors

    • getTypeFromServer

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> List<org.gcube.informationsystem.types.reference.Type> getTypeFromServer(Class<ME> clz, int depth) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves type definitions directly from the server using a model element class and depth.
      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clz - the class of the model element type to retrieve
      depth - the depth of subclass expansion
      Returns:
      list of Type objects retrieved from the server
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type is not found on the server
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for server communication errors

    • delete

      boolean delete(String typeName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Deletes an uninstantiated, childless, and unreferenced Type through DELETE /types/{type-name} and lazily invalidates initialized local knowledge.

      No query parameter or Prefer option is sent. A successful bodyless 204 returns true; response status and warnings are available through serverResponses() without being replaced by cache-refresh requests.

      Parameters:
      typeName - the exact, case-sensitive Type name; UUID addressing is unsupported
      Returns:
      true after a successful 204 No Content
      Throws:
      jakarta.ws.rs.ForbiddenException - if the caller is not an IS-M or Infra-M
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the exact Type name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - if concrete instances, subtypes, or Type references remain
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if transport or response processing fails

    • delete

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> boolean delete(Class<ME> clz) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Type-safe counterpart of delete(String) using the class-derived exact Type name.
      Type Parameters:
      ME - the model element type
      Parameters:
      clz - the class whose Type definition is deleted
      Returns:
      true after a successful 204 No Content
      Throws:
      jakarta.ws.rs.ForbiddenException - if the caller is not an IS-M or Infra-M
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the class-derived Type name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - if concrete instances, subtypes, or Type references remain
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if transport or response processing fails

    • query

      String query(String jsonQuery) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a read-only JSON Query-By-Example payload against the global Types collection. The payload must be a non-null JSON object targeting ResourceSchema, FacetSchema, IsRelatedToSchema, ConsistsOfSchema, or PropertySchema. Every authenticated role may invoke the operation and no Context-scoped token is required.

      ResourceRegistryRequestOptions may set limit (default 10, maximum 50), offset (default 0), depth (default -1), and metadataPolicy (default none) for one invocation. Plain name, source, and target filters use depth. An _emit payload returns flat, native-typed aliases and supersedes metadata inclusion. Per-request options take precedence over the metadata default configured through setIncludeMeta(boolean).

      The method has no local cache or mutation side effects. It returns [] when no definition matches. Pagination links and parameter/projection warnings are available through serverResponses().

      Parameters:
      jsonQuery - non-null JSON object describing the Type definitions to search for
      Returns:
      JSON array string containing full Type definitions or flat projection rows; never null
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - if the payload is malformed, structurally invalid, or targets an unsupported Type category
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if request construction, transport, response processing, or server-side persistence fails