Package org.gcube.informationsystem.resourceregistry.schema

Class ResourceRegistrySchemaClientImpl

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected 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.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      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.

    • Field Detail

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

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

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