Package org.gcube.informationsystem.resourceregistry.schema

Class ResourceRegistrySchemaClientImpl

java.lang.Object
org.gcube.informationsystem.resourceregistry.schema.ResourceRegistrySchemaClientImpl
All Implemented Interfaces:
ResourceRegistrySchemaClient
public class ResourceRegistrySchemaClientImpl extends Object implements ResourceRegistrySchemaClient
Author:
Luca Frosini (ISTI - CNR)

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final String
    address
    The base address URL for the Resource Registry Schema service endpoint.
    protected Map<String,String>
    headers
    HTTP headers to be included in requests to the Resource Registry Schema service.
    protected boolean
    includeMeta
    Track if the client must request to include Metadata
    protected org.gcube.informationsystem.types.knowledge.TypesKnowledge
    typesKnowledge
    Cached knowledge about types and their relationships within the Information System.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ResourceRegistrySchemaClientImpl(String address)
    Creates a new ResourceRegistrySchemaClient instance with shared model knowledge.
    ResourceRegistrySchemaClientImpl(String address, boolean sharedModelKnowledge)
    Creates a new ResourceRegistrySchemaClient instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected List<org.gcube.informationsystem.types.reference.Type>
    addChildren(org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type> node, List<org.gcube.informationsystem.types.reference.Type> types, int currentLevel, int maxLevel)
    Recursively adds child types to the result list up to the specified maximum level.
    void
    addHeader(String name, boolean value)
    Adds a custom HTTP header to be included in requests.
    void
    addHeader(String name, String value)
    Adds a custom HTTP header to be included in requests.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    org.gcube.informationsystem.types.reference.Type
    create(Class<ME> clz)
    Creates a new type definition in the Information System using a model element class.
    String
    create(String typeDefinitition)
    Creates a new type definition in the Information System using JSON schema definition.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    boolean
    exist(Class<ME> clazz)
    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 exists directly on the server using a HEAD request.
    protected org.gcube.common.gxhttp.request.GXHTTPStringRequest
    getGXHTTPStringRequest()
    Creates and configures a GXHTTPStringRequest with authentication headers and custom headers.
    org.gcube.informationsystem.model.knowledge.ModelKnowledge<org.gcube.informationsystem.types.reference.Type,org.gcube.informationsystem.types.knowledge.TypeInformation>
    getModelKnowledge()
    Retrieves the complete model knowledge containing type definitions and their information.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromServer(Class<ME> clz, Boolean polymorphic)
    Retrieves type definitions directly from the server using a model element class.
    String
    getTypeFromServer(String typeName, Boolean polymorphic)
    Retrieves type definitions directly from the server by type name.
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromTypesKnowledge(String typeName, int level)
    Retrieves type information from the local TypesKnowledge cache with level-based filtering.
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromTypesKnowledge(String typeName, Boolean polymorphic)
    Retrieves type information from the local TypesKnowledge cache.
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromTypesKnowledge(String typeName, Boolean polymorphic, int level)
    Retrieves type information from the local TypesKnowledge cache with full filtering options.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type>
    getTypeTreeNode(Class<ME> clazz)
    Retrieves the type tree node for a specific type identified by its model element class.
    org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type>
    getTypeTreeNode(String typeName)
    Retrieves the type tree node for a specific type identified by its name.
    boolean
    includeMeta()
    Returns whether metadata should be included in schema requests.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    List<org.gcube.informationsystem.types.reference.Type>
    read(Class<ME> clazz, int level)
    Reads the type definitions for a specified model element class up to a specific hierarchy level.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    List<org.gcube.informationsystem.types.reference.Type>
    read(Class<ME> clazz, Boolean polymorphic)
    Reads the type definitions for a specified model element class.
    String
    read(String typeName, int level)
    Reads the schema definition for a specified type by name up to a specific hierarchy level.
    String
    read(String typeName, Boolean polymorphic)
    Reads the schema definition for a specified type by name.
    void
    renewModelKnowledge()
    Forces a renewal of the cached model knowledge by fetching the latest version from the Resource Registry.
    void
    setIncludeMeta(boolean includeMeta)
    Sets whether metadata should be included in schema requests.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • address

      protected final String address
      The base address URL for the Resource Registry Schema service endpoint.

    • headers

      protected Map<String,String> headers
      HTTP headers to be included in requests to the Resource Registry Schema service.

    • typesKnowledge

      protected org.gcube.informationsystem.types.knowledge.TypesKnowledge typesKnowledge
      Cached knowledge about types and their relationships within the Information System.

    • includeMeta

      protected boolean includeMeta
      Track if the client must request to include Metadata

  • Constructor Details

    • ResourceRegistrySchemaClientImpl

      public ResourceRegistrySchemaClientImpl(String address)
      Creates a new ResourceRegistrySchemaClient instance with shared model knowledge. This constructor delegates to ResourceRegistrySchemaClientImpl(String, boolean) with sharedModelKnowledge=true.
      Parameters:
      address - the base address of the Resource Registry service

    • ResourceRegistrySchemaClientImpl

      public ResourceRegistrySchemaClientImpl(String address, boolean sharedModelKnowledge)
      Creates a new ResourceRegistrySchemaClient instance.
      Parameters:
      address - the base address of the Resource Registry service
      sharedModelKnowledge - whether to use shared TypesKnowledge instance (true) or create a new one (false)

  • Method Details

    • includeMeta

      public boolean includeMeta()
      Returns whether metadata should be included in schema requests.
      Specified by:
      includeMeta in interface ResourceRegistrySchemaClient
      Returns:
      true if metadata should be included, false otherwise

    • setIncludeMeta

      public void setIncludeMeta(boolean includeMeta)
      Sets whether metadata should be included in schema requests.
      Specified by:
      setIncludeMeta in interface ResourceRegistrySchemaClient
      Parameters:
      includeMeta - true to include metadata, false to exclude it

    • addHeader

      public void addHeader(String name, String value)
      Adds a custom HTTP header to be included in requests.
      Specified by:
      addHeader in interface ResourceRegistrySchemaClient
      Parameters:
      name - Header name
      value - Header value

    • addHeader

      public void addHeader(String name, boolean value)
      Adds a custom HTTP header to be included in requests.
      Specified by:
      addHeader in interface ResourceRegistrySchemaClient
      Parameters:
      name - Header name
      value - boolean value

    • getGXHTTPStringRequest

      protected org.gcube.common.gxhttp.request.GXHTTPStringRequest getGXHTTPStringRequest()
      Creates and configures a GXHTTPStringRequest with authentication headers and custom headers. This method sets up the basic HTTP request infrastructure needed for all REST API calls.
      Returns:
      a configured GXHTTPStringRequest ready for API calls

    • getModelKnowledge

      public org.gcube.informationsystem.model.knowledge.ModelKnowledge<org.gcube.informationsystem.types.reference.Type,org.gcube.informationsystem.types.knowledge.TypeInformation> 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.
      Specified by:
      getModelKnowledge in interface ResourceRegistrySchemaClient
      Returns:
      the model knowledge containing type definitions and information

    • renewModelKnowledge

      public 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.
      Specified by:
      renewModelKnowledge in interface ResourceRegistrySchemaClient

    • create

      public <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 a new type definition in the Information System using a model element class. Corresponding REST API: PUT /types/{type-name} Operation Behavior:
      • Creates a new type definition derived from the provided model element class
      • Type name is automatically derived from the class using reflection
      • Analyzes class annotations and structure to generate the type schema
      • Type definitions become available system-wide for instance creation
      • Returns the complete Type object with metadata and schema information.
      HTTP Response Codes:
      • 201 Created: Type successfully created
      • 409 Conflict: Type already exists with the given name
      • 400 Bad Request: Invalid class definition or schema generation failure
      • 403 Forbidden: User lacks authorization to create types.
      Input Processing:
      • Type name is automatically derived from the provided class using TypeUtility.getTypeName(Class)
      • Class must extend ModelElement or its subtypes
      • Annotations are processed to generate schema constraints
      • Property definitions are extracted from class fields and methods.
      Schema Validation:
      • All class properties and relationships are validated against the Information System model
      • Type hierarchy and inheritance rules are enforced
      • Property types and constraints are validated from class annotations
      • Relationship definitions must reference valid types.
      Authorization Requirements:
      • IS-Manager: Can create any type definition without restrictions
      • Infrastructure-Manager: Can create any type definition without restrictions
      • All Other Users: Cannot create type definitions (will receive authorization errors)
      • Type creation is restricted to prevent system-wide compatibility issues.
      Example Usage: 
       ResourceRegistrySchemaClient client = ResourceRegistrySchemaClientFactory.create();
 
 // Create a new type from model element class
 Type createdType = client.create(ContactFacet.class);
      This method is a type-safe wrapper that delegates to create(String) for implementation details.
      Specified by:
      create in interface ResourceRegistrySchemaClient
      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clz - the class of the model element type to create
      Returns:
      the Type object representing the created type definition
      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 - for creation errors or authorization failures Context Access:
      • Type definitions are global and not bound to a specific context.

    • create

      public String create(String typeDefinitition) throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextAlreadyPresentException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Creates a new type definition in the Information System using JSON schema definition. Corresponding REST API: PUT /types/{type-name} Operation Behavior:
      • Creates a new type definition from JSON schema representation
      • Type name is extracted from the JSON schema definition
      • Validates the JSON schema against Information System type schema requirements
      • Type definitions become available system-wide for instance creation
      • Returns the complete type definition including metadata and schema information.
      HTTP Response Codes:
      • 201 Created: Type successfully created
      • 409 Conflict: Type already exists with the given name
      • 400 Bad Request: Invalid JSON schema or malformed request
      • 403 Forbidden: User lacks authorization to create types.
      Input Processing:
      • JSON schema must conform to Information System type schema format
      • Type name must be unique in the system
      • Schema must define valid properties, relationships, and constraints.
      Schema Validation:
      • All type properties and relationships are validated against the Information System model
      • Type hierarchy and inheritance rules are enforced
      • Property types and constraints are validated
      • Relationship definitions must reference valid types.
      Authorization Requirements:
      • IS-Manager: Can create any type definition without restrictions
      • Infrastructure-Manager: Can create any type definition without restrictions
      • All Other Users: Cannot create type definitions (will receive authorization errors)
      • Type creation is restricted to prevent system-wide compatibility issues.
      Example Usage: 
       ResourceRegistrySchemaClient client = ResourceRegistrySchemaClientFactory.create();

 // Create a new type from JSON schema
 String jsonSchema = "{ \"@class\": \"ContactFacet\", ... }";
 String createdType = client.create(jsonSchema);
      Context Access:
      • Type definitions are global and not bound to a specific context.
      Specified by:
      create in interface ResourceRegistrySchemaClient
      Parameters:
      typeDefinitition - the JSON schema definition of the type to create
      Returns:
      the JSON representation of the created type definition
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaException - if the provided schema is invalid or malformed
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for creation errors or authorization failures
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextAlreadyPresentException

    • exist

      public <ME extends org.gcube.informationsystem.model.reference.ModelElement> boolean exist(Class<ME> clazz) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a type definition exists in the Information System using a model element class. Corresponding REST API: HEAD /types/{type-name}[?polymorphic={true|false}&includeMeta={true|false}] Operation Behavior:
      • Verifies the existence of the specified type definition using its model element class
      • Type name is automatically derived from the class using reflection
      • Does not return the type data, only confirms existence
      • Checks accessibility within the current user authorization level
      • Convenient method when working with strongly-typed classes.
      HTTP Response Codes:
      • 200 OK: Type exists and is accessible
      • 404 Not Found: Type corresponding to the class does not exist in the system
      • 403 Forbidden: User lacks authorization to access type information
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • The type name is automatically derived from the provided class using TypeUtility.getTypeName(Class)
      • Class must extend ModelElement or its subtypes
      • Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes).
      Authorization Requirements:
      • IS-Manager: Can check existence of any type definition
      • Infrastructure-Manager: Can check existence of any type definition
      • All Other Users: Can check existence of any type definition with filtered access to sensitive metadata.
      Example Usage: 
       ResourceRegistrySchemaClient client = ResourceRegistrySchemaClientFactory.create();
 
 // Check if ContactFacet type exists
 boolean contactFacetExists = client.exist(ContactFacet.class);
 
 // Check if EService type exists
 boolean eServiceExists = client.exist(EService.class);
      This method is a type-safe wrapper that delegates to exist(String) for implementation details.
      Specified by:
      exist in interface ResourceRegistrySchemaClient
      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clazz - 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

    • exist

      public 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. Corresponding REST API: HEAD /types/{type-name}[?polymorphic={true|false}&includeMeta={true|false}] Operation Behavior:
      • Verifies the existence of the specified type definition using its name
      • Does not return the type data, only confirms existence
      • Checks accessibility within the current user authorization level
      • Most direct method when type name is already known.
      HTTP Response Codes:
      • 200 OK: Type exists and is accessible
      • 404 Not Found: Type does not exist in the system
      • 403 Forbidden: User lacks authorization to access type information
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • Type name must be a valid Information System model type
      • Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
      • Type name is case-sensitive and must match exactly.
      Authorization Requirements:
      • IS-Manager: Can check existence of any type definition
      • Infrastructure-Manager: Can check existence of any type definition
      • All Other Users: Can check existence of any type definition with filtered access to sensitive metadata.
      Example Usage: 
       ResourceRegistrySchemaClient client = ResourceRegistrySchemaClientFactory.create();
 
 // Check if ContactFacet type exists
 boolean contactFacetExists = client.exist("ContactFacet");
 
 // Check if a custom resource type exists
 boolean customResourceExists = client.exist("MyCustomResource");
      Specified by:
      exist in interface ResourceRegistrySchemaClient
      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

    • getTypeFromTypesKnowledge

      public List<org.gcube.informationsystem.types.reference.Type> getTypeFromTypesKnowledge(String typeName, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves type information from the local TypesKnowledge cache. This method supports both polymorphic and level-based filtering.
      Parameters:
      typeName - the name of the type to retrieve
      polymorphic - whether to include subtypes
      Returns:
      list of Type objects matching the criteria
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for other retrieval errors

    • getTypeFromTypesKnowledge

      public List<org.gcube.informationsystem.types.reference.Type> getTypeFromTypesKnowledge(String typeName, int level) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves type information from the local TypesKnowledge cache with level-based filtering. This method delegates to getTypeFromTypesKnowledge(String, Boolean, int) with polymorphic=true.
      Parameters:
      typeName - the name of the type to retrieve
      level - the maximum hierarchy level to include
      Returns:
      list of Type objects matching the criteria
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for other retrieval errors

    • addChildren

      protected List<org.gcube.informationsystem.types.reference.Type> addChildren(org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type> node, List<org.gcube.informationsystem.types.reference.Type> types, int currentLevel, int maxLevel)
      Recursively adds child types to the result list up to the specified maximum level. This method is used internally to build polymorphic type hierarchies.
      Parameters:
      node - the current node in the type hierarchy
      types - the accumulator list for type results
      currentLevel - the current recursion level
      maxLevel - the maximum level to recurse to (-1 for unlimited)
      Returns:
      the updated list of types including children

    • getTypeFromTypesKnowledge

      public List<org.gcube.informationsystem.types.reference.Type> getTypeFromTypesKnowledge(String typeName, Boolean polymorphic, int level) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves type information from the local TypesKnowledge cache with full filtering options. This is the main implementation method that supports both polymorphic and level-based filtering.
      Parameters:
      typeName - the name of the type to retrieve
      polymorphic - whether to include subtypes
      level - the maximum hierarchy level to include (-1 for unlimited)
      Returns:
      list of Type objects matching the criteria
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for other retrieval errors

    • read

      public String read(String typeName, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads the schema definition for a specified type by name. Corresponding REST API: GET /types/{type-name}[?polymorphic={true|false}&includeMeta={true|false}] Operation Behavior:
      • Retrieves type schema definition(s) for the specified type name
      • When polymorphic=false: returns only the specified type definition
      • When polymorphic=true: returns the specified type AND all its existing subtypes
      • Metadata inclusion is controlled by client configuration and user authorization
      • Response detail level varies based on user authorization (IS/Infrastructure managers get full metadata).
      HTTP Response Codes:
      • 200 OK: Type successfully retrieved
      • 404 Not Found: Type with the specified name does not exist
      • 403 Forbidden: User lacks authorization to access type information.
      Query Parameters: polymorphic (parameter of this method):
      • Whether to include subtypes in the response
      • Default value: false (returns only the specified type)
      • Values: true (includes all subtypes) | false (specified type only)
      • When true: returns the specified type AND all its existing subtypes
      • When false: returns only the specified type definition
      • Note: No pagination is applied - ALL subtypes are returned when polymorphic=true.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response type definition
      • Default value: false (basic type information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: TypePath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      Authorization Requirements:
      • IS-Manager: Receive complete type definitions with full metadata when requested
      • Infrastructure-Manager: Receive complete type definitions with full metadata when requested
      • All Other Users: Receive basic type information with filtered metadata (sensitive information obfuscated).
      Example Usage: 
       ResourceRegistrySchemaClient client = ResourceRegistrySchemaClientFactory.create();
 
 // Read a ContactFacet type definition only
 String contactFacetSchema = client.read("ContactFacet", false);
 
 // Read ContactFacet and all its subtypes
 String contactFacetAndSubtypes = client.read("ContactFacet", true);
      Specified by:
      read in interface ResourceRegistrySchemaClient
      Parameters:
      typeName - the name of the type to retrieve (case-sensitive)
      polymorphic - whether to include subtypes in the response (when true, includes all subtypes)
      Returns:
      JSON string containing type schema definition(s) with authorization-appropriate detail level
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the specified type is not found in the system
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for retrieval errors or other system failures

    • read

      public <ME extends org.gcube.informationsystem.model.reference.ModelElement> List<org.gcube.informationsystem.types.reference.Type> read(Class<ME> clazz, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads the type definitions for a specified model element class. Corresponding REST API: GET /types/{type-name}[?polymorphic={true|false}&includeMeta={true|false}] Operation Behavior:
      • Retrieves type definitions for the specified model element class
      • Type name is automatically derived from the class using reflection
      • When polymorphic=false: returns only the specified type definition
      • When polymorphic=true: returns the specified type AND all its existing subtypes
      • Returns strongly-typed Type objects instead of JSON strings
      • Response detail level varies based on user authorization.
      HTTP Response Codes:
      • 200 OK: Type successfully retrieved
      • 404 Not Found: Type corresponding to the specified class does not exist
      • 403 Forbidden: User lacks authorization to access type information.
      Query Parameters: polymorphic (parameter of this method):
      • Whether to include subtypes in the response
      • Default value: false (returns only the specified type)
      • Values: true (includes all subtypes) | false (specified type only)
      • When true: returns the specified type AND all its existing subtypes
      • When false: returns only the specified type definition
      • Note: No pagination is applied - ALL subtypes are returned when polymorphic=true.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response type definition
      • Default value: false (basic type information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: TypePath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      Input Processing:
      • The type name is automatically derived from the provided class using TypeUtility.getTypeName(Class).
      Authorization Requirements:
      • IS-Manager: Receive complete type definitions with full metadata when requested
      • Infrastructure-Manager: Receive complete type definitions with full metadata when requested
      • All Other Users: Receive basic type information with filtered metadata (sensitive information obfuscated).
      Example Usage: 
       ResourceRegistrySchemaClient client = ResourceRegistrySchemaClientFactory.create();
 
 // Read ContactFacet type definition only
 List<Type> contactFacetType = client.read(ContactFacet.class, false);
 
 // Read ContactFacet and all its subtypes
 List<Type> contactFacetAndSubtypes = client.read(ContactFacet.class, true);
      This method is a type-safe wrapper that delegates to getTypeFromTypesKnowledge(String, Boolean) for implementation details.
      Specified by:
      read in interface ResourceRegistrySchemaClient
      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clazz - the class of the model element type to retrieve
      polymorphic - whether to include subtypes in the response (when true, includes all subtypes)
      Returns:
      list of Type objects representing the type definition(s) with authorization-appropriate detail level
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type corresponding to the specified class is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for retrieval errors or other system failures

    • read

      public String read(String typeName, int level) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads the schema definition for a specified type by name up to a specific hierarchy level. Corresponding REST API: GET /types/{type-name}[?polymorphic={true|false}&includeMeta={true|false}] Operation Behavior:
      • Retrieves type schema definition for the specified type name
      • Limits the depth of hierarchical relationships to the specified level
      • Level parameter controls how deep into related types the response includes
      • Useful for preventing overly complex responses in deeply nested type hierarchies
      • Response detail level varies based on user authorization.
      HTTP Response Codes:
      • 200 OK: Type successfully retrieved
      • 404 Not Found: Type with the specified name does not exist
      • 403 Forbidden: User lacks authorization to access type information.
      Query Parameters: level (parameter of this method):
      • Controls the depth of hierarchical relationships included in the response
      • Higher values include more detailed relationship information
      • Lower values provide more concise responses with limited relationship depth
      • Useful for controlling response size and complexity.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response type definition
      • Default value: false (basic type information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: TypePath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      Authorization Requirements:
      • IS-Manager: Receive complete type definitions with full metadata when requested
      • Infrastructure-Manager: Receive complete type definitions with full metadata when requested
      • All Other Users: Receive basic type information with filtered metadata (sensitive information obfuscated).
      Example Usage: 
       ResourceRegistrySchemaClient client = ResourceRegistrySchemaClientFactory.create();
 
 // Read ContactFacet type definition with hierarchy level 1
 String contactFacetSchema = client.read("ContactFacet", 1);
 
 // Read ContactFacet type definition with deeper hierarchy level
 String contactFacetDeepSchema = client.read("ContactFacet", 3);
      Specified by:
      read in interface ResourceRegistrySchemaClient
      Parameters:
      typeName - the name of the type to retrieve (case-sensitive)
      level - the maximum hierarchy level to include in the response
      Returns:
      JSON string containing type schema definition with hierarchy limited to the specified level
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the specified type is not found in the system
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for retrieval errors or other system failures

    • read

      public <ME extends org.gcube.informationsystem.model.reference.ModelElement> List<org.gcube.informationsystem.types.reference.Type> read(Class<ME> clazz, int level) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads the type definitions for a specified model element class up to a specific hierarchy level. Corresponding REST API: GET /types/{type-name}[?polymorphic={true|false}&includeMeta={true|false}] Operation Behavior:
      • Retrieves type definitions for the specified model element class
      • Type name is automatically derived from the class using reflection
      • Limits the depth of hierarchical relationships to the specified level
      • Level parameter controls how deep into related types the response includes
      • Returns strongly-typed Type objects instead of JSON strings
      • Response detail level varies based on user authorization.
      HTTP Response Codes:
      • 200 OK: Type successfully retrieved
      • 404 Not Found: Type corresponding to the specified class does not exist
      • 403 Forbidden: User lacks authorization to access type information.
      Query Parameters: level (parameter of this method):
      • Controls the depth of hierarchical relationships included in the response
      • Higher values include more detailed relationship information
      • Lower values provide more concise responses with limited relationship depth
      • Useful for controlling response size and complexity.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response type definition
      • Default value: false (basic type information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: TypePath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager and Infrastructure-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      Input Processing:
      • The type name is automatically derived from the provided class using TypeUtility.getTypeName(Class).
      Authorization Requirements:
      • IS-Manager: Receive complete type definitions with full metadata when requested
      • Infrastructure-Manager: Receive complete type definitions with full metadata when requested
      • All Other Users: Receive basic type information with filtered metadata (sensitive information obfuscated).
      Example Usage: 
       ResourceRegistrySchemaClient client = ResourceRegistrySchemaClientFactory.create();
 
 // Read ContactFacet type definition with hierarchy level 1
 List<Type> contactFacetType = client.read(ContactFacet.class, 1);
 
 // Read ContactFacet type definition with deeper hierarchy level
 List<Type> contactFacetDeepType = client.read(ContactFacet.class, 3);
      This method is a type-safe wrapper that delegates to getTypeFromTypesKnowledge(String, int) for implementation details.
      Specified by:
      read in interface ResourceRegistrySchemaClient
      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clazz - the class of the model element type to retrieve
      level - the maximum hierarchy level to include in the response
      Returns:
      list of Type objects representing the type definition(s) with hierarchy limited to the specified level
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type corresponding to the specified class is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for retrieval errors or other system failures

    • getTypeTreeNode

      public org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type> getTypeTreeNode(String typeName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the type tree node for a specific type identified by its name. The tree node contains the type definition and its hierarchical position within the type system.
      Specified by:
      getTypeTreeNode in interface ResourceRegistrySchemaClient
      Parameters:
      typeName - the name of the type to retrieve
      Returns:
      the tree 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

    • getTypeTreeNode

      public <ME extends org.gcube.informationsystem.model.reference.ModelElement> org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type> getTypeTreeNode(Class<ME> clazz) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the type tree node for a specific type identified by its model element class. The tree node contains the type definition and its hierarchical position within the type system. This method is a type-safe wrapper that delegates to getTypeTreeNode(String) for implementation details.
      Specified by:
      getTypeTreeNode in interface ResourceRegistrySchemaClient
      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clazz - the class of the model element type to retrieve
      Returns:
      the tree 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

    • existTypeFromServer

      public boolean existTypeFromServer(String typeName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a type exists directly on the server using a HEAD request. This method bypasses the local cache and queries the server directly.
      Parameters:
      typeName - the name of the type to check
      Returns:
      true if the type exists on the server, false otherwise
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for server communication errors

    • getTypeFromServer

      public <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
      Retrieves type definitions directly from the server using a model element class. This method bypasses the local cache and queries the server directly. This method is a type-safe wrapper that delegates to getTypeFromServer(String, Boolean) for implementation details.
      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

      public String getTypeFromServer(String typeName, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves type definitions directly from the server by type name. This method bypasses the local cache and queries the server directly using REST API.
      Parameters:
      typeName - the name of the type to retrieve
      polymorphic - whether to include subtypes in the response
      Returns:
      JSON string containing the type definition(s) from the server
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for server communication errors