Package org.gcube.informationsystem.resourceregistry.client

Class ResourceRegistryClientImpl

java.lang.Object
org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo
org.gcube.informationsystem.resourceregistry.client.ResourceRegistryClientImpl
All Implemented Interfaces:
org.gcube.informationsystem.resourceregistry.api.request.RequestInfo, ResourceRegistryClient
public class ResourceRegistryClientImpl extends org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo implements ResourceRegistryClient
Author:
Luca Frosini (ISTI - CNR)

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final String
    address
    The base address of the Resource Registry service
    protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache
    contextCache
    Cache for context information
    protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCacheRenewal
    contextCacheRenewal
    Context cache renewal strategy that reads all contexts from the server
    protected Map<String,String>
    headers
    Additional HTTP headers to be included in requests
    protected org.gcube.informationsystem.types.knowledge.TypesKnowledge
    typesKnowledge
    Knowledge base for type information

    Fields inherited from class org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

    allMeta, hierarchicalMode, includeContexts, includeMeta, limit, offset

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

    DEFAULT_LIMIT, DEFAULT_OFFSET, UNBOUNDED_LIMIT

  • Constructor Summary

    Constructors
    Constructor
    Description
    ResourceRegistryClientImpl(String address)
    Creates a new ResourceRegistryClientImpl with default configuration.
    ResourceRegistryClientImpl(String address, boolean sharedContextCache, boolean sharedModelKnowledge)
    Creates a new ResourceRegistryClientImpl with configurable cache and knowledge sharing.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected List<org.gcube.informationsystem.types.reference.Type>
    addChildren(org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type> node, List<org.gcube.informationsystem.types.reference.Type> types, int currentLevel, int maxLevel)
    Recursively adds child types to a list based on type hierarchy.
    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.
    boolean
    existTypeFromServer(String typeName)
    Checks if a type exists by querying the server directly, bypassing the local knowledge cache.
    List<org.gcube.informationsystem.contexts.reference.entities.Context>
    getAllContextFromServer()
    Retrieves the list of all contexts in the system.
    protected List<org.gcube.informationsystem.contexts.reference.entities.Context>
    getAllContextFromServer(boolean includeMeta, Integer offset, Integer limit)
    It reads all the contexts from server with specific parameters.
    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.
    protected org.gcube.informationsystem.contexts.reference.entities.Context
    getContextFromServer(String uuid)
    It reads the context from server by UUID string.
    org.gcube.informationsystem.contexts.reference.entities.Context
    getContextFromServer(UUID uuid)
    It reads the context from server by UUID.
    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> facetConstraints)
    Gets filtered resources based on facet constraints and relations (typed version).
    String
    getFilteredResources(String resourceType, String consistsOfType, String facetType, boolean polymorphic, Map<String,String> facetConstraints)
    Gets filtered resources based on facet constraints and relations (string version).
    protected org.gcube.common.gxhttp.request.GXHTTPStringRequest
    getGXHTTPStringRequest()
    Creates and configures a new HTTP request with authorization headers and custom headers.
    <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.
    protected <E extends org.gcube.informationsystem.model.reference.entities.Entity, R extends org.gcube.informationsystem.model.reference.relations.Relation<?, ?>, RE extends org.gcube.informationsystem.model.reference.entities.Entity>
    List<E>
    getRelated(Class<E> entityClass, Class<R> relationClass, Class<RE> referenceEntityClass, UUID referenceEntityUUID, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic)
    Gets entities related to a specific reference entity through a specific relation using UUID.
    protected <E extends org.gcube.informationsystem.model.reference.entities.Entity, R extends org.gcube.informationsystem.model.reference.relations.Relation<?, ?>, RE extends org.gcube.informationsystem.model.reference.entities.Entity>
    List<E>
    getRelated(Class<E> entityClass, Class<R> relationClass, Class<RE> referenceEntityClass, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic, Map<String,String> map)
    Gets entities related through a specific relation with constraint-based filtering.
    protected <E extends org.gcube.informationsystem.model.reference.entities.Entity, R extends org.gcube.informationsystem.model.reference.relations.Relation<?, ?>, RE extends org.gcube.informationsystem.model.reference.entities.Entity>
    List<E>
    getRelated(Class<E> entityClass, Class<R> relationClass, Class<RE> referenceEntityClass, RE referenceEntity, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic)
    Gets entities related to a specific reference entity through a specific relation.
    protected String
    getRelated(String entityType, String relationType, String referenceEntityType, UUID referenceEntity, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic)
    Gets entities related to a specific reference entity through a specific relation (string-based with UUID).
    protected String
    getRelated(String entityType, String relationType, String referenceEntityType, UUID referenceEntity, org.gcube.informationsystem.base.reference.Direction direction, Boolean polymorphic, Map<String,String> facetConstraints)
    Gets entities related to a specific reference entity through a specific relation.
    protected String
    getRelated(String entityType, String relationType, String referenceEntityType, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic, Map<String,String> facetConstraints)
    Gets entities related through a specific relation with constraint-based filtering (string-based).
    <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 facetUUID, 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>
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromServer(Class<ME> clazz, Boolean polymorphic)
    Gets type information directly from the server, bypassing the local cache.
    String
    getTypeFromServer(String typeName, Boolean polymorphic)
    Gets type schema directly from the server as a JSON string.
    <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromTypesKnowledge(String typeName, int level)
    Gets type information from the local types knowledge cache with level limitation.
    <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromTypesKnowledge(String typeName, Boolean polymorphic)
    Gets type information from the local types knowledge cache.
    <ERElem extends org.gcube.informationsystem.model.reference.ERElement>
    List<org.gcube.informationsystem.types.reference.Type>
    getTypeFromTypesKnowledge(String typeName, Boolean polymorphic, int level)
    Gets type information from the local types knowledge cache with full configuration.
    <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 class org.gcube.informationsystem.resourceregistry.api.request.BaseRequestInfo

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

    Methods inherited from class java.lang.Object

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

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

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

  • Field Details

    • address

      protected final String address
      The base address of the Resource Registry service

    • headers

      protected Map<String,String> headers
      Additional HTTP headers to be included in requests

    • contextCache

      protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache contextCache
      Cache for context information

    • typesKnowledge

      protected org.gcube.informationsystem.types.knowledge.TypesKnowledge typesKnowledge
      Knowledge base for type information

    • contextCacheRenewal

      protected org.gcube.informationsystem.resourceregistry.api.contexts.ContextCacheRenewal contextCacheRenewal
      Context cache renewal strategy that reads all contexts from the server

  • Constructor Details

    • ResourceRegistryClientImpl

      public ResourceRegistryClientImpl(String address)
      Creates a new ResourceRegistryClientImpl with default configuration. Uses shared context cache and shared model knowledge.
      Parameters:
      address - the base address of the Resource Registry service

    • ResourceRegistryClientImpl

      public ResourceRegistryClientImpl(String address, boolean sharedContextCache, boolean sharedModelKnowledge)
      Creates a new ResourceRegistryClientImpl with configurable cache and knowledge sharing.
      Parameters:
      address - the base address of the Resource Registry service
      sharedContextCache - true to use shared context cache, false for dedicated cache
      sharedModelKnowledge - true to use shared model knowledge, false for dedicated knowledge

  • Method Details

    • addHeader

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

    • addHeader

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

    • getGXHTTPStringRequest

      protected org.gcube.common.gxhttp.request.GXHTTPStringRequest getGXHTTPStringRequest()
      Creates and configures a new HTTP request with authorization headers and custom headers.
      Returns:
      A configured GXHTTPStringRequest instance ready for use

    • getContextCache

      public 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();
      Specified by:
      getContextCache in interface ResourceRegistryClient
      Returns:
      The context cache instance

    • getAllContexts

      public 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() + ")");
 }
      Specified by:
      getAllContexts in interface ResourceRegistryClient
      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

    • getAllContextFromServer

      public List<org.gcube.informationsystem.contexts.reference.entities.Context> getAllContextFromServer() throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the list of all contexts in the system. Corresponding REST API: GET /access/contexts[?limit={limit}&offset={offset}&includeMeta={true|false}] Operation Behavior:
      • Returns all contexts that are accessible to the current user
      • Results are filtered based on user authorization and context access permissions
      • Supports pagination and metadata inclusion based on client configuration
      • Returns strongly-typed Context objects with role-appropriate detail level.
      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
      • 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.
      Input Processing:
      • No input parameters required for this method
      • All contexts accessible to the current user are returned based on authorization level
      • Context filtering is automatically applied based on user permissions.
      Context Access:
      • Results include only contexts that the current user has permission to access
      • IS-Manager and Infrastructure-Manager see all contexts in the system
      • Context-Manager sees contexts within their management scope
      • Other users see contexts they have explicit access to.
      Authorization Requirements:
      • All users must have a valid token and basic read permissions to list contexts they have access to.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Basic usage - get all contexts with default settings
 List<Context> contexts = client.getContexts();
 
 // With metadata for non-admin users
 client.setIncludeMeta(true);
 List<Context> contextsWithMeta = client.getContexts();
 
 // With pagination
 client.setLimit(20);
 client.setOffset(10);
 List<Context> paginatedContexts = client.getContexts();
      Returns:
      List of Context objects with role-appropriate detail level accessible to the current user
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval or if there are authorization issues

    • getAllContextFromServer

      protected List<org.gcube.informationsystem.contexts.reference.entities.Context> getAllContextFromServer(boolean includeMeta, Integer offset, Integer limit) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      It reads all the contexts from server with specific parameters. The cache used for contexts is bypassed and not updated.
      Parameters:
      includeMeta - whether to include metadata in the response
      offset - the starting position for pagination
      limit - the maximum number of contexts to return
      Returns:
      All Contexts read from server
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the retrieval

    • getModelKnowledge

      public org.gcube.informationsystem.model.knowledge.ModelKnowledge<org.gcube.informationsystem.types.reference.Type,org.gcube.informationsystem.types.knowledge.TypeInformation> getModelKnowledge()
      Retrieves the complete model knowledge containing type definitions and their information. The model knowledge provides access to all registered types and their hierarchical relationships. 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: 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);
      Specified by:
      getModelKnowledge in interface ResourceRegistryClient
      Returns:
      the model knowledge containing type definitions and information

    • renewModelKnowledge

      public void renewModelKnowledge()
      Forces a renewal of the cached model knowledge by fetching the latest version from the Resource Registry. This method should be called when the schema has been modified and the local cache needs to be updated. 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: 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();
      Specified by:
      renewModelKnowledge in interface ResourceRegistryClient

    • getContextFromServer

      public org.gcube.informationsystem.contexts.reference.entities.Context getContextFromServer(UUID uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      It reads the context from server by UUID. The cache used for contexts is bypassed and not updated. Corresponding REST API: GET /access/contexts/{context-uuid}[?includeMeta={true|false}] Operation Behavior:
      • Retrieves the context with the specified UUID from the system
      • Returns the complete context object with all accessible properties
      • Direct UUID-based context retrieval without additional processing.
      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.
      Input Processing:
      • Accepts a properly formatted UUID object
      • No additional processing or conversion required
      • Direct UUID-based context retrieval.
      Context Access:
      • The context must be accessible to the current user based on authorization level
      • IS-Manager and Infrastructure-Manager can retrieve any context without restrictions
      • Context-Manager can retrieve contexts within their management scope
      • Other users can retrieve contexts they have explicit access to.
      Authorization Requirements:
      • All users must have a valid token and read permissions for the specific context to retrieve it.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 UUID contextUuid = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 
 // Basic usage - read context
 Context context = client.getContext(contextUuid);
 System.out.println("Context name: " + context.getName());
 
 // With metadata for non-admin users
 client.setIncludeMeta(true);
 Context contextWithMeta = client.getContext(contextUuid);
      Parameters:
      uuid - the UUID of the context to retrieve
      Returns:
      the Contexts read from server
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the retrieval

    • getContextFromServer

      protected org.gcube.informationsystem.contexts.reference.entities.Context getContextFromServer(String uuid) throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      It reads the context from server by UUID string. The cache used for contexts is bypassed and not updated. Corresponding REST API: GET /access/contexts/{context-uuid}[?includeMeta={true|false}] Operation Behavior:
      • Retrieves the context with the specified UUID from the system
      • Returns the complete context object with all accessible properties
      • Direct UUID-based context retrieval without additional processing.
      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.
      Input Processing:
      • Accepts a properly formatted UUID object
      • No additional processing or conversion required
      • Direct UUID-based context retrieval.
      Context Access:
      • The context must be accessible to the current user based on authorization level
      • IS-Manager and Infrastructure-Manager can retrieve any context without restrictions
      • Context-Manager can retrieve contexts within their management scope
      • Other users can retrieve contexts they have explicit access to.
      Authorization Requirements:
      • All users must have a valid token and read permissions for the specific context to retrieve it.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 UUID contextUuid = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 
 // Basic usage - read context
 Context context = client.getContext(contextUuid);
 System.out.println("Context name: " + context.getName());
 
 // With metadata for non-admin users
 client.setIncludeMeta(true);
 Context contextWithMeta = client.getContext(contextUuid);
      Parameters:
      uuid - the UUID string of the context to retrieve
      Returns:
      the Context read from server
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - if the context is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the retrieval

    • existContext

      public boolean existContext(String uuid) throws 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");
 }
      Specified by:
      existContext in interface ResourceRegistryClient
      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

    • existContext

      public boolean existContext(UUID uuid) throws 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");
 }
      Specified by:
      existContext in interface ResourceRegistryClient
      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

      public 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());
      Specified by:
      getContext in interface ResourceRegistryClient
      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

    • getContext

      public 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());
      Specified by:
      getContext in interface ResourceRegistryClient
      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

      public 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());
      Specified by:
      getCurrentContext in interface ResourceRegistryClient
      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

    • existType

      public <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.
      Specified by:
      existType in interface ResourceRegistryClient
      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

    • existType

      public 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.
      Specified by:
      existType in interface ResourceRegistryClient
      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

    • existTypeFromServer

      public boolean existTypeFromServer(String typeName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Checks if a type exists by querying the server directly, bypassing the local knowledge cache. Corresponding REST API: HEAD /access/types/{type-name}[?polymorphic={true|false}&includeMeta={true|false}] Operation Behavior:
      • Verifies the existence of the specified type definition using its name
      • Does not return the type data, only confirms existence
      • Checks accessibility within the current user authorization level
      • Most direct method when type name is already known.
      HTTP Response Codes:
      • 200 OK: Type exists and is accessible
      • 404 Not Found: Type does not exist in the system
      • 403 Forbidden: User lacks authorization to access type information
      • 401 Unauthorized: Invalid or missing authentication credentials.
      Input Processing:
      • Type name must be a valid Information System model type
      • Supports all Information System model types and their subtypes: Entities (Resources and all Resource subtypes, Facets and all Facet subtypes) and Relations (ConsistsOf and all ConsistsOf subtypes, IsRelatedTo and all IsRelatedTo subtypes)
      • Type name is case-sensitive and must match exactly.
      Authorization Requirements:
      • IS-Manager: Can check existence of any type definition
      • Infrastructure-Manager: Can check existence of any type definition
      • All Other Users: Can check existence of any type definition with filtered access to sensitive metadata.
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Check if ContactFacet type exists
 boolean contactFacetExists = client.existType("ContactFacet");
 
 // Check if a custom resource type exists
 boolean customResourceExists = client.existType("MyCustomResource");
      Parameters:
      typeName - the name of the type to check
      Returns:
      true if the type exists on the server, false otherwise
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the check

    • getTypeFromTypesKnowledge

      public <ERElem extends org.gcube.informationsystem.model.reference.ERElement> List<org.gcube.informationsystem.types.reference.Type> getTypeFromTypesKnowledge(String typeName, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets type information from the local types knowledge cache.
      Type Parameters:
      ERElem - the type parameter extending ERElement
      Parameters:
      typeName - the name of the type to retrieve
      polymorphic - whether to include polymorphic types
      Returns:
      a list of Type objects
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type schema is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getTypeFromTypesKnowledge

      public <ERElem extends org.gcube.informationsystem.model.reference.ERElement> List<org.gcube.informationsystem.types.reference.Type> getTypeFromTypesKnowledge(String typeName, int level) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets type information from the local types knowledge cache with level limitation.
      Type Parameters:
      ERElem - the type parameter extending ERElement
      Parameters:
      typeName - the name of the type to retrieve
      level - the depth level for type hierarchy traversal
      Returns:
      a list of Type objects
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type schema is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • addChildren

      protected List<org.gcube.informationsystem.types.reference.Type> addChildren(org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type> node, List<org.gcube.informationsystem.types.reference.Type> types, int currentLevel, int maxLevel)
      Recursively adds child types to a list based on type hierarchy.
      Parameters:
      node - the current node in the type hierarchy
      types - the list to add types to
      currentLevel - the current depth level
      maxLevel - the maximum depth level to traverse (-1 for unlimited)
      Returns:
      the updated list of types

    • getTypeFromTypesKnowledge

      public <ERElem extends org.gcube.informationsystem.model.reference.ERElement> List<org.gcube.informationsystem.types.reference.Type> getTypeFromTypesKnowledge(String typeName, Boolean polymorphic, int level) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets type information from the local types knowledge cache with full configuration.
      Type Parameters:
      ERElem - the type parameter extending ERElement
      Parameters:
      typeName - the name of the type to retrieve
      polymorphic - whether to include polymorphic types
      level - the depth level for type hierarchy traversal (-1 for unlimited)
      Returns:
      a list of Type objects
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type schema is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getType

      public 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.
      Specified by:
      getType in interface ResourceRegistryClient
      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

      public 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.
      Specified by:
      getType in interface ResourceRegistryClient
      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

      public <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.
      Specified by:
      getType in interface ResourceRegistryClient
      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

      public <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.
      Specified by:
      getType in interface ResourceRegistryClient
      Type Parameters:
      ME - the model element type parameter
      Parameters:
      clazz - the class of the model element type to retrieve
      level - the maximum hierarchy level to include in the response
      Returns:
      list of Type objects representing the type definition(s) with hierarchy limited to the specified level
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type corresponding to the specified class is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - for retrieval errors or other system failures

    • getTypeTreeNode

      public org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type> getTypeTreeNode(String typeName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the type tree node for a specific type identified by its name. The tree node contains the type definition and its hierarchical position within the type system.
      Specified by:
      getTypeTreeNode in interface ResourceRegistryClient
      Parameters:
      typeName - the name of the type to retrieve
      Returns:
      the tree node containing the type and its hierarchical information
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the specified type name does not exist in the schema
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during the operation

    • getTypeTreeNode

      public <ME extends org.gcube.informationsystem.model.reference.ModelElement> org.gcube.informationsystem.tree.Node<org.gcube.informationsystem.types.reference.Type> getTypeTreeNode(Class<ME> clazz) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Retrieves the type tree node for a specific type identified by its model element class. The tree node contains the type definition and its hierarchical position within the type system.
      Specified by:
      getTypeTreeNode in interface ResourceRegistryClient
      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

    • getTypeFromServer

      public <ME extends org.gcube.informationsystem.model.reference.ModelElement> List<org.gcube.informationsystem.types.reference.Type> getTypeFromServer(Class<ME> clazz, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets type information directly from the server, bypassing the local cache.
      Type Parameters:
      ME - the type parameter extending ModelElement
      Parameters:
      clazz - the class representing the type to retrieve
      polymorphic - whether to include polymorphic types
      Returns:
      a list of Type objects
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type schema is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getTypeFromServer

      public String getTypeFromServer(String typeName, Boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException, org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets type schema directly from the server as a JSON string. Corresponding REST API: GET /access/types/{type-name}[?polymorphic={true|false}&includeMeta={true|false}] Operation Behavior:
      • Retrieves type schema definition(s) for the specified type name
      • When polymorphic=false: returns only the specified type definition
      • When polymorphic=true: returns the specified type AND all its existing subtypes
      • Metadata inclusion is controlled by client configuration and user authorization
      • Response detail level varies based on user authorization (IS/Infrastructure managers get full metadata).
      HTTP Response Codes:
      • 200 OK: Type successfully retrieved
      • 404 Not Found: Type with the specified name does not exist
      • 403 Forbidden: User lacks authorization to access type information.
      Query Parameters 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.
      Authorization Requirements:
      • IS-Manager: Receive complete type definitions with full metadata when requested
      • Infrastructure-Manager: Receive complete type definitions with full metadata when requested
      • All Other Users: Receive basic type information with filtered metadata (sensitive information obfuscated).
      Example Usage: 
       ResourceRegistryClient client = ResourceRegistryClientFactory.create();
 
 // Read a ContactFacet type definition only
 String contactFacetSchema = client.getType("ContactFacet", false);
 
 // Read ContactFacet and all its subtypes
 String contactFacetAndSubtypes = client.getType("ContactFacet", true);
      Parameters:
      typeName - the name of the type 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:
      the type schema as a JSON string
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaNotFoundException - if the type schema is not found
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getInstances

      public <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);
      Specified by:
      getInstances in interface ResourceRegistryClient
      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

      public 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);
      Specified by:
      getInstances in interface ResourceRegistryClient
      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

      public <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);
      Specified by:
      existInstance in interface ResourceRegistryClient
      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

      public 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);
      Specified by:
      existInstance in interface ResourceRegistryClient
      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

      public <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);
      Specified by:
      getInstance in interface ResourceRegistryClient
      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

      public 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
      Description copied from interface: ResourceRegistryClient
      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);
      Specified by:
      getInstance in interface ResourceRegistryClient
      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

    • rawQuery

      public 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);
      Specified by:
      rawQuery in interface ResourceRegistryClient
      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

      public 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);
      Specified by:
      rawQuery in interface ResourceRegistryClient
      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

    • getRelated

      protected String getRelated(String entityType, String relationType, String referenceEntityType, UUID referenceEntity, org.gcube.informationsystem.base.reference.Direction direction, Boolean polymorphic, Map<String,String> facetConstraints) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets entities related to a specific reference entity through a specific relation.
      Parameters:
      entityType - the type of entities to retrieve
      relationType - the type of relation connecting the entities
      referenceEntityType - the type of the reference entity
      referenceEntity - the UUID of the reference entity (null for constraints-based search)
      direction - the direction of the relation (IN/OUT)
      polymorphic - whether to include polymorphic types
      facetConstraints - optional constraints on facet properties
      Returns:
      JSON string containing the related entities
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getResourcesFromReferenceFacet

      public <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);
      Specified by:
      getResourcesFromReferenceFacet in interface ResourceRegistryClient
      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

      public <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
      Description copied from interface: ResourceRegistryClient
      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);
      Specified by:
      getResourcesFromReferenceFacet in interface ResourceRegistryClient
      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

      public String getResourcesFromReferenceFacet(String resourceType, String consistsOfType, String facetType, UUID facetUUID, 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);
      Specified by:
      getResourcesFromReferenceFacet in interface ResourceRegistryClient
      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
      facetUUID - 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

      public <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> facetConstraints) 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);
      Specified by:
      getFilteredResources in interface ResourceRegistryClient
      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.
      facetConstraints - 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

      public String getFilteredResources(String resourceType, String consistsOfType, String facetType, boolean polymorphic, Map<String,String> facetConstraints) 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);
      Specified by:
      getFilteredResources in interface ResourceRegistryClient
      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.
      facetConstraints - 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

      public <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);
      Specified by:
      getRelatedResourcesFromReferenceResource in interface ResourceRegistryClient
      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

      public <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);
      Specified by:
      getRelatedResourcesFromReferenceResource in interface ResourceRegistryClient
      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

      public 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);
      Specified by:
      getRelatedResourcesFromReferenceResource in interface ResourceRegistryClient
      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

      public <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
      Description copied from interface: ResourceRegistryClient
      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);
      Specified by:
      getRelatedResources in interface ResourceRegistryClient
      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

      public 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);
      Specified by:
      getRelatedResources in interface ResourceRegistryClient
      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

    • getRelated

      protected <E extends org.gcube.informationsystem.model.reference.entities.Entity, R extends org.gcube.informationsystem.model.reference.relations.Relation<?, ?>, RE extends org.gcube.informationsystem.model.reference.entities.Entity> List<E> getRelated(Class<E> entityClass, Class<R> relationClass, Class<RE> referenceEntityClass, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic, Map<String,String> map) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets entities related through a specific relation with constraint-based filtering.
      Type Parameters:
      E - the entity type to retrieve
      R - the relation type
      RE - the reference entity type
      Parameters:
      entityClass - the class of entities to retrieve
      relationClass - the class of the relation
      referenceEntityClass - the class of the reference entity
      direction - the direction of the relation (IN/OUT)
      polymorphic - whether to include polymorphic types
      map - optional constraints on entity properties
      Returns:
      a list of related entities
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getRelated

      protected String getRelated(String entityType, String relationType, String referenceEntityType, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic, Map<String,String> facetConstraints) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets entities related through a specific relation with constraint-based filtering (string-based).
      Parameters:
      entityType - the type name of entities to retrieve
      relationType - the type name of the relation
      referenceEntityType - the type name of the reference entity
      direction - the direction of the relation (IN/OUT)
      polymorphic - whether to include polymorphic types
      facetConstraints - optional constraints on facet properties
      Returns:
      JSON string containing the related entities
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getRelated

      protected <E extends org.gcube.informationsystem.model.reference.entities.Entity, R extends org.gcube.informationsystem.model.reference.relations.Relation<?, ?>, RE extends org.gcube.informationsystem.model.reference.entities.Entity> List<E> getRelated(Class<E> entityClass, Class<R> relationClass, Class<RE> referenceEntityClass, RE referenceEntity, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets entities related to a specific reference entity through a specific relation.
      Type Parameters:
      E - the entity type to retrieve
      R - the relation type
      RE - the reference entity type
      Parameters:
      entityClass - the class of entities to retrieve
      relationClass - the class of the relation
      referenceEntityClass - the class of the reference entity
      referenceEntity - the specific reference entity instance
      direction - the direction of the relation (IN/OUT)
      polymorphic - whether to include polymorphic types
      Returns:
      a list of related entities
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getRelated

      protected <E extends org.gcube.informationsystem.model.reference.entities.Entity, R extends org.gcube.informationsystem.model.reference.relations.Relation<?, ?>, RE extends org.gcube.informationsystem.model.reference.entities.Entity> List<E> getRelated(Class<E> entityClass, Class<R> relationClass, Class<RE> referenceEntityClass, UUID referenceEntityUUID, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets entities related to a specific reference entity through a specific relation using UUID.
      Type Parameters:
      E - the entity type to retrieve
      R - the relation type
      RE - the reference entity type
      Parameters:
      entityClass - the class of entities to retrieve
      relationClass - the class of the relation
      referenceEntityClass - the class of the reference entity
      referenceEntityUUID - the UUID of the reference entity
      direction - the direction of the relation (IN/OUT)
      polymorphic - whether to include polymorphic types
      Returns:
      a list of related entities
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getRelated

      protected String getRelated(String entityType, String relationType, String referenceEntityType, UUID referenceEntity, org.gcube.informationsystem.base.reference.Direction direction, boolean polymorphic) throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException
      Gets entities related to a specific reference entity through a specific relation (string-based with UUID).
      Parameters:
      entityType - the type name of entities to retrieve
      relationType - the type name of the relation
      referenceEntityType - the type name of the reference entity
      referenceEntity - the UUID of the reference entity
      direction - the direction of the relation (IN/OUT)
      polymorphic - whether to include polymorphic types
      Returns:
      JSON string containing the related entities
      Throws:
      org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - if an error occurs during retrieval

    • getInstanceContexts

      public <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());
 }
      Specified by:
      getInstanceContexts in interface ResourceRegistryClient
      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

      public 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());
 }
      Specified by:
      getInstanceContexts in interface ResourceRegistryClient
      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

      public 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();
      Specified by:
      getAllQueryTemplates in interface ResourceRegistryClient
      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

      public boolean existQueryTemplate(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
      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);
      Specified by:
      existQueryTemplate in interface ResourceRegistryClient
      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
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException

    • existQueryTemplate

      public boolean existQueryTemplate(String queryTemplateName) throws org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException, 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");
      Specified by:
      existQueryTemplate in interface ResourceRegistryClient
      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
      org.gcube.informationsystem.resourceregistry.api.exceptions.queries.templates.QueryTemplateNotFoundException

    • readQueryTemplate

      public 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);
      Specified by:
      readQueryTemplate in interface ResourceRegistryClient
      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

      public 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");
      Specified by:
      readQueryTemplate in interface ResourceRegistryClient
      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

      public 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");
      Specified by:
      readQueryTemplateAsString in interface ResourceRegistryClient
      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

      public 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");
      Specified by:
      runQueryTemplate in interface ResourceRegistryClient
      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

      public 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);
      Specified by:
      runQueryTemplate in interface ResourceRegistryClient
      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

      public 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);
      Specified by:
      runQueryTemplate in interface ResourceRegistryClient
      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

      public 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);
      Specified by:
      runQueryTemplate in interface ResourceRegistryClient
      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

      public 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);
      Specified by:
      runQueryTemplate in interface ResourceRegistryClient
      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

    • jsonQuery

      public 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);
      Specified by:
      jsonQuery in interface ResourceRegistryClient
      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

      public <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);
      Specified by:
      jsonQuery in interface ResourceRegistryClient
      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