Package org.gcube.informationsystem.resourceregistry.client

Interface ResourceRegistryClient

All Superinterfaces:
org.gcube.informationsystem.resourceregistry.api.request.RequestInfo
All Known Implementing Classes:
ResourceRegistryClientImpl
public interface ResourceRegistryClient extends org.gcube.informationsystem.resourceregistry.api.request.RequestInfo
Client interface for querying and reading Information System entities, relations, and metadata from the Resource Registry. Purpose: This interface provides comprehensive read-only access to Information System model instances (Resources, Facets, ConsistsOf relations, IsRelatedTo relations), type schemas, query templates, and context information within the Resource Registry service. Instantiation: Clients should be created using the factory pattern for proper configuration: 
 // Recommended way to create a client
 ResourceRegistryClient client = ResourceRegistryClientFactory.create();
Supported Operations:
  • Context Operations: Access context information and hierarchy
  • Schema Operations: Access type definitions, hierarchies, and model knowledge
  • Instance Operations: Retrieve instance by type, UUID, or complex queries with filtering and pagination
  • Query Operations: Execute custom queries and manage query templates
  • Instance Navigation: Traverse relations between resources, facets, and other entities.
Query Parameter Configuration: Most methods support optional query parameters that can be configured via the client configuration:
  • includeMeta: Include metadata in responses (role-based filtering applied)
  • allMeta: Include metadata for all nested instances
  • includeContexts: Show context availability information
  • hierarchical: Include instances from child contexts (admin-only)
  • limit: Maximum number of results per request
  • offset: Number of results to skip for pagination.
Authorization: All operations respect authorization context derived from the current authentication token. Users can only access instances within their authorized contexts and see metadata appropriate for their role. Context Support: The client automatically operates within the context determined by the authorization token. Additional methods support cross-context queries for authorized users with hierarchical access.
Author:
Luca Frosini (ISTI - CNR)

  • Field Summary

    Fields inherited from interface org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

    DEFAULT_LIMIT, DEFAULT_OFFSET, UNBOUNDED_LIMIT

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    boolean
    existContext(String uuid)
    Checks if a context with the specified UUID (as string) exists in the system using internal cache.
    boolean
    existContext(UUID uuid)
    Checks if a context with the specified UUID exists in the system using internal cache.
    <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
    boolean
    existInstance(Class<ERElem> clazz, UUID uuid)
    Checks if an Information System element instance exists in the Resource Registry using class and UUID.
    boolean
    existInstance(String type, UUID uuid)
    Checks if an Information System element instance exists in the Resource Registry using type name and UUID.
    boolean
    existQueryTemplate(String queryTemplateName)
    Checks if a query template exists in the Resource Registry using template name.
    boolean
    existQueryTemplate(org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate queryTemplate)
    Checks if a query template exists in the Resource Registry.
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    boolean
    existType(Class<ME> clazz)
    Checks if a type definition exists in the Information System using a model element class.
    boolean
    existType(String typeName)
    Checks if a type definition exists in the Information System using the type name.
    List<org.gcube.informationsystem.contexts.reference.entities.Context>
    getAllContexts()
    Retrieves all available contexts using internal cache.
    List<org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate>
    getAllQueryTemplates()
    Retrieves all query templates from the Resource Registry.
    org.gcube.informationsystem.contexts.reference.entities.Context
    getContext(String uuid)
    Retrieves a specific context by its UUID (as string) using internal cache.
    org.gcube.informationsystem.contexts.reference.entities.Context
    getContext(UUID uuid)
    Retrieves a specific context by its UUID using internal cache.
    org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache
    getContextCache()
    Gets the context cache used for context-related operations.
    org.gcube.informationsystem.contexts.reference.entities.Context
    getCurrentContext()
    Retrieves the current context associated with the client's authorization token using internal cache.
    <R extends org.gcube.informationsystem.model.reference.entities.Resource, C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<?, ?>, F extends org.gcube.informationsystem.model.reference.entities.Facet>
    List<R>
    getFilteredResources(Class<R> resourceClass, Class<C> consistsOfClass, Class<F> facetClass, boolean polymorphic, Map<String,String> facetConstraint)
    Gets filtered resources based on facet constraints and relations (typed version).
    String
    getFilteredResources(String resourceType, String consistsOfType, String facetType, boolean polymorphic, Map<String,String> facetConstraint)
    Gets filtered resources based on facet constraints and relations (string version).
    <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
    ERElem
    getInstance(Class<ERElem> clazz, UUID uuid)
    Reads an existing instance from the Resource Registry by its type class and UUID.
    String
    getInstance(String type, UUID uuid)
    Reads an existing instance from the Resource Registry by its type name and UUID.
    <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
    Map<UUID,String>
    getInstanceContexts(Class<ERElem> clazz, UUID uuid)
    Retrieves the list of contexts where a specific Information System element is present in the Resource Registry.
    Map<UUID,String>
    getInstanceContexts(String type, UUID uuid)
    Retrieves the list of contexts where a specific Information System element is present in the Resource Registry.
    <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
    List<ERElem>
    getInstances(Class<ERElem> clazz, Boolean polymorphic)
    Retrieves all instances of the specified type from the Resource Registry.
    String
    getInstances(String type, Boolean polymorphic)
    Retrieves all instances of the specified type from the Resource Registry as JSON string.
    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.
    <R extends org.gcube.informationsystem.model.reference.entities.Resource, I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<?, ?>, RR extends org.gcube.informationsystem.model.reference.entities.Resource>
    List<R>
    getRelatedResources(Class<R> resourceClass, Class<I> isRelatedToClass, Class<RR> referenceResourceClass, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic)
    Gets all resources related to any resource of a specific type through an IsRelatedTo relation (typed version).
    String
    getRelatedResources(String resourceType, String isRelatedToType, String referenceResourceType, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic)
    Gets all resources related to any resource of a specific type through an IsRelatedTo relation (string version).
    <R extends org.gcube.informationsystem.model.reference.entities.Resource, I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<?, ?>, RR extends org.gcube.informationsystem.model.reference.entities.Resource>
    List<R>
    getRelatedResourcesFromReferenceResource(Class<R> resourceClass, Class<I> isRelatedToClass, Class<RR> referenceResourceClass, UUID referenceResourceUUID, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic)
    Gets resources related to a specific reference resource through an IsRelatedTo relation (typed version with UUID).
    <R extends org.gcube.informationsystem.model.reference.entities.Resource, I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<?, ?>, RR extends org.gcube.informationsystem.model.reference.entities.Resource>
    List<R>
    getRelatedResourcesFromReferenceResource(Class<R> resourceClass, Class<I> isRelatedToClass, RR referenceResource, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic)
    Gets resources related to a specific reference resource through an IsRelatedTo relation (typed version with instance).
    String
    getRelatedResourcesFromReferenceResource(String resourceType, String isRelatedToType, String referenceResourceType, UUID referenceResourceUUID, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic)
    Gets resources related to a specific reference resource through an IsRelatedTo relation (string version).
    <R extends org.gcube.informationsystem.model.reference.entities.Resource, C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<?, ?>, F extends org.gcube.informationsystem.model.reference.entities.Facet>
    List<R>
    getResourcesFromReferenceFacet(Class<R> resourceClass, Class<C> consistsOfClass, F referenceFacet, boolean polymorphic)
    Gets resources connected to a specific facet instance through a ConsistsOf relation (typed version).
    <R extends org.gcube.informationsystem.model.reference.entities.Resource, C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<?, ?>, F extends org.gcube.informationsystem.model.reference.entities.Facet>
    List<R>
    getResourcesFromReferenceFacet(Class<R> resourceClass, Class<C> consistsOfClass, Class<F> facetClass, UUID referenceFacetUUID, boolean polymorphic)
    Gets resources connected to a facet of specific type and UUID through a ConsistsOf relation (typed version).
    String
    getResourcesFromReferenceFacet(String resourceType, String consistsOfType, String facetType, UUID referenceFacetUUID, boolean polymorphic)
    Gets resources connected to a facet of specific type and UUID through a ConsistsOf relation (string version).
    <ME extends org.gcube.informationsystem.model.reference.ModelElement>
    List<org.gcube.informationsystem.types.reference.Type>
    getType(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>
    getType(Class<ME> clazz, Boolean polymorphic)
    Reads the type definitions for a specified model element class.
    String
    getType(String typeName, int level)
    Reads the schema definition for a specified type by name up to a specific hierarchy level.
    String
    getType(String typeName, Boolean polymorphic)
    Reads the schema definition for a specified type by name.
    <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.
    String
    jsonQuery(String query)
    Executes a JSON-based query to find instances matching the specified structure in the Resource Registry.
    <E extends org.gcube.informationsystem.model.reference.entities.Entity>
    List<E>
    jsonQuery(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode)
    Executes a JSON-based query to find instances matching the specified structure and returns typed results.
    String
    rawQuery(String query)
    Executes a raw OrientDB SQL query against the Resource Registry backend.
    String
    rawQuery(String query, boolean raw)
    Executes a raw OrientDB SQL query against the Resource Registry backend with configurable result formatting.
    org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate
    readQueryTemplate(String queryTemplateName)
    Reads an existing query template from the Resource Registry by its name.
    org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate
    readQueryTemplate(org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate queryTemplate)
    Reads an existing query template from the Resource Registry using a provided template object.
    String
    readQueryTemplateAsString(String queryTemplateName)
    Reads an existing query template from the Resource Registry as JSON string.
    void
    renewModelKnowledge()
    Forces a renewal of the cached model knowledge by fetching the latest version from the Resource Registry.
    String
    runQueryTemplate(String name)
    Executes a query template and returns results as JSON string (deprecated method).
    String
    runQueryTemplate(String name, String params)
    Executes a query template with string parameters and returns results as JSON string.
    String
    runQueryTemplate(String name, org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode)
    Executes a query template with JsonNode parameters and returns results as JSON string.
    String
    runQueryTemplate(org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate queryTemplate)
    Executes a query template using template object and returns results as JSON string.
    String
    runQueryTemplate(org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate queryTemplate, org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode)
    Executes a query template using template object with JsonNode parameters and returns results as JSON string.

    Methods inherited from interface org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

    allMeta, getLimit, getOffset, includeContexts, includeMeta, isHierarchicalMode, setAllMeta, setHierarchicalMode, setIncludeContexts, setIncludeMeta, setLimit, setOffset

  • Method Details

    • addHeader

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

    • addHeader

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

    • getContextCache

      org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache getContextCache()
      Gets the context cache used for context-related operations. Cache Behavior:
      • Provides access to the internal context cache used by all context methods;
      • Cache improves performance by avoiding repeated server requests;
      • Automatically manages cache updates and invalidation;
      • Used internally by getAllContexts(), existContext(), getContext(), and getCurrentContext().
      Authorization Requirements:
      • Available to all authenticated users;
      • Cache content is filtered based on user authorization level.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Access context cache for advanced operations
 ContextCache cache = client.getContextCache();
 
 // Force cache refresh if needed
 cache.refresh();
      Returns:
      The context cache instance

    • getAllContexts

      List<org.gcube.informationsystem.contexts.reference.entities.Context> getAllContexts() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves all available contexts using internal cache. Cache Behavior:
      • Uses internal context cache - does NOT bypass cache like server-direct methods
      • First call may trigger server request to populate cache
      • Subsequent calls return cached data for improved performance
      • Cache is automatically maintained and refreshed as needed.
      Query Parameters NOT Applicable:
      • Standard query parameters like includeMeta, limit, offset, hierarchical are NOT applicable to cached methods
      • Cache behavior is controlled internally for optimal performance
      • For direct server access with full query control, use the implementation's FromServer methods.
      Authorization Requirements:
      • Available to all authenticated users
      • Returns contexts accessible based on user authorization level
      • Context list is filtered according to user permissions.
      Context Content:
      • Includes all contexts where the user has any level of access
      • Context details include basic information (name, UUID, parent relationships)
      • Metadata inclusion depends on cache configuration and user role.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get all contexts from cache
 List<Context> contexts = client.getAllContexts();
 
 // Iterate through available contexts
 for (Context context : contexts) {
     System.out.println("Context: " + context.getName() + " (" + context.getUuid() + ")");
 }
      Returns:
      List of all contexts accessible to the current user (from cache)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If fails to retrieve contexts from cache or server

    • existContext

      boolean existContext(String uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a context with the specified UUID (as string) exists in the system using internal cache. Cache Behavior:
      • Uses internal context cache - does NOT bypass cache like server-direct methods
      • First call may trigger cache population from server if needed
      • Subsequent calls use cached data for improved performance
      • Cache is automatically maintained and refreshed as needed.
      Query Parameters NOT Applicable:
      • Standard query parameters like includeMeta, hierarchical are NOT applicable to cached methods
      • Cache behavior is controlled internally for optimal performance
      • For direct server existence checks, use the implementation's FromServer methods.
      Authorization Requirements:
      • Available to all authenticated users
      • Returns true only if context exists AND is accessible based on user authorization level
      • Contexts outside user's access scope will return false.
      Input Validation:
      • UUID string format is validated before cache lookup
      • Invalid UUID format throws IllegalArgumentException
      • Null or empty strings are handled gracefully.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Check context existence using cache
 String contextUUID = "c0f314e7-2807-4241-a792-2a6c79ed4fd0";
 if (client.existContext(contextUUID)) {
     System.out.println("Context exists and is accessible");
 } else {
     System.out.println("Context not found or not accessible");
 }
      Parameters:
      uuid - the UUID of the context (as string) to check for existence
      Returns:
      true if the context exists and is accessible to the current user, false if not found
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If there are communication errors with the Resource Registry service
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check
      IllegalArgumentException - If the provided string is not a valid UUID format

    • existContext

      boolean existContext(UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a context with the specified UUID exists in the system using internal cache. Cache Behavior:
      • Uses internal context cache - does NOT bypass cache like server-direct methods
      • First call may trigger cache population from server if needed
      • Subsequent calls use cached data for improved performance
      • Cache is automatically maintained and refreshed as needed.
      Query Parameters NOT Applicable:
      • Standard query parameters like includeMeta, hierarchical are NOT applicable to cached methods
      • Cache behavior is controlled internally for optimal performance
      • For direct server existence checks, use the implementation's FromServer methods.
      Authorization Requirements:
      • Available to all authenticated users
      • Returns true only if context exists AND is accessible based on user authorization level
      • Contexts outside user's access scope will return false.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Check context existence using cache
 UUID contextUUID = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 if (client.existContext(contextUUID)) {
     System.out.println("Context exists and is accessible");
 } else {
     System.out.println("Context not found or not accessible");
 }
      Parameters:
      uuid - the UUID of the context to check for existence
      Returns:
      true if the context exists and is accessible to the current user, false if not found
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the context is not found or not accessible
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

    • getContext

      org.gcube.informationsystem.contexts.reference.entities.Context getContext(String uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves a specific context by its UUID (as string) using internal cache. Cache Behavior:
      • Uses internal context cache - does NOT bypass cache like server-direct methods
      • First call may trigger cache population from server if needed
      • Subsequent calls use cached data for improved performance
      • Cache is automatically maintained and refreshed as needed.
      Query Parameters NOT Applicable:
      • Standard query parameters like includeMeta, hierarchical are NOT applicable to cached methods
      • Metadata inclusion depends on cache configuration and user role
      • For direct server access with full query control, use the implementation's FromServer methods.
      Authorization Requirements:
      • Available to all authenticated users
      • Returns context only if accessible based on user authorization level
      • Context details are filtered according to user permissions and role.
      Context Content:
      • Includes basic context information (name, UUID, parent relationships)
      • Metadata inclusion depends on user role: IS-Manager/Infrastructure-Manager see complete metadata, others see filtered metadata
      • Sensitive information (createdBy, lastUpdatedBy) may be obfuscated for non-administrative users.
      Input Validation:
      • UUID string format is validated before cache lookup
      • Invalid UUID format throws IllegalArgumentException
      • Null or empty strings are handled gracefully.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get context from cache
 String contextUUID = "c0f314e7-2807-4241-a792-2a6c79ed4fd0";
 Context context = client.getContext(contextUUID);
 
 System.out.println("Context name: " + context.getName());
 System.out.println("Context UUID: " + context.getUuid());
 System.out.println("Parent context: " + context.getParent());
      Parameters:
      uuid - the UUID of the context (as string) to retrieve
      Returns:
      the Context object with role-appropriate detail level (from cache)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the context with the specified UUID is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval or authorization issues
      IllegalArgumentException - If the provided string is not a valid UUID format

    • getContext

      org.gcube.informationsystem.contexts.reference.entities.Context getContext(UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves a specific context by its UUID using internal cache. Cache Behavior:
      • Uses internal context cache - does NOT bypass cache like server-direct methods
      • First call may trigger cache population from server if needed
      • Subsequent calls use cached data for improved performance
      • Cache is automatically maintained and refreshed as needed.
      Query Parameters NOT Applicable:
      • Standard query parameters like includeMeta, hierarchical are NOT applicable to cached methods
      • Metadata inclusion depends on cache configuration and user role
      • For direct server access with full query control, use the implementation's FromServer methods.
      Authorization Requirements:
      • Available to all authenticated users
      • Returns context only if accessible based on user authorization level
      • Context details are filtered according to user permissions and role.
      Context Content:
      • Includes basic context information (name, UUID, parent relationships)
      • Metadata inclusion depends on user role: IS-Manager/Infrastructure-Manager see complete metadata, others see filtered metadata
      • Sensitive information (createdBy, lastUpdatedBy) may be obfuscated for non-administrative users.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get context from cache
 UUID contextUUID = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 Context context = client.getContext(contextUUID);
 
 System.out.println("Context name: " + context.getName());
 System.out.println("Context UUID: " + context.getUuid());
 System.out.println("Parent context: " + context.getParent());
      Parameters:
      uuid - the UUID of the context to retrieve
      Returns:
      the Context object with role-appropriate detail level (from cache)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the context with the specified UUID is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval or authorization issues

    • getCurrentContext

      org.gcube.informationsystem.contexts.reference.entities.Context getCurrentContext() throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the current context associated with the client's authorization token using internal cache. Cache Behavior:
      • Uses internal context cache - does NOT bypass cache like server-direct methods
      • Current context is determined from the authorization token/secret
      • First call may trigger cache population from server if needed
      • Subsequent calls use cached data for improved performance.
      Query Parameters NOT Applicable:
      • Standard query parameters like includeMeta, hierarchical are NOT applicable to cached methods
      • Metadata inclusion depends on cache configuration and user role
      • For direct server access with full query control, use the implementation's FromServer methods.
      Authorization Requirements:
      • Available to all authenticated users
      • Returns the context associated with the current authorization token
      • Context details are filtered according to user permissions and role.
      Context Resolution:
      • Current context is extracted from the authorization token/secret
      • Token must contain valid context information
      • Context must be accessible to the user associated with the token.
      Context Content:
      • Includes basic context information (name, UUID, parent relationships)
      • Metadata inclusion depends on user role: IS-Manager/Infrastructure-Manager see complete metadata, others see filtered metadata
      • Sensitive information (createdBy, lastUpdatedBy) may be obfuscated for non-administrative users.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get current context from cache
 Context currentContext = client.getCurrentContext();
 
 System.out.println("Current context name: " + currentContext.getName());
 System.out.println("Current context UUID: " + currentContext.getUuid());
 System.out.println("Current context parent: " + currentContext.getParent());
      Returns:
      the Context object associated with the current authorization token (from cache)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be found or resolved
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval or authorization issues

    • getModelKnowledge

      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. Corresponding REST API: Multiple endpoints used internally to build the complete model knowledge Operation Behavior:
      • Returns a cached version of the complete type system model
      • Includes all type definitions, their properties, and hierarchical relationships
      • Provides access to type information used for validation and schema operations
      • Cache is automatically maintained and updated as needed.
      Model Knowledge Content:
      • Type Definitions: Complete schema definitions for all registered types
      • Type Hierarchy: Parent-child relationships between types
      • Type Properties: Property definitions and constraints for each type
      • Type Metadata: Additional information about type usage and validation rules.
      Authorization Requirements:
      • Available to all authenticated users
      • No special permissions required for accessing type definitions
      • Type information is considered public metadata within the system.
      Caching Behavior:
      • Model knowledge is cached for performance
      • Cache is automatically refreshed when schema changes are detected
      • Use renewModelKnowledge() to force cache refresh if needed.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get complete model knowledge
 ModelKnowledge<Type, TypeInformation> modelKnowledge = client.getModelKnowledge();
 
 // Access type information
 TypeInformation contactFacetInfo = modelKnowledge.getTypeInformation("ContactFacet");
 Type eServiceType = modelKnowledge.getType("EService");
 
 // Check type hierarchy
 Set<String> subTypes = modelKnowledge.getSubTypes("Resource", true);
      Returns:
      the model knowledge containing type definitions and information

    • renewModelKnowledge

      void renewModelKnowledge()
      Forces a renewal of the cached model knowledge by fetching the latest version from the Resource Registry. This method should be called when the schema has been modified and the local cache needs to be updated. Corresponding REST API: Multiple endpoints used internally to rebuild the complete model knowledge Operation Behavior:
      • Clears the current cached model knowledge
      • Fetches the latest type definitions from the Resource Registry
      • Rebuilds the complete model knowledge structure
      • Updates internal caches with the new information.
      When to Use:
      • After schema modifications that add, modify, or remove type definitions
      • When working with dynamic schema changes in development environments
      • If type validation errors suggest schema inconsistencies
      • When explicit cache refresh is needed for testing purposes.
      Performance Considerations:
      • This operation involves multiple REST API calls to rebuild the model
      • Should be used sparingly in production environments
      • Consider the impact on application performance when calling this method
      • Automatic cache refresh is usually sufficient for most use cases.
      Authorization Requirements:
      • Available to all authenticated users
      • No special permissions required for refreshing type definitions
      • Same authorization level as getModelKnowledge().
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Force refresh of model knowledge after schema changes
 client.renewModelKnowledge();
 
 // Now get updated model knowledge
 ModelKnowledge<Type, TypeInformation> freshModelKnowledge = client.getModelKnowledge();

    • existType

      boolean existType(String typeName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a type definition exists in the Information System using the type name.
      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

    • existType

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> boolean existType(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.
      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

    • getType

      String getType(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.
      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

    • getType

      String getType(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.
      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

    • getType

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> List<org.gcube.informationsystem.types.reference.Type> getType(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.
      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

    • getType

      <ME extends org.gcube.informationsystem.model.reference.ModelElement> List<org.gcube.informationsystem.types.reference.Type> getType(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.
      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

      <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.
      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 type corresponding to the specified class does not exist in the schema
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the operation

    • getTypeTreeNode

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

    • getInstances

      <ERElem extends org.gcube.informationsystem.model.reference.ERElement> List<ERElem> getInstances(Class<ERElem> clazz, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves all instances of the specified type from the Resource Registry. Corresponding REST API: GET /access/instances/{type-name}[?polymorphic={true|false}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:
      • Returns all instances of the specified type that are accessible in the current context
      • Supports polymorphic queries to include instances of subtypes
      • Results are filtered based on user authorization and context access
      • Returns strongly-typed objects instead of JSON strings.
      Query Parameters: limit (configurable via client configuration):
      • Maximum number of instances to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 instances per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: InstancePath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of instances to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 instances (useful for pagination)
      • Query parameter: InstancePath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response instance
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instance, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main instance only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the instance and its nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include instances from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      Input Processing:
      • The type name is automatically derived from the provided class using TypeUtility.getTypeName(Class)
      • 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).
      Context Access:
      • The instances must be accessible in the current context or child contexts (depending on hierarchical mode)
      • IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
      • Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.
      Authorization Requirements:
      • All users must have a valid token and read permissions for the specific context where they want to list instances.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get all EService instances including subtypes
 List<EService> services = client.getInstances(EService.class, true);
 
 // Get only exact ContactFacet instances (no subtypes)
 List<ContactFacet> contacts = client.getInstances(ContactFacet.class, false);
      Type Parameters:
      ERElem - The specific type of Information System element to retrieve
      Parameters:
      clazz - The class representing the type of instances to retrieve
      polymorphic - Whether to include instances of subtypes (true) or only exact type instances (false). When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the polymorphic query parameter of the REST API call.
      Returns:
      List of instances of the specified type accessible in the current context
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval or if the type is invalid

    • getInstances

      String getInstances(String type, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves all instances of the specified type from the Resource Registry as JSON string. Corresponding REST API: GET /access/instances/{type-name}[?polymorphic={true|false}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:
      • Returns all instances of the specified type that are accessible in the current context
      • Supports polymorphic queries to include instances of subtypes
      • Results are filtered based on user authorization and context access
      • Returns the response as a JSON array string.
      Query Parameters: limit (configurable via client configuration):
      • Maximum number of instances to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 instances per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: InstancePath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of instances to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 instances (useful for pagination)
      • Query parameter: InstancePath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response instance
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instance, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main instance only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the instance and its nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include instances from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      Input Processing:
      • 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 names are case-sensitive and must match exactly the class names defined in the Information System model.
      Context Access:
      • The instances must be accessible in the current context or child contexts (depending on hierarchical mode)
      • IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
      • Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.
      Authorization Requirements:
      • All users must have a valid token and read permissions for the specific context where they want to list instances.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get all EService instances including subtypes as JSON
 String servicesJson = client.getInstances("EService", true);
 
 // Get only exact ContactFacet instances (no subtypes) as JSON
 String contactsJson = client.getInstances("ContactFacet", false);
      Parameters:
      type - The name of the Information System type to retrieve (case-sensitive)
      polymorphic - Whether to include instances of subtypes (true) or only exact type instances (false). When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the polymorphic query parameter of the REST API call.
      Returns:
      JSON array string containing instances of the specified type accessible in the current context
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval or if the type is invalid

    • existInstance

      <ERElem extends org.gcube.informationsystem.model.reference.ERElement> boolean existInstance(Class<ERElem> clazz, UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if an Information System element instance exists in the Resource Registry using class and UUID. Corresponding REST API: HEAD /access/instances/{type-name}/{uuid}[?hierarchical={true|false}] Operation Behavior:
      • Verifies the existence of the specified instance using its UUID and class type
      • Type name is automatically derived from the class using reflection
      • Does not return the instance data, only confirms existence
      • Checks accessibility within the current context and user authorization
      • Convenient method when working with strongly-typed classes.
      HTTP Response Codes:
      • 200 OK: Instance exists and is accessible in the current context
      • 404 Not Found: Instance does not exist or is not accessible
      • 403 Forbidden: Instance exists but user lacks authorization to access it
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Query Parameters: hierarchical (configurable via client configuration, admin-only):
      • Whether to include instances from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      Input Processing:
      • The type name is automatically derived from the provided class using TypeUtility.getTypeName(Class)
      • 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).
      Context Access:
      • The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
      • IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
      • Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.
      Authorization Requirements:
      • All users must have a valid token and read permissions for the specific context where they want to check existence.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Check if an EService instance exists by class and UUID
 UUID serviceUUID = UUID.fromString("...");
 boolean exists = client.existInstance(EService.class, serviceUUID);
 
 // Check if a ContactFacet instance exists by class and UUID
 UUID contactUUID = UUID.fromString("...");
 boolean contactExists = client.existInstance(ContactFacet.class, contactUUID);
      Type Parameters:
      ERElem - The specific type of Information System element to check
      Parameters:
      clazz - The class representing the type of instance to check
      uuid - The UUID of the instance to check for existence
      Returns:
      true if the instance exists and is accessible in the current context, false if not found
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

    • existInstance

      boolean existInstance(String type, UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if an Information System element instance exists in the Resource Registry using type name and UUID. Corresponding REST API: HEAD /access/instances/{type-name}/{uuid}[?hierarchical={true|false}] Operation Behavior:
      • Verifies the existence of the specified instance using its UUID and type name
      • Does not return the instance data, only confirms existence
      • Checks accessibility within the current context and user authorization
      • Most direct method when type name is already known.
      HTTP Response Codes:
      • 200 OK: Instance exists and is accessible in the current context
      • 404 Not Found: Instance does not exist or is not accessible
      • 403 Forbidden: Instance exists but user lacks authorization to access it
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Query Parameters: hierarchical (configurable via client configuration, admin-only):
      • Whether to include instances from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      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.
      Context Access:
      • The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
      • IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
      • Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.
      Authorization Requirements:
      • All users must have a valid token and read permissions for the specific context where they want to check existence.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Check if an EService instance exists by type name and UUID
 UUID serviceUUID = UUID.fromString("...");
 boolean exists = client.existInstance("EService", serviceUUID);
 
 // Check if a ContactFacet instance exists by type name and UUID
 UUID contactUUID = UUID.fromString("...");
 boolean contactExists = client.existInstance("ContactFacet", contactUUID);
      Parameters:
      type - The name of the Information System type to check
      uuid - The UUID of the instance to check for existence
      Returns:
      true if the instance exists and is accessible in the current context, false if not found
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

    • getInstance

      <ERElem extends org.gcube.informationsystem.model.reference.ERElement> ERElem getInstance(Class<ERElem> clazz, UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads an existing instance from the Resource Registry by its type class and UUID. Corresponding REST API: GET /access/instances/{type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:
      • Retrieves an existing instance (Entity or Relation) by its type class and unique identifier
      • Type name is automatically derived from the class using reflection
      • The instance must be accessible in the current context or in child contexts (based on hierarchical mode)
      • Returns the complete instance with all properties and metadata
      • Returns strongly-typed objects instead of JSON strings.
      HTTP Response Codes:
      • 200 OK: Instance successfully retrieved
      • 404 Not Found: No instance found with the specified UUID and type, or not accessible in current context
      • 403 Forbidden: User lacks read permissions for the instance or its context
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Query Parameters: includeMeta (configurable via client configuration):
      • Whether to include metadata in the response instance
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instance, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main instance only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the instance and its nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include instances from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      Input Processing:
      • The type name is automatically derived from the provided class using TypeUtility.getTypeName(Class)
      • 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).
      Context Access:
      • The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
      • IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
      • Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.
      Authorization Requirements:
      • All users must have a valid token and read permissions for the specific context where they want to read instances.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Read an EService instance by class and UUID
 UUID serviceUuid = UUID.fromString("...");
 EService service = client.getInstance(EService.class, serviceUuid);
 
 // Read a ContactFacet instance by class and UUID
 UUID contactUuid = UUID.fromString("...");
 ContactFacet contact = client.getInstance(ContactFacet.class, contactUuid);
      Type Parameters:
      ERElem - The specific type of Entity or Relation to read
      Parameters:
      clazz - The class of the Entity or Relation type to read
      uuid - The unique identifier of the instance to read
      Returns:
      The complete instance from the Resource Registry
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If no instance is found with the specified UUID and type
      org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

    • getInstance

      String getInstance(String type, UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads an existing instance from the Resource Registry by its type name and UUID. Corresponding REST API: GET /access/instances/{type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:
      • Retrieves an existing instance (Entity or Relation) by its type name and unique identifier
      • The instance must be accessible in the current context or in child contexts (based on hierarchical mode)
      • Returns the complete instance as JSON with all properties and metadata
      • Type validation ensures the UUID corresponds to an instance of the specified type.
      HTTP Response Codes:
      • 200 OK: Instance successfully retrieved
      • 404 Not Found: No instance found with the specified UUID and type, or not accessible in current context
      • 403 Forbidden: User lacks read permissions for the instance or its context
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Query Parameters: includeMeta (configurable via client configuration):
      • Whether to include metadata in the response instance
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: InstancePath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested instances (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instance, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main instance only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: InstancePath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the instance and its nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include instances from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      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 names are case-sensitive and must match exactly the class names defined in the Information System model.
      Context Access:
      • The instance must be accessible in the current context or child contexts (depending on hierarchical mode)
      • IS-Manager and Infrastructure-Manager are global roles (available in all contexts) and can use hierarchical mode in any contexts
      • Context-Manager is a context-specific role and can use hierarchical mode only in contexts where they have this role.
      Authorization Requirements:
      • All users must have a valid token and read permissions for the specific context where they want to read instances.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Read an EService instance by type name and UUID as JSON
 UUID serviceUuid = UUID.fromString("...");
 String serviceJson = client.getInstance("EService", serviceUuid);
 
 // Read a ContactFacet instance by type name and UUID as JSON
 UUID contactUuid = UUID.fromString("...");
 String contactJson = client.getInstance("ContactFacet", contactUuid);
      Parameters:
      type - The name of the Information System type to read (case-sensitive)
      uuid - The unique identifier of the instance to read
      Returns:
      JSON string containing the complete instance from the Resource Registry
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If no instance is found with the specified UUID and type
      org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

    • getInstanceContexts

      <ERElem extends org.gcube.informationsystem.model.reference.ERElement> Map<UUID,String> getInstanceContexts(Class<ERElem> clazz, UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the list of contexts where a specific Information System element is present in the Resource Registry. Corresponding REST API: GET /access/instances/{type-name}/{instance-uuid}/contexts Operation Behavior:
      • Retrieves all contexts where the specified element (Resource, Facet, ConsistsOf, or IsRelatedTo) is present
      • Type name is automatically derived from the class using reflection
      • The element must exist and be accessible to the user
      • Returns a map where keys are context UUIDs and values are the full context paths
      • No filtering, pagination, or metadata options are available
      • Context information is determined by the element's presence across different VREs and organizational contexts.
      HTTP Response Codes:
      • 200 OK: Context list successfully retrieved
      • 404 Not Found: Element does not exist with the specified type and UUID
      • 403 Forbidden: Element exists but is not accessible for context listing in the current authorization scope
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Authorization Requirements:
      • IS-Manager: Can retrieve context information for any element across the entire infrastructure
      • Infrastructure-Manager: Can retrieve context information for any element across the entire infrastructure
      • Context-Manager: Can retrieve context information for elements accessible within their managed contexts
      • Other Users: Can retrieve context information for elements accessible through their authorization token.
      Response Format:
      • Returns a Map where keys are context UUIDs (UUID) and values are full context paths (String)
      • Empty map is returned if the element exists but is not present in any contexts
      • Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").
      Element Context Rules:
      • Resources: Present in all contexts that form the union of contexts of all their Facets
      • Facets: Present in the contexts where they are explicitly available
      • ConsistsOf Relations: Present in all contexts where their target Facets are present
      • IsRelatedTo Relations: Present based on their specific context assignments.
      Type Safety:
      • This method provides compile-time type safety by accepting any ERElement subtype
      • The element's type is automatically determined from the object's class
      • Supports all Information System element types including Resources, Facets, and Relations.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get contexts for an EService by class and UUID
 UUID serviceUuid = UUID.fromString("48af15ad-7e56-4157-b624-71c98cea4f8f");
 Map<UUID, String> contexts = client.getInstanceContexts(EService.class, serviceUuid);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
      Type Parameters:
      ERElem - The type of Information System element (Resource, Facet, ConsistsOf, or IsRelatedTo)
      Parameters:
      clazz - The class of the Information System element whose contexts to retrieve
      uuid - The unique identifier of the element whose contexts to retrieve
      Returns:
      Map containing context UUID to context path mappings where the element is present
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If no element is found with the specified class and UUID
      org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the element exists but is not accessible for context listing
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

    • getInstanceContexts

      Map<UUID,String> getInstanceContexts(String type, UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the list of contexts where a specific Information System element is present in the Resource Registry. Corresponding REST API: GET /access/instances/{type-name}/{instance-uuid}/contexts Operation Behavior:
      • Retrieves all contexts where the specified element (Resource, Facet, ConsistsOf, or IsRelatedTo) is present
      • The element must exist and be accessible to the user
      • Returns a map where keys are context UUIDs and values are the full context paths
      • No filtering, pagination, or metadata options are available
      • Context information is determined by the element's presence across different VREs and organizational contexts.
      HTTP Response Codes:
      • 200 OK: Context list successfully retrieved
      • 404 Not Found: Element does not exist with the specified type and UUID
      • 403 Forbidden: Element exists but is not accessible for context listing in the current authorization scope
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Authorization Requirements:
      • IS-Manager: Can retrieve context information for any element across the entire infrastructure
      • Infrastructure-Manager: Can retrieve context information for any element across the entire infrastructure
      • Context-Manager: Can retrieve context information for elements accessible within their managed contexts
      • Other Users: Can retrieve context information for elements accessible through their authorization token.
      Response Format:
      • Returns a Map where keys are context UUIDs (UUID) and values are full context paths (String)
      • Empty map is returned if the element exists but is not present in any contexts
      • Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").
      Element Context Rules:
      • Resources: Present in all contexts that form the union of contexts of all their Facets
      • Facets: Present in the contexts where they are explicitly available
      • ConsistsOf Relations: Present in all contexts where their target Facets are present
      • IsRelatedTo Relations: Present based on their specific context assignments.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get contexts for an EService by type and UUID
 UUID serviceUuid = UUID.fromString("48af15ad-7e56-4157-b624-71c98cea4f8f");
 Map<UUID, String> contexts = client.getInstanceContexts("EService", serviceUuid);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
      Parameters:
      type - The exact type name of the Information System element (e.g., "EService", "ContactFacet")
      uuid - The unique identifier of the element whose contexts to retrieve
      Returns:
      Map containing context UUID to context path mappings where the element is present
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If no element is found with the specified type and UUID
      org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the element exists but is not accessible for context listing
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

    • getAllQueryTemplates

      List<org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate> getAllQueryTemplates() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves all query templates from the Resource Registry. Corresponding REST API: GET /access/query-templates[?limit={number}&offset={number}&includeMeta={true|false}] Operation Behavior:
      • Returns all query templates accessible to the current user
      • Results are filtered based on user authorization
      • Provides pagination support via limit and offset parameters
      • Can include metadata with role-based filtering when requested.
      Query Parameters: limit (configurable via client configuration):
      • Maximum number of query templates to return in a single response
      • Default value: 10
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 query templates per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: QueryTemplatePath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of query templates to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(100)
      • Example: Set to 100 to skip the first 100 query templates (useful for pagination)
      • Query parameter: QueryTemplatePath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response query templates
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: QueryTemplatePath.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.
      HTTP Response Codes:
      • 200 OK: Query templates successfully retrieved
      • 400 Bad Request: Invalid query parameters (e.g., invalid limit/offset values)
      • 403 Forbidden: Insufficient permissions to access query templates
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • No input parameters required for this operation
      • All available query templates are retrieved based on user authorization.
      Context Access:
      • Query templates are global resources accessible across contexts
      • Access level depends on user role and authorization.
      Authorization Requirements:
      • IS-Manager: Full access to all query templates with complete, unfiltered metadata including all administrative fields
      • Infrastructure-Manager: Full access to all query templates with complete, unfiltered metadata including all administrative fields
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Get all query templates with default pagination
 List<QueryTemplate> templates = client.getAllQueryTemplates();
 
 // Get query templates with custom pagination and metadata
 client.setLimit(20);
 client.setOffset(40);
 client.setIncludeMeta(true);
 List<QueryTemplate> templatesWithMeta = client.getAllQueryTemplates();
      Returns:
      List of all query templates accessible to the current user
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template retrieval

    • existQueryTemplate

      boolean existQueryTemplate(org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate queryTemplate) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a query template exists in the Resource Registry. Corresponding REST API: GET /access/query-templates/{query-template-name} Operation Behavior:
      • Verifies the existence of the specified query template using its name
      • The template name is automatically extracted from the provided QueryTemplate object
      • Does not return the template data, only confirms existence
      • Checks accessibility based on user authorization.
      Query Parameters:
      • This operation does not use query parameters for existence checking
      • Existence is determined by attempting to retrieve the template without metadata.
      HTTP Response Codes:
      • 200 OK: Query template exists and is accessible
      • 404 Not Found: Query template does not exist
      • 403 Forbidden: Query template exists but user lacks authorization to access it
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • The query template name is automatically extracted from the provided QueryTemplate object
      • Only the name field is used for the existence check.
      Context Access:
      • Query templates are global resources accessible across contexts
      • Access level depends on user role and authorization.
      Authorization Requirements:
      • IS-Manager: Full access to check existence of any query template
      • Infrastructure-Manager: Full access to check existence of any query template
      • All Other Users: Basic access with metadata filtering; can check existence of accessible templates.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Check if a query template exists
 QueryTemplate template = new QueryTemplate();
 template.setName("GetAllEServiceWithState");
 boolean exists = client.existQueryTemplate(template);
      Parameters:
      queryTemplate - The query template to check for existence (must have a valid name)
      Returns:
      true if the query template exists and is accessible, false if not found
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

    • existQueryTemplate

      boolean existQueryTemplate(String queryTemplateName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a query template exists in the Resource Registry using template name. Corresponding REST API: GET /access/query-templates/{query-template-name} Operation Behavior:
      • Verifies the existence of the specified query template using its name
      • Does not return the template data, only confirms existence
      • Checks accessibility based on user authorization
      • Most direct method when template name is already known.
      Query Parameters:
      • This operation does not use query parameters for existence checking
      • Existence is determined by attempting to retrieve the template without metadata.
      HTTP Response Codes:
      • 200 OK: Query template exists and is accessible
      • 404 Not Found: Query template does not exist
      • 403 Forbidden: Query template exists but user lacks authorization to access it
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • Template name must be a valid query template name
      • Template names are case-sensitive and must match exactly.
      Context Access:
      • Query templates are global resources accessible across contexts
      • Access level depends on user role and authorization.
      Authorization Requirements:
      • IS-Manager: Full access to check existence of any query template
      • Infrastructure-Manager: Full access to check existence of any query template
      • All Other Users: Basic access with metadata filtering; can check existence of accessible templates.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Check if a query template exists by name
 boolean exists = client.existQueryTemplate("GetAllEServiceWithState");
      Parameters:
      queryTemplateName - The name of the query template to check for existence
      Returns:
      true if the query template exists and is accessible, false if not found
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

    • readQueryTemplate

      org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate readQueryTemplate(org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate queryTemplate) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads an existing query template from the Resource Registry using a provided template object. Corresponding REST API: GET /access/query-templates/{query-template-name}[?includeMeta={true|false}] Operation Behavior:
      • Retrieves an existing query template by extracting name from the provided template object
      • The template must be accessible based on user authorization
      • Returns the complete template with all properties and metadata
      • The name is automatically determined from the provided template object.
      Query Parameters: includeMeta (configurable via client configuration):
      • Whether to include metadata in the response query template
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: QueryTemplatePath.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.
      HTTP Response Codes:
      • 200 OK: Query template successfully retrieved
      • 404 Not Found: No query template found with the specified name
      • 403 Forbidden: User lacks read permissions for the query template
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • The query template name is automatically extracted from the provided QueryTemplate object
      • Only the name field is used for template retrieval.
      Context Access:
      • Query templates are global resources accessible across contexts
      • Access level depends on user role and authorization.
      Authorization Requirements:
      • IS-Manager: Full access to retrieve any query template with complete, unfiltered metadata including all administrative fields
      • Infrastructure-Manager: Full access to retrieve any query template with complete, unfiltered metadata including all administrative fields
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Read a query template using template object
 QueryTemplate template = new QueryTemplate();
 template.setName("GetAllEServiceWithState");
 QueryTemplate readTemplate = client.readQueryTemplate(template);
      Parameters:
      queryTemplate - Template object containing at least the name
      Returns:
      The complete query template from the Resource Registry
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException - If no query template is found with the specified name
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during template retrieval

    • readQueryTemplate

      org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate readQueryTemplate(String queryTemplateName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads an existing query template from the Resource Registry by its name. Corresponding REST API: GET /access/query-templates/{query-template-name}[?includeMeta={true|false}] Operation Behavior:
      • Retrieves an existing query template by its name
      • The template must be accessible based on user authorization
      • Returns the complete template with all properties and metadata
      • Most direct method when template name is already known.
      Query Parameters: includeMeta (configurable via client configuration):
      • Whether to include metadata in the response query template
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: QueryTemplatePath.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.
      HTTP Response Codes:
      • 200 OK: Query template successfully retrieved
      • 404 Not Found: No query template found with the specified name
      • 403 Forbidden: User lacks read permissions for the query template
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • The specified name must be a valid query template name
      • Template names are case-sensitive and must match exactly
      • Name must correspond to an existing template.
      Context Access:
      • Query templates are global resources accessible across contexts
      • Access level depends on user role and authorization.
      Authorization Requirements:
      • IS-Manager: Full access to retrieve any query template with complete, unfiltered metadata including all administrative fields
      • Infrastructure-Manager: Full access to retrieve any query template with complete, unfiltered metadata including all administrative fields
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Read a query template by name
 QueryTemplate template = client.readQueryTemplate("GetAllEServiceWithState");
      Parameters:
      queryTemplateName - The name of the query template to read
      Returns:
      The complete query template from the Resource Registry
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException - If no query template is found with the specified name
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during template retrieval

    • readQueryTemplateAsString

      String readQueryTemplateAsString(String queryTemplateName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Reads an existing query template from the Resource Registry as JSON string. Corresponding REST API: GET /access/query-templates/{query-template-name}[?includeMeta={true|false}] Operation Behavior:
      • Retrieves an existing query template by its name
      • The template must be accessible based on user authorization
      • Returns the complete template as JSON with all properties and metadata
      • Returns the response as a JSON object string.
      Query Parameters: includeMeta (configurable via client configuration):
      • Whether to include metadata in the response query template
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: QueryTemplatePath.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.
      HTTP Response Codes:
      • 200 OK: Query template successfully retrieved
      • 404 Not Found: No query template found with the specified name
      • 403 Forbidden: User lacks read permissions for the query template
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • The specified name must be a valid query template name
      • Template names are case-sensitive and must match exactly
      • Name must correspond to an existing template.
      Context Access:
      • Query templates are global resources accessible across contexts
      • Access level depends on user role and authorization.
      Authorization Requirements:
      • IS-Manager: Full access to retrieve any query template with complete, unfiltered metadata including all administrative fields
      • Infrastructure-Manager: Full access to retrieve any query template with complete, unfiltered metadata including all administrative fields
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Read a query template as JSON string
 String templateJson = client.readQueryTemplateAsString("GetAllEServiceWithState");
      Parameters:
      queryTemplateName - The name of the query template to read
      Returns:
      JSON representation of the complete query template from the Resource Registry
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException - If no query template is found with the specified name
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during template retrieval

    • runQueryTemplate

      String runQueryTemplate(String name) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a query template and returns results as JSON string (deprecated method). Corresponding REST API: POST /access/query-templates/{query-template-name}[?polymorphic={true|false}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:
      • Executes the specified query template with no parameters
      • Returns query results as a JSON array string
      • Uses default parameter values if the template defines any parameters
      • Results are filtered based on user authorization and context access.
      Query Parameters: HTTP Response Codes:
      • 200 OK: Query template successfully executed
      • 404 Not Found: Query template with the specified name does not exist
      • 400 Bad Request: Invalid query execution or parameter values
      • 403 Forbidden: Insufficient permissions to execute the query template
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • Template name must be a valid query template name
      • Template names are case-sensitive and must match exactly
      • Name must correspond to an existing template.
      Context Access:
      • Query execution respects context boundaries based on user authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies.
      Authorization Requirements:
      • IS-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Execute a query template and get results as JSON
 String resultsJson = client.runQueryTemplate("GetAllEService");
      Parameters:
      name - The name of the query template to execute
      Returns:
      JSON array string containing query results
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template execution

    • runQueryTemplate

      String runQueryTemplate(org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate queryTemplate) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a query template using template object and returns results as JSON string. Corresponding REST API: POST /access/query-templates/{query-template-name}[?polymorphic={true|false}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:
      • Executes the query template with no parameters
      • The template name is extracted from the provided QueryTemplate object
      • Returns query results as a JSON array string
      • Uses default parameter values if the template defines any parameters
      • Results are filtered based on user authorization and context access.
      Query Parameters: HTTP Response Codes:
      • 200 OK: Query template successfully executed
      • 404 Not Found: Query template with the specified name does not exist
      • 400 Bad Request: Invalid query execution or parameter values
      • 403 Forbidden: Insufficient permissions to execute the query template
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • The query template name is automatically extracted from the provided QueryTemplate object
      • Only the name field is used for template execution.
      Context Access:
      • Query execution respects context boundaries based on user authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies.
      Authorization Requirements:
      • IS-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Execute a query template using template object
 QueryTemplate template = new QueryTemplate();
 template.setName("GetAllEService");
 String resultsJson = client.runQueryTemplate(template);
      Parameters:
      queryTemplate - The query template to execute (name is extracted from this object)
      Returns:
      JSON array string containing query results
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template execution

    • runQueryTemplate

      String runQueryTemplate(String name, String params) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a query template with string parameters and returns results as JSON string. Corresponding REST API: POST /access/query-templates/{query-template-name}[?polymorphic={true|false}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:
      • Executes the specified query template with provided parameter values
      • Parameters are provided as a JSON string containing parameter substitutions
      • Returns query results as a JSON array string
      • Template variables are replaced with provided parameter values
      • Results are filtered based on user authorization and context access.
      Query Parameters: HTTP Response Codes:
      • 200 OK: Query template successfully executed
      • 404 Not Found: Query template with the specified name does not exist
      • 400 Bad Request: Invalid query execution, parameter values, or parameter format
      • 403 Forbidden: Insufficient permissions to execute the query template
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • Template name must be a valid query template name
      • Template names are case-sensitive and must match exactly
      • Parameters must be provided as valid JSON string containing parameter values for substitution.
      Context Access:
      • Query execution respects context boundaries based on user authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies.
      Authorization Requirements:
      • IS-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Execute with string parameters
 String params = "{\"state\":\"ready\",\"namePattern\":\"%Service%\"}";
 String resultsJson = client.runQueryTemplate("GetAllEServiceWithState", params);
      Parameters:
      name - The name of the query template to execute
      params - JSON string containing parameter values for template substitution
      Returns:
      JSON array string containing query results
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template execution

    • runQueryTemplate

      String runQueryTemplate(String name, org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a query template with JsonNode parameters and returns results as JSON string. Corresponding REST API: POST /access/query-templates/{query-template-name}[?polymorphic={true|false}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:
      • Executes the specified query template with provided parameter values
      • Parameters are provided as a JsonNode object containing parameter substitutions
      • Returns query results as a JSON array string
      • Template variables are replaced with provided parameter values
      • Results are filtered based on user authorization and context access.
      Query Parameters: HTTP Response Codes:
      • 200 OK: Query template successfully executed
      • 404 Not Found: Query template with the specified name does not exist
      • 400 Bad Request: Invalid query execution, parameter values, or parameter format
      • 403 Forbidden: Insufficient permissions to execute the query template
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • Template name must be a valid query template name
      • Template names are case-sensitive and must match exactly
      • Parameters must be provided as valid JsonNode containing parameter values for substitution.
      Context Access:
      • Query execution respects context boundaries based on user authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies.
      Authorization Requirements:
      • IS-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Execute with JsonNode parameters
 ObjectMapper mapper = new ObjectMapper();
 JsonNode params = mapper.createObjectNode()
     .put("state", "ready")
     .put("namePattern", "%Service%");
 String resultsJson = client.runQueryTemplate("GetAllEServiceWithState", params);
      Parameters:
      name - The name of the query template to execute
      jsonNode - JsonNode containing parameter values for template substitution
      Returns:
      JSON array string containing query results
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template execution

    • runQueryTemplate

      String runQueryTemplate(org.gcube.informationsystem.queries.templates.reference.entities.QueryTemplate queryTemplate, org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a query template using template object with JsonNode parameters and returns results as JSON string. Corresponding REST API: POST /access/query-templates/{query-template-name}[?polymorphic={true|false}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:
      • Executes the query template with provided parameter values
      • The template name is extracted from the provided QueryTemplate object
      • Parameters are provided as a JsonNode object containing parameter substitutions
      • Returns query results as a JSON array string
      • Template variables are replaced with provided parameter values
      • Results are filtered based on user authorization and context access.
      Query Parameters: HTTP Response Codes:
      • 200 OK: Query template successfully executed
      • 404 Not Found: Query template with the specified name does not exist
      • 400 Bad Request: Invalid query execution, parameter values, or parameter format
      • 403 Forbidden: Insufficient permissions to execute the query template
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • The query template name is automatically extracted from the provided QueryTemplate object
      • Parameter values from JsonNode are used for template variable substitution
      • All template parameters must be provided in the JsonNode or have default values.
      Context Access:
      • Query execution respects context boundaries based on user authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies.
      Authorization Requirements:
      • IS-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute any query template with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Execute using template object with JsonNode parameters
 QueryTemplate template = new QueryTemplate();
 template.setName("GetAllEServiceWithState");
 
 ObjectMapper mapper = new ObjectMapper();
 JsonNode params = mapper.createObjectNode()
     .put("state", "ready")
     .put("namePattern", "%Service%");
 
 String resultsJson = client.runQueryTemplate(template, params);
      Parameters:
      queryTemplate - The query template to execute (name is extracted from this object)
      jsonNode - JsonNode containing parameter values for template substitution
      Returns:
      JSON array string containing query results
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException - If the query template with the specified name does not exist
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query template execution

    • getResourcesFromReferenceFacet

      <R extends org.gcube.informationsystem.model.reference.entities.Resource, C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<?, ?>, F extends org.gcube.informationsystem.model.reference.entities.Facet> List<R> getResourcesFromReferenceFacet(Class<R> resourceClass, Class<C> consistsOfClass, F referenceFacet, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets resources connected to a specific facet instance through a ConsistsOf relation (typed version). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_reference={reference-uuid}&_polymorphic={true|false}&_direction={out|in}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources connected to the specified facet instance through the specified relation
      • Returns strongly-typed resource objects filtered based on user authorization
      • Supports polymorphic queries to include subtypes and sophisticated filtering options
      • Results are filtered based on context access and user permissions.
      Query Parameters: _direction (automatically set to "out"):
      • Direction of relation traversal from resource perspective
      • Fixed value: "out" (outgoing relations from resource to facet)
      • Represents: Resources having outgoing ConsistsOf relations to the specified facet
      • Query parameter: AccessPath._DIRECTION_QUERY_PARAMETER.
      limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, facet type, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and facet classes are automatically converted to type names
      • The reference facet UUID is extracted from the provided facet instance
      • Polymorphic parameter controls whether subtypes are included in results.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices identified by a specific SoftwareFacet
 SoftwareFacet softwareFacet = // ... obtained from somewhere
 List<EService> services = client.getResourcesFromReferenceFacet(
     EService.class, IsIdentifiedBy.class, softwareFacet, true);
      Type Parameters:
      R - The specific Resource type to retrieve
      C - The specific ConsistsOf relation type connecting resources to facets
      F - The specific Facet type used as reference
      Parameters:
      resourceClass - The class of resources to retrieve
      consistsOfClass - The class of the relation connecting resources to facets
      referenceFacet - The specific facet instance to use as reference. The UUID of this facet is automatically set in the _reference query parameter of the REST API call.
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      Returns:
      List of resources connected to the specified facet instance
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • getResourcesFromReferenceFacet

      <R extends org.gcube.informationsystem.model.reference.entities.Resource, C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<?, ?>, F extends org.gcube.informationsystem.model.reference.entities.Facet> List<R> getResourcesFromReferenceFacet(Class<R> resourceClass, Class<C> consistsOfClass, Class<F> facetClass, UUID referenceFacetUUID, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets resources connected to a facet of specific type and UUID through a ConsistsOf relation (typed version). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_reference={reference-uuid}&_polymorphic={true|false}&_direction={out|in}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources connected to a facet of the specified type and UUID through the specified relation
      • Returns strongly-typed resource objects filtered based on user authorization
      • Supports polymorphic queries to include subtypes and sophisticated filtering options
      • Results are filtered based on context access and user permissions.
      Query Parameters: _direction (automatically set to "out"):
      • Direction of relation traversal from resource perspective
      • Fixed value: "out" (outgoing relations from resource to facet)
      • Represents: Resources having outgoing ConsistsOf relations to the specified facet
      • Query parameter: AccessPath._DIRECTION_QUERY_PARAMETER.
      limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, facet type, UUID format, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and facet classes are automatically converted to type names
      • The reference facet UUID must be a valid UUID format
      • Polymorphic parameter controls whether subtypes are included in results.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices identified by a SoftwareFacet with specific UUID
 UUID softwareFacetUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 List<EService> services = client.getResourcesFromReferenceFacet(
     EService.class, IsIdentifiedBy.class, SoftwareFacet.class, softwareFacetUUID, true);
      Type Parameters:
      R - The specific Resource type to retrieve
      C - The specific ConsistsOf relation type connecting resources to facets
      F - The specific Facet type used as reference
      Parameters:
      resourceClass - The class of resources to retrieve
      consistsOfClass - The class of the relation connecting resources to facets
      facetClass - The class of facets used as reference
      referenceFacetUUID - The UUID of the specific facet instance to use as reference. This value is automatically set in the _reference query parameter of the REST API call.
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      Returns:
      List of resources connected to the specified facet instance
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • getResourcesFromReferenceFacet

      String getResourcesFromReferenceFacet(String resourceType, String consistsOfType, String facetType, UUID referenceFacetUUID, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets resources connected to a facet of specific type and UUID through a ConsistsOf relation (string version). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_reference={reference-uuid}&_polymorphic={true|false}&_direction={out|in}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources connected to a facet of the specified type and UUID through the specified relation
      • Returns JSON string representation of resources filtered based on user authorization
      • Supports polymorphic queries to include subtypes and sophisticated filtering options
      • Results are filtered based on context access and user permissions.
      Query Parameters: _direction (automatically set to "out"):
      • Direction of relation traversal from resource perspective
      • Fixed value: "out" (outgoing relations from resource to facet)
      • Represents: Resources having outgoing ConsistsOf relations to the specified facet
      • Query parameter: AccessPath._DIRECTION_QUERY_PARAMETER.
      limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, facet type, UUID format, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and facet type names must be valid Information System model types
      • The reference facet UUID must be a valid UUID format
      • Polymorphic parameter controls whether subtypes are included in results.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices identified by a SoftwareFacet with specific UUID
 UUID softwareFacetUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 String servicesJson = client.getResourcesFromReferenceFacet(
     "EService", "IsIdentifiedBy", "SoftwareFacet", softwareFacetUUID, true);
      Parameters:
      resourceType - The name of the resource type to retrieve
      consistsOfType - The name of the relation type connecting resources to facets
      facetType - The name of the facet type used as reference
      referenceFacetUUID - The UUID of the specific facet instance to use as reference. This value is automatically set in the _reference query parameter of the REST API call.
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      Returns:
      JSON string representation of resources connected to the specified facet instance
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • getFilteredResources

      <R extends org.gcube.informationsystem.model.reference.entities.Resource, C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<?, ?>, F extends org.gcube.informationsystem.model.reference.entities.Facet> List<R> getFilteredResources(Class<R> resourceClass, Class<C> consistsOfClass, Class<F> facetClass, boolean polymorphic, Map<String,String> facetConstraint) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets filtered resources based on facet constraints and relations (typed version). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_polymorphic={true|false}&_direction={out|in}&{constraint-key}={constraint-value}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources connected to facets of the specified type that match the given constraints
      • Applies property-based filtering on connected facets through specified relations
      • Returns strongly-typed resource objects filtered based on user authorization
      • Supports polymorphic queries to include subtypes and sophisticated filtering options.
      Query Parameters: _direction (automatically set to "out"):
      • Direction of relation traversal from resource perspective
      • Fixed value: "out" (outgoing relations from resource to facet)
      • Represents: Resources having outgoing ConsistsOf relations to facets matching constraints
      • Query parameter: AccessPath._DIRECTION_QUERY_PARAMETER.
      Constraint parameters (automatically configured from facetConstraint map):
      • Each key-value pair in facetConstraint becomes a query parameter
      • Used to filter facets by their property values
      • Example: facetConstraint.put("name", "data-transfer-service") becomes ?name=data-transfer-service
      • Only resources connected to facets matching ALL constraint criteria are returned.
      limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, facet type, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and facet classes are automatically converted to type names
      • Constraint map is converted to query parameters for facet property filtering
      • Polymorphic parameter controls whether subtypes are included in results.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices identified by SoftwareFacets with specific name and group
 Map<String, String> constraints = new HashMap<>();
 constraints.put("name", "data-transfer-service");
 constraints.put("group", "DataTransfer");
 List<EService> services = client.getFilteredResources(
     EService.class, IsIdentifiedBy.class, SoftwareFacet.class, true, constraints);
      Type Parameters:
      R - The specific Resource type to retrieve
      C - The specific ConsistsOf relation type connecting resources to facets
      F - The specific Facet type used for filtering
      Parameters:
      resourceClass - The class of resources to retrieve
      consistsOfClass - The class of the relation connecting resources to facets
      facetClass - The class of facets used for filtering
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      facetConstraint - Map of property name-value pairs to filter facets
      Returns:
      List of resources connected to facets matching the specified constraints
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • getFilteredResources

      String getFilteredResources(String resourceType, String consistsOfType, String facetType, boolean polymorphic, Map<String,String> facetConstraint) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets filtered resources based on facet constraints and relations (string version). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_polymorphic={true|false}&_direction={out|in}&{constraint-key}={constraint-value}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources connected to facets of the specified type that match the given constraints
      • Applies property-based filtering on connected facets through specified relations
      • Returns JSON string representation of resources filtered based on user authorization
      • Supports polymorphic queries to include subtypes and sophisticated filtering options.
      Query Parameters: _direction (automatically set to "out"):
      • Direction of relation traversal from resource perspective
      • Fixed value: "out" (outgoing relations from resource to facet)
      • Represents: Resources having outgoing ConsistsOf relations to facets matching constraints
      • Query parameter: AccessPath._DIRECTION_QUERY_PARAMETER.
      Constraint parameters (automatically configured from facetConstraint map):
      • Each key-value pair in facetConstraint becomes a query parameter
      • Used to filter facets by their property values
      • Example: facetConstraint.put("name", "data-transfer-service") becomes ?name=data-transfer-service
      • Only resources connected to facets matching ALL constraint criteria are returned.
      limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, facet type, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and facet type names must be valid Information System model types
      • Constraint map is converted to query parameters for facet property filtering
      • Polymorphic parameter controls whether subtypes are included in results.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices identified by SoftwareFacets with specific name and group
 Map<String, String> constraints = new HashMap<>();
 constraints.put("name", "data-transfer-service");
 constraints.put("group", "DataTransfer");
 String servicesJson = client.getFilteredResources(
     "EService", "IsIdentifiedBy", "SoftwareFacet", true, constraints);
      Parameters:
      resourceType - The name of the resource type to retrieve
      consistsOfType - The name of the relation type connecting resources to facets
      facetType - The name of the facet type used for filtering
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      facetConstraint - Map of property name-value pairs to filter facets
      Returns:
      JSON string representation of resources connected to facets matching the specified constraints
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • getRelatedResourcesFromReferenceResource

      <R extends org.gcube.informationsystem.model.reference.entities.Resource, I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<?, ?>, RR extends org.gcube.informationsystem.model.reference.entities.Resource> List<R> getRelatedResourcesFromReferenceResource(Class<R> resourceClass, Class<I> isRelatedToClass, RR referenceResource, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets resources related to a specific reference resource through an IsRelatedTo relation (typed version with instance). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_reference={reference-uuid}&_polymorphic={true|false}&_direction={out|in}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources related to the specified reference resource through the specified IsRelatedTo relation
      • Returns strongly-typed resource objects filtered based on user authorization
      • Supports polymorphic queries to include subtypes and directional relationship traversal
      • Results are filtered based on context access and user permissions.
      Query Parameters: limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, reference resource type, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and reference resource classes are automatically converted to type names
      • The reference resource UUID is extracted from the provided reference resource instance
      • Direction parameter controls the traversal direction of the IsRelatedTo relation.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices hosted by a specific HostingNode (incoming relation)
 HostingNode hostingNode = // ... obtained from somewhere
 List<EService> hostedServices = client.getRelatedResourcesFromReferenceResource(
     EService.class, Hosts.class, hostingNode, Direction.IN, true);
 
 // Find all HostingNodes that host a specific EService (outgoing relation)
 EService eservice = // ... obtained from somewhere
 List<HostingNode> hostingNodes = client.getRelatedResourcesFromReferenceResource(
     HostingNode.class, Hosts.class, eservice, Direction.OUT, true);
      Type Parameters:
      R - The specific Resource type to retrieve
      I - The specific IsRelatedTo relation type connecting resources
      RR - The specific reference Resource type
      Parameters:
      resourceClass - The class of resources to retrieve
      isRelatedToClass - The class of the IsRelatedTo relation connecting resources
      referenceResource - The specific reference resource instance. The UUID of this resource is automatically set in the _reference query parameter of the REST API call.
      direction - The direction of relation traversal (OUT or IN). Values: OUT finds resources that the reference resource relates to; IN finds resources that relate to the reference resource. This parameter is automatically set in the _direction query parameter of the REST API call.
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      Returns:
      List of resources related to the specified reference resource
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • getRelatedResourcesFromReferenceResource

      <R extends org.gcube.informationsystem.model.reference.entities.Resource, I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<?, ?>, RR extends org.gcube.informationsystem.model.reference.entities.Resource> List<R> getRelatedResourcesFromReferenceResource(Class<R> resourceClass, Class<I> isRelatedToClass, Class<RR> referenceResourceClass, UUID referenceResourceUUID, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets resources related to a specific reference resource through an IsRelatedTo relation (typed version with UUID). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_reference={reference-uuid}&_polymorphic={true|false}&_direction={out|in}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources related to a reference resource with the specified UUID through the specified IsRelatedTo relation
      • Returns strongly-typed resource objects filtered based on user authorization
      • Supports polymorphic queries to include subtypes and directional relationship traversal
      • Results are filtered based on context access and user permissions.
      Query Parameters: limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, reference resource type, UUID format, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and reference resource classes are automatically converted to type names
      • The reference resource UUID must be a valid UUID format
      • Direction parameter controls the traversal direction of the IsRelatedTo relation.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices hosted by a HostingNode with specific UUID (incoming relation)
 UUID hostingNodeUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 List<EService> hostedServices = client.getRelatedResourcesFromReferenceResource(
     EService.class, Hosts.class, HostingNode.class, hostingNodeUUID, Direction.IN, true);
      Type Parameters:
      R - The specific Resource type to retrieve
      I - The specific IsRelatedTo relation type connecting resources
      RR - The specific reference Resource type
      Parameters:
      resourceClass - The class of resources to retrieve
      isRelatedToClass - The class of the IsRelatedTo relation connecting resources
      referenceResourceClass - The class of the reference resource
      referenceResourceUUID - The UUID of the specific reference resource instance. This value is automatically set in the _reference query parameter of the REST API call.
      direction - The direction of relation traversal (OUT or IN). Values: OUT finds resources that the reference resource relates to; IN finds resources that relate to the reference resource. This parameter is automatically set in the _direction query parameter of the REST API call.
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      Returns:
      List of resources related to the specified reference resource
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • getRelatedResourcesFromReferenceResource

      String getRelatedResourcesFromReferenceResource(String resourceType, String isRelatedToType, String referenceResourceType, UUID referenceResourceUUID, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets resources related to a specific reference resource through an IsRelatedTo relation (string version). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_reference={reference-uuid}&_polymorphic={true|false}&_direction={out|in}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources related to a reference resource with the specified UUID through the specified IsRelatedTo relation
      • Returns JSON string representation of resources filtered based on user authorization
      • Supports polymorphic queries to include subtypes and directional relationship traversal
      • Results are filtered based on context access and user permissions.
      Query Parameters: limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, reference resource type, UUID format, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and reference resource type names must be valid Information System model types
      • The reference resource UUID must be a valid UUID format
      • Direction parameter controls the traversal direction of the IsRelatedTo relation.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices hosted by a HostingNode with specific UUID (incoming relation)
 UUID hostingNodeUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 String hostedServicesJson = client.getRelatedResourcesFromReferenceResource(
     "EService", "Hosts", "HostingNode", hostingNodeUUID, Direction.IN, true);
      Parameters:
      resourceType - The name of the resource type to retrieve
      isRelatedToType - The name of the IsRelatedTo relation type connecting resources
      referenceResourceType - The name of the reference resource type
      referenceResourceUUID - The UUID of the specific reference resource instance. This value is automatically set in the _reference query parameter of the REST API call.
      direction - The direction of relation traversal (OUT or IN). Values: OUT finds resources that the reference resource relates to; IN finds resources that relate to the reference resource. This parameter is automatically set in the _direction query parameter of the REST API call.
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      Returns:
      JSON string representation of resources related to the specified reference resource
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • getRelatedResources

      <R extends org.gcube.informationsystem.model.reference.entities.Resource, I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<?, ?>, RR extends org.gcube.informationsystem.model.reference.entities.Resource> List<R> getRelatedResources(Class<R> resourceClass, Class<I> isRelatedToClass, Class<RR> referenceResourceClass, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets all resources related to any resource of a specific type through an IsRelatedTo relation (typed version). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_polymorphic={true|false}&_direction={out|in}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources related to any resource of the specified reference type through the specified IsRelatedTo relation
      • Returns strongly-typed resource objects filtered based on user authorization
      • Supports polymorphic queries to include subtypes and directional relationship traversal
      • Does not filter by specific reference resource instance (returns all related resources).
      Query Parameters: _reference (not used):
      • No specific reference resource UUID is specified
      • Returns resources related to ANY resource of the specified reference type.
      limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, reference resource type, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and reference resource classes are automatically converted to type names
      • Direction parameter controls the traversal direction of the IsRelatedTo relation
      • Polymorphic parameter controls whether subtypes are included in results.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices hosted by any HostingNode (incoming relation)
 List<EService> allHostedServices = client.getRelatedResources(
     EService.class, Hosts.class, HostingNode.class, Direction.IN, true);
 
 // Find all HostingNodes that host any EService (outgoing relation)
 List<HostingNode> allHostingNodes = client.getRelatedResources(
     HostingNode.class, Hosts.class, EService.class, Direction.OUT, true);
      Type Parameters:
      R - The specific Resource type to retrieve
      I - The specific IsRelatedTo relation type connecting resources
      RR - The specific reference Resource type
      Parameters:
      resourceClass - The class of resources to retrieve
      isRelatedToClass - The class of the IsRelatedTo relation connecting resources
      referenceResourceClass - The class of the reference resource type
      direction - The direction of relation traversal (OUT or IN). Values: OUT finds resources that any reference resource relates to; IN finds resources that relate to any reference resource. This parameter is automatically set in the _direction query parameter of the REST API call.
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      Returns:
      List of resources related to any resource of the specified reference type
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • getRelatedResources

      String getRelatedResources(String resourceType, String isRelatedToType, String referenceResourceType, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets all resources related to any resource of a specific type through an IsRelatedTo relation (string version). Corresponding REST API: GET /access/query/{resource-type-name}/{relation-type-name}/{reference-type-name}[?_polymorphic={true|false}&_direction={out|in}&limit={number}&offset={number}&includeMeta={true|false}&allMeta={true|false}&hierarchical={true|false}&includeContexts={true|false}] Operation Behavior:
      • Retrieves all resources related to any resource of the specified reference type through the specified IsRelatedTo relation
      • Returns JSON string representation of resources filtered based on user authorization
      • Supports polymorphic queries to include subtypes and directional relationship traversal
      • Does not filter by specific reference resource instance (returns all related resources).
      Query Parameters: _reference (not used):
      • No specific reference resource UUID is specified
      • Returns resources related to ANY resource of the specified reference type.
      limit (configurable via client configuration):
      • Maximum number of resources to return in a single response
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 resources per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of resources to skip from the beginning of the result set
      • Default value: 0
      • Usage: client.setOffset(10)
      • Example: Set to 10 to skip the first 10 resources (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      includeMeta (configurable via client configuration):
      • Whether to include metadata in the response resources
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata including sensitive information (createdBy, lastUpdatedBy); other users see filtered metadata with sensitive fields obfuscated.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested elements (ConsistsOf relations, Facets, etc.) in the response
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main resources, more human-readable)
      • Usage: client.setAllMeta(true)
      • Values: true (complete metadata) | false (main resources only, more readable)
      • Purpose: When false, produces more human-readable responses with less JSON to process
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where the resources and their nested elements are available in the response
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER
      • Note: A Resource is present in all contexts that form the union of contexts of all its Facets
      • Note: ConsistsOf relations are present in all contexts where their target Facets are present
      • Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations.
      hierarchical (configurable via client configuration, admin-only):
      • Whether to include resources from child contexts of the current context
      • Default value: false (child contexts not included)
      • Usage: client.setHierarchicalMode(true)
      • Values: true (includes child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles.
      HTTP Response Codes:
      • 200 OK: Resources successfully retrieved
      • 400 Bad Request: Invalid resource type, relation type, reference resource type, or query parameters
      • 403 Forbidden: Insufficient permissions to execute prepared queries or access hierarchical data
      • 404 Not Found: Specified types do not exist in the model.
      Input Processing:
      • Resource, relation, and reference resource type names must be valid Information System model types
      • Direction parameter controls the traversal direction of the IsRelatedTo relation
      • Polymorphic parameter controls whether subtypes are included in results.
      Context Access:
      • Resources are returned from the current context based on authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results respect context boundaries and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute prepared queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Find all EServices hosted by any HostingNode (incoming relation)
 String allHostedServicesJson = client.getRelatedResources(
     "EService", "Hosts", "HostingNode", Direction.IN, true);
      Parameters:
      resourceType - The name of the resource type to retrieve
      isRelatedToType - The name of the IsRelatedTo relation type connecting resources
      referenceResourceType - The name of the reference resource type
      direction - The direction of relation traversal (OUT or IN). Values: OUT finds resources that any reference resource relates to; IN finds resources that relate to any reference resource. This parameter is automatically set in the _direction query parameter of the REST API call.
      polymorphic - Whether to include subtypes in the results. When true, includes all subtypes of the specified type; when false, returns only instances of the exact specified type. This parameter is automatically set in the _polymorphic query parameter of the REST API call.
      Returns:
      JSON string representation of resources related to any resource of the specified reference type
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • jsonQuery

      String jsonQuery(String query) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a JSON-based query to find instances matching the specified structure in the Resource Registry. Corresponding REST API: POST /access/query[?polymorphic={true|false}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}&limit={number}&offset={number}] Operation Behavior:
      • Executes a JSON-based structural query to find instances matching the specified criteria
      • Returns JSON string representation of matching instances
      • Supports complex queries including relations, properties, and nested structures
      • Results are filtered based on user authorization and context access.
      Query Parameters: includeMeta (configurable via client configuration):
      • Whether to include metadata in the response instances
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata; other users see filtered metadata.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested instances
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instances)
      • Usage: client.setAllMeta(true)
      • Values: true (includes metadata for all nested elements) | false (metadata only for main instances)
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where each instance is available
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability for each instance) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER.
      hierarchical (configurable via client configuration):
      • Whether to include instances from child contexts of the current context
      • Default value: false (current context only)
      • Usage: client.setHierarchicalMode(true)
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles
      • Values: true (includes instances from current and child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER.
      limit (configurable via client configuration):
      • Maximum number of instances to return
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 instances per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of instances to skip from the beginning of the result set
      • Default value: 0 (starts from the first instance)
      • Usage: client.setOffset(100)
      • Example: Set to 100 to skip the first 100 instances (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      HTTP Response Codes:
      • 200 OK: JSON query successfully executed
      • 400 Bad Request: Invalid query structure, syntax errors, or invalid parameters
      • 403 Forbidden: Insufficient permissions to execute JSON queries or access hierarchical data
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • Query must be a valid JSON string describing the structure to search for
      • Must specify the target type and optionally its relations and properties
      • Relations can include ConsistsOf, IsRelatedTo, and other defined relation types
      • Properties can specify exact values or patterns to match.
      Context Access:
      • Query execution respects context boundaries based on user authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results are filtered based on current context and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute JSON queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute JSON queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Context-Manager: Access to execute JSON queries with hierarchical querying within managed contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // JSON query to find EServices with specific state and software
 String jsonQuery = """
     {
       "type": "EService",
       "consistsOf": [
         {
           "type": "ConsistsOf",
           "target": {
             "type": "StateFacet",
             "value": "down"
           }
         },
         {
           "type": "IsIdentifiedBy",
           "target": {
             "type": "SoftwareFacet",
             "name": "data-transfer-service"
           }
         }
       ]
     }
     """;
 
 String resultsJson = client.jsonQuery(jsonQuery);
      Parameters:
      query - JSON string describing the structure to search for
      Returns:
      JSON string containing query results
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - If the query structure is invalid or contains syntax errors
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • jsonQuery

      <E extends org.gcube.informationsystem.model.reference.entities.Entity> List<E> jsonQuery(org.gcube.com.fasterxml.jackson.databind.JsonNode jsonNode) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a JSON-based query to find instances matching the specified structure and returns typed results. Corresponding REST API: POST /access/query[?polymorphic={true|false}&includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}&limit={number}&offset={number}] Operation Behavior:
      • Executes a JSON-based structural query to find instances matching the specified criteria
      • Returns strongly-typed list of Entity objects automatically deserialized from JSON results
      • Supports complex queries including relations, properties, and nested structures
      • Results are filtered based on user authorization and context access.
      Query Parameters: includeMeta (configurable via client configuration):
      • Whether to include metadata in the response instances
      • Default value: false (basic information only)
      • Usage: client.setIncludeMeta(true)
      • Values: true (includes metadata with role-based filtering) | false (basic information only)
      • Query parameter: AccessPath.INCLUDE_META_QUERY_PARAMETER
      • Restriction: IS-Manager, Infrastructure-Manager, and Context-Manager see complete metadata; other users see filtered metadata.
      allMeta (configurable via client configuration):
      • Whether to include metadata for all nested instances
      • Must be used in conjunction with includeMeta=true
      • Default value: false (metadata only for main instances)
      • Usage: client.setAllMeta(true)
      • Values: true (includes metadata for all nested elements) | false (metadata only for main instances)
      • Query parameter: AccessPath.INCLUDE_META_IN_ALL_INSTANCES_QUERY_PARAMETER.
      includeContexts (configurable via client configuration):
      • Whether to include the list of contexts where each instance is available
      • Default value: false (context information not included)
      • Usage: client.setIncludeContexts(true)
      • Values: true (shows context availability for each instance) | false (no context information)
      • Query parameter: AccessPath.INCLUDE_CONTEXTS_QUERY_PARAMETER.
      hierarchical (configurable via client configuration):
      • Whether to include instances from child contexts of the current context
      • Default value: false (current context only)
      • Usage: client.setHierarchicalMode(true)
      • Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles
      • Values: true (includes instances from current and child contexts) | false (current context only)
      • Query parameter: AccessPath.HIERARCHICAL_MODE_QUERY_PARAMETER.
      limit (configurable via client configuration):
      • Maximum number of instances to return
      • Default value: server configuration dependent
      • Usage: client.setLimit(50)
      • Example: Set to 50 to get at most 50 instances per request
      • Unlimited results: Set to RequestInfo.UNBOUNDED_LIMIT (-1) for unlimited results (may cause timeout if results are too many)
      • Query parameter: AccessPath.LIMIT_QUERY_PARAMETER.
      offset (configurable via client configuration):
      • Number of instances to skip from the beginning of the result set
      • Default value: 0 (starts from the first instance)
      • Usage: client.setOffset(100)
      • Example: Set to 100 to skip the first 100 instances (useful for pagination)
      • Query parameter: AccessPath.OFFSET_QUERY_PARAMETER.
      HTTP Response Codes:
      • 200 OK: JSON query successfully executed
      • 400 Bad Request: Invalid query structure, syntax errors, or invalid parameters
      • 403 Forbidden: Insufficient permissions to execute JSON queries or access hierarchical data
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • JsonNode must represent a valid JSON structure describing the search criteria
      • Must specify the target type and optionally its relations and properties
      • Relations can include ConsistsOf, IsRelatedTo, and other defined relation types
      • Properties can specify exact values or patterns to match.
      Context Access:
      • Query execution respects context boundaries based on user authorization
      • Hierarchical mode can be enabled for administrative users to query across context hierarchies
      • Results are filtered based on current context and user access permissions.
      Authorization Requirements:
      • IS-Manager: Full access to execute JSON queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Infrastructure-Manager: Full access to execute JSON queries with hierarchical querying across all contexts; receives complete, unfiltered metadata
      • Context-Manager: Access to execute JSON queries with hierarchical querying within managed contexts; receives complete, unfiltered metadata
      • All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Create JsonNode query to find EServices with specific software
 ObjectMapper mapper = new ObjectMapper();
 JsonNode queryNode = mapper.createObjectNode()
     .put("type", "EService")
     .set("consistsOf", mapper.createArrayNode()
         .add(mapper.createObjectNode()
             .put("type", "IsIdentifiedBy")
             .set("target", mapper.createObjectNode()
                 .put("type", "SoftwareFacet")
                 .put("name", "data-transfer-service"))));
 
 List<EService> services = client.jsonQuery(queryNode);
      Type Parameters:
      E - The specific Entity type expected in results
      Parameters:
      jsonNode - JsonNode representing the query structure
      Returns:
      List of Entity instances matching the query criteria
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - If the query structure is invalid or contains syntax errors
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • rawQuery

      String rawQuery(String query) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a raw OrientDB SQL query against the Resource Registry backend. Corresponding REST API: GET /access/query[?q={query}&raw={false}] Operation Behavior:
      • Executes a direct OrientDB SQL query against the backend database
      • Returns results formatted according to the Information System model
      • Only idempotent queries (SELECT statements) are accepted for security
      • Results are filtered based on user authorization and context access.
      Query Parameters: q (automatically configured from query parameter):
      • The OrientDB SQL query to execute against the backend
      • Must be URL-encoded for special characters
      • Only idempotent queries are accepted (SELECT statements)
      • Example: "SELECT FROM EService WHERE out('ConsistsOf').@class = 'StateFacet'"
      • Query parameter: AccessPath.Q_QUERY_PARAMETER.
      raw (automatically set to false):
      • Whether to return the raw backend response or format it according to the Information System model
      • Fixed value: false (format results according to IS model)
      • Results are converted to standard Information System model format with proper typing and structure
      • Query parameter: AccessPath.RAW_QUERY_PARAMETER.
      HTTP Response Codes:
      • 200 OK: Graph query successfully executed
      • 400 Bad Request: Invalid query syntax or non-idempotent query attempted
      • 403 Forbidden: Insufficient permissions to execute graph queries (only IS-Manager and Infrastructure-Manager allowed)
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • Query must be a valid OrientDB SQL statement
      • Must be idempotent (SELECT-only operations)
      • Query is automatically URL-encoded before transmission
      • Only SELECT operations are allowed for security reasons.
      Context Access:
      • Query execution respects context boundaries based on user authorization
      • Results are filtered based on current context and user access permissions
      • Administrative users may have broader query capabilities.
      Authorization Requirements:
      • IS-Manager: Full access to execute raw queries with complete, unfiltered results
      • Infrastructure-Manager: Full access to execute raw queries with complete, unfiltered results
      • All Other Users: Limited or no access to raw query functionality (implementation dependent).
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Execute a raw OrientDB query to find EServices with StateFacets
 String query = "SELECT FROM EService WHERE out('ConsistsOf').@class = 'StateFacet'";
 String results = client.rawQuery(query);
      Parameters:
      query - The OrientDB SQL query to execute against the backend
      Returns:
      JSON string containing formatted query results according to Information System model
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - If the query is invalid, non-idempotent, or contains syntax errors
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution

    • rawQuery

      String rawQuery(String query, boolean raw) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Executes a raw OrientDB SQL query against the Resource Registry backend with configurable result formatting. Corresponding REST API: GET /access/query[?q={query}&raw={true|false}] Operation Behavior:
      • Executes a direct OrientDB SQL query against the backend database
      • Returns results either as raw OrientDB format or formatted according to the Information System model
      • Only idempotent queries (SELECT statements) are accepted for security
      • Results are filtered based on user authorization and context access.
      Query Parameters: q (automatically configured from query parameter):
      • The OrientDB SQL query to execute against the backend
      • Must be URL-encoded for special characters
      • Only idempotent queries are accepted (SELECT statements)
      • Example: "SELECT FROM EService WHERE out('ConsistsOf').@class = 'StateFacet'"
      • Query parameter: AccessPath.Q_QUERY_PARAMETER.
      raw (automatically configured from raw parameter):
      • Whether to return the raw backend response or format it according to the Information System model
      • Configured by method parameter value
      • Values: true (returns raw OrientDB response format) | false (format results according to IS model)
      • When false: Results are converted to standard Information System model format with proper typing and structure
      • When true: Results are returned exactly as provided by the OrientDB backend without any formatting or conversion
      • Query parameter: AccessPath.RAW_QUERY_PARAMETER.
      HTTP Response Codes:
      • 200 OK: Graph query successfully executed
      • 400 Bad Request: Invalid query syntax or non-idempotent query attempted
      • 403 Forbidden: Insufficient permissions to execute graph queries (only IS-Manager and Infrastructure-Manager allowed)
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • Query must be a valid OrientDB SQL statement
      • Must be idempotent (SELECT-only operations)
      • Query is automatically URL-encoded before transmission
      • Raw parameter controls result formatting.
      Context Access:
      • Query execution respects context boundaries based on user authorization
      • Results are filtered based on current context and user access permissions
      • Administrative users may have broader query capabilities and access to raw data.
      Authorization Requirements:
      • IS-Manager: Full access to execute raw queries with complete, unfiltered results; can request raw backend data
      • Infrastructure-Manager: Full access to execute raw queries with complete, unfiltered results; can request raw backend data
      • All Other Users: Limited or no access to raw query functionality (implementation dependent).
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Execute query with formatted results (IS model)
 String query = "SELECT FROM EService WHERE out('ConsistsOf').@class = 'StateFacet'";
 String formattedResults = client.rawQuery(query, false);
 
 // Execute query with raw OrientDB results
 String rawResults = client.rawQuery(query, true);
      Parameters:
      query - The OrientDB SQL query to execute against the backend
      raw - Whether to return raw backend response (true) or format according to IS model (false)
      Returns:
      JSON string containing query results (raw OrientDB format or IS model format)
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.InvalidQueryException - If the query is invalid, non-idempotent, or contains syntax errors
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during query execution