Package org.gcube.informationsystem.resourceregistry.publisher

Interface ResourceRegistryPublisher

All Superinterfaces:

org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

All Known Implementing Classes:

ResourceRegistryPublisherImpl

public interface ResourceRegistryPublisher
extends org.gcube.informationsystem.resourceregistry.api.request.RequestInfo

Client interface for publishing and managing entities, relations, and resources in the Resource Registry. Purpose: This interface provides methods for creating, reading, updating, and deleting Information System model instances (Resources, Facets, ConsistsOf relations, IsRelatedTo relations) in the Resource Registry service. Instantiation: Clients should be created using the factory pattern for proper configuration:

 // Recommended way to create a client
 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 

Supported Operations:

• List Operations: Retrieve instances of specific types with filtering and pagination support
• CRUD Operations: Create, Read, Update, Delete for all Information System model types
• Context Management: Add/remove instances to/from specific contexts
• Specialized Operations: Type-specific methods for Resources, Facets, and Relations.

Query Parameter Configuration: Most methods support optional query parameters that can be configured via the client configuration: * - limit: Maximum number of results per request;

• offset: Number of results to skip for pagination
• includeMeta: Include metadata in responses (role-based filtering applied)
• allMeta: Include metadata for all nested instances
• includeContexts: Show context availability information
• hierarchical: Include instances from child contexts (admin-only).

Authorization: All operations respect the authorization context derived from the current authentication token. Users can only access and modify instances within their authorized contexts. Context Support: The client automatically operates within the context determined by the authorization token. Additional methods support cross-context operations for authorized users.

Author:

Luca Frosini (ISTI - CNR)

Field Summary

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

DEFAULT_LIMIT, DEFAULT_OFFSET, UNBOUNDED_LIMIT

Method Summary

Modifier and Type	Method	Description
<F extends org.gcube.informationsystem.model.reference.entities.Facet> List<org.gcube.informationsystem.model.reference.ERElement>	addFacetToContext(F facet, UUID contextUUID, Boolean dryRun)	Adds a Facet instance to a specific context using a provided Facet object.
List<org.gcube.informationsystem.model.reference.ERElement>	addFacetToContext(String facetType, UUID facetUUID, UUID contextUUID, Boolean dryRun)	Adds a Facet instance to a specific context using type name and UUID.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> List<org.gcube.informationsystem.model.reference.ERElement>	addFacetToCurrentContext(F facet, Boolean dryRun)	Adds a Facet instance to the current context using a provided Facet object.
List<org.gcube.informationsystem.model.reference.ERElement>	addFacetToCurrentContext(String facetType, UUID facetUUID, Boolean dryRun)	Adds a Facet instance to the current context using type name and UUID.
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.
List<org.gcube.informationsystem.model.reference.ERElement>	addResourceToContext(String resourceType, UUID resourceUUID, UUID contextUUID, Boolean dryRun)	Adds a Resource instance to a specific context.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> List<org.gcube.informationsystem.model.reference.ERElement>	addResourceToContext(R resource, UUID contextUUID, Boolean dryRun)	Adds a Resource instance to a specific context using a provided Resource object.
List<org.gcube.informationsystem.model.reference.ERElement>	addResourceToCurrentContext(String resourceType, UUID resourceUUID, Boolean dryRun)	Adds a Resource instance to the current context.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> List<org.gcube.informationsystem.model.reference.ERElement>	addResourceToCurrentContext(R resource, Boolean dryRun)	Adds a Resource instance to the current context using a provided Resource object.
List<org.gcube.informationsystem.model.reference.ERElement>	addToContext(String type, UUID instanceUUID, UUID contextUUID, Boolean dryRun)	Adds an Information System element instance to a specific context.
List<org.gcube.informationsystem.model.reference.ERElement>	addToContext(org.gcube.informationsystem.model.reference.ERElement er, UUID contextUUID, Boolean dryRun)	Adds an Information System element instance to a specific context using a provided instance object.
List<org.gcube.informationsystem.model.reference.ERElement>	addToCurrentContext(String type, UUID instanceUUID, Boolean dryRun)	Adds an Information System element instance to the current context.
List<org.gcube.informationsystem.model.reference.ERElement>	addToCurrentContext(org.gcube.informationsystem.model.reference.ERElement er, Boolean dryRun)	Adds an Information System element instance to the current context using a provided instance object.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> ERElem	create(ERElem er)	Creates a new instance of an Information System element in the Resource Registry.
String	create(String json)	Creates a new instance of an Information System element from JSON representation.
<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Facet>> C	createConsistsOf(C consistsOf)	Creates a new ConsistsOf relation instance in the Resource Registry.
String	createConsistsOf(String consistsOf)	Creates a new ConsistsOf relation instance from JSON representation.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> F	createFacet(F facet)	Creates a new Facet instance in the Resource Registry.
String	createFacet(String facet)	Creates a new Facet instance from JSON representation.
<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Resource>> I	createIsRelatedTo(I isRelatedTo)	Creates a new IsRelatedTo relation instance in the Resource Registry.
String	createIsRelatedTo(String isRelatedTo)	Creates a new IsRelatedTo relation instance from JSON representation.
String	createResource(String resource)	Creates a new Resource instance from JSON representation.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> R	createResource(R resource)	Creates a new Resource instance in the Resource Registry.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> boolean	delete(ERElem er)	Deletes an Information System element instance from the Resource Registry.
boolean	delete(String type, UUID uuid)	Deletes an Information System element instance from the Resource Registry using type name and UUID.
<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Facet>> boolean	deleteConsistsOf(C consistsOf)	Deletes a ConsistsOf relation instance from the Resource Registry.
boolean	deleteConsistsOf(String consistsOfType, UUID uuid)	Deletes a ConsistsOf relation instance from the Resource Registry using type name and UUID.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> boolean	deleteFacet(F facet)	Deletes a Facet instance from the Resource Registry.
boolean	deleteFacet(String facetType, UUID uuid)	Deletes a Facet instance from the Resource Registry using type name and UUID.
<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Resource>> boolean	deleteIsRelatedTo(I isRelatedTo)	Deletes an IsRelatedTo relation instance from the Resource Registry.
boolean	deleteIsRelatedTo(String isRelatedToType, UUID uuid)	Deletes an IsRelatedTo relation instance from the Resource Registry by its type and UUID.
boolean	deleteResource(String resourceType, UUID uuid)	Deletes a Resource instance from the Resource Registry using type name and UUID.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> boolean	deleteResource(R resource)	Deletes a Resource instance from the Resource Registry.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> boolean	exist(ERElem er)	Checks if an Information System element instance exists in the Resource Registry.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> boolean	exist(Class<ERElem> clazz, UUID uuid)	Checks if an Information System element instance exists in the Resource Registry using class and UUID.
boolean	exist(String type, UUID uuid)	Checks if an Information System element instance exists in the Resource Registry using type name and UUID.
List<org.gcube.informationsystem.contexts.reference.entities.Context>	getAllContexts()	Retrieves all available contexts using internal cache.
org.gcube.informationsystem.contexts.reference.entities.Context	getContext(UUID uuid)	Retrieves a specific context by its UUID using internal cache.
org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache	getContextCache()	Gets the context cache used for context-related operations.
org.gcube.informationsystem.contexts.reference.entities.Context	getCurrentContext()	Retrieves the current context associated with the publisher's authorization token using internal cache.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> Map<UUID,String>	getElementContexts(ERElem er)	Retrieves the list of contexts where a specific Information System element is present in the Resource Registry.
Map<UUID,String>	getElementContexts(String type, UUID instanceUUID)	Retrieves the list of contexts where a specific Information System element is present in the Resource Registry.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> Map<UUID,String>	getFacetContexts(F facet)	Retrieves the list of contexts where a specific Facet is present in the Resource Registry.
Map<UUID,String>	getFacetContexts(String facetType, UUID facetUUID)	Retrieves the list of contexts where a specific Facet is present in the Resource Registry.
Map<UUID,String>	getResourceContexts(String resourceType, UUID resourceUUID)	Retrieves the list of contexts where a specific Resource is present in the Resource Registry.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> Map<UUID,String>	getResourceContexts(R resource)	Retrieves the list of contexts where a specific Resource is present in the Resource Registry.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> List<ERElem>	list(Class<ERElem> clazz, Boolean polymorphic)	Retrieves all instances of the specified type from the Resource Registry.
String	list(String type, Boolean polymorphic)	Retrieves all instances of the specified type from the Resource Registry as JSON string.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> ERElem	read(ERElem er)	Reads an existing instance from the Resource Registry using a provided instance object.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> ERElem	read(Class<ERElem> clazz, UUID uuid)	Reads an existing instance from the Resource Registry by its type class and UUID.
String	read(String type, UUID uuid)	Reads an existing instance from the Resource Registry by its type name and UUID.
<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Facet>> C	readConsistsOf(C consistsOf)	Reads a ConsistsOf relation instance from the Resource Registry using a provided instance object.
String	readConsistsOf(String consistsOfType, UUID uuid)	Reads a ConsistsOf relation instance from the Resource Registry by its type and UUID.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> F	readFacet(F facet)	Reads a Facet instance from the Resource Registry using a provided instance object.
String	readFacet(String facetType, UUID uuid)	Reads a Facet instance from the Resource Registry by its type and UUID.
<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Resource>> I	readIsRelatedTo(I isRelatedTo)	Reads an IsRelatedTo relation instance from the Resource Registry by its UUID.
String	readIsRelatedTo(String isRelatedToType, UUID uuid)	Reads an IsRelatedTo relation instance from the Resource Registry by its type and UUID.
String	readResource(String resourceType, UUID uuid)	Reads a Resource instance from the Resource Registry by its type and UUID.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> R	readResource(R resource)	Reads a Resource instance from the Resource Registry using a provided instance object.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> List<org.gcube.informationsystem.model.reference.ERElement>	removeFacetFromContext(F facet, UUID contextUUID, Boolean dryRun)	Removes a Facet instance from a specific context using a provided Facet object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFacetFromContext(String facetType, UUID facetUUID, UUID contextUUID, Boolean dryRun)	Removes a Facet instance from a specific context.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> List<org.gcube.informationsystem.model.reference.ERElement>	removeFacetFromCurrentContext(F facet, Boolean dryRun)	Removes a Facet instance from the current context using a provided Facet object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFacetFromCurrentContext(String facetType, UUID facetUUID, Boolean dryRun)	Removes a Facet instance from the current context.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFromContext(String type, UUID instanceUUID, UUID contextUUID, Boolean dryRun)	Removes an Information System element instance from a specific context.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFromContext(org.gcube.informationsystem.model.reference.ERElement er, UUID contextUUID, Boolean dryRun)	Removes an Information System element instance from a specific context using a provided instance object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFromCurrentContext(String type, UUID instanceUUID, Boolean dryRun)	Removes an ERElement instance from the current context.
List<org.gcube.informationsystem.model.reference.ERElement>	removeFromCurrentContext(org.gcube.informationsystem.model.reference.ERElement er, Boolean dryRun)	Removes an ERElement instance from the current context using a provided ERElement object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeResourceFromContext(String resourceType, UUID resourceUUID, UUID contextUUID, Boolean dryRun)	Removes a Resource instance from a specific context.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> List<org.gcube.informationsystem.model.reference.ERElement>	removeResourceFromContext(R resource, UUID contextUUID, Boolean dryRun)	Removes a Resource instance from a specific context using a provided Resource object.
List<org.gcube.informationsystem.model.reference.ERElement>	removeResourceFromCurrentContext(String resourceType, UUID resourceUUID, Boolean dryRun)	Removes a Resource instance from the current context.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> List<org.gcube.informationsystem.model.reference.ERElement>	removeResourceFromCurrentContext(R resource, Boolean dryRun)	Removes a Resource instance from the current context using a provided Resource object.
<ERElem extends org.gcube.informationsystem.model.reference.ERElement> ERElem	update(ERElem er)	Updates an existing instance in the Resource Registry using the instance object.
String	update(String json)	Updates an existing instance in the Resource Registry using JSON representation.
String	update(String type, String json)	Updates an existing instance in the Resource Registry using type name and JSON representation.
String	update(String type, String json, UUID uuid)	Updates an existing instance in the Resource Registry using type name, JSON representation, and explicit UUID.
<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Facet>> C	updateConsistsOf(C consistsOf)	Updates an existing ConsistsOf relation instance in the Resource Registry.
String	updateConsistsOf(String consistsOf)	Updates an existing ConsistsOf relation instance in the Resource Registry using JSON representation.
<F extends org.gcube.informationsystem.model.reference.entities.Facet> F	updateFacet(F facet)	Updates an existing Facet instance in the Resource Registry.
String	updateFacet(String facet)	Updates an existing Facet instance in the Resource Registry using JSON representation.
<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource, ? extends org.gcube.informationsystem.model.reference.entities.Resource>> I	updateIsRelatedTo(I isRelatedTo)	Updates an existing IsRelatedTo relation instance in the Resource Registry.
String	updateIsRelatedTo(String isRelatedTo)	Updates an existing IsRelatedTo relation instance from JSON representation.
String	updateResource(String resource)	Updates an existing Resource instance in the Resource Registry using JSON representation.
<R extends org.gcube.informationsystem.model.reference.entities.Resource> R	updateResource(R resource)	Updates an existing Resource instance in the Resource Registry.

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

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

Method Details

addHeader

void addHeader(String name,
 String value)

Adds a custom HTTP header to be included in requests.

Parameters:

name - Header name

value - Header value

addHeader

void addHeader(String name,
 boolean value)

Adds a custom HTTP header to be included in requests.

Parameters:

name - Header name

value - boolean value

getContextCache

org.gcube.informationsystem.resourceregistry.api.contexts.ContextCache getContextCache()

Gets the context cache used for context-related operations. Cache Behavior:

• Provides access to the internal context cache used by all context methods
• Cache improves performance by avoiding repeated server requests
• Automatically manages cache updates and invalidation
• Used internally by getAllContexts(), getContext(), and getCurrentContext() methods.

Authorization Requirements:

• Available to all authenticated users
• Cache content is filtered based on user authorization level.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Access context cache for advanced operations
 ContextCache cache = publisher.getContextCache();
 
 // Force cache refresh if needed
 cache.refresh();
 

Returns:

The context cache instance

getAllContexts

List<org.gcube.informationsystem.contexts.reference.entities.Context> getAllContexts()
                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves all available contexts using internal cache. Cache Behavior:

• Uses internal context cache - does NOT bypass cache like server-direct methods
• First call may trigger server request to populate cache
• Subsequent calls return cached data for improved performance
• Cache is automatically maintained and refreshed as needed.

Query Parameters NOT Applicable:

• Standard query parameters like includeMeta, limit, offset, hierarchical are NOT applicable to cached methods
• Cache behavior is controlled internally for optimal performance
• For direct server access with full query control, use the implementation's FromServer methods.

Authorization Requirements:

• Available to all authenticated users
• Returns contexts accessible based on user authorization level
• Context list is filtered according to user permissions.

Context Content:

• Includes all contexts where the user has any level of access
• Context details include basic information (name, UUID, parent relationships)
• Metadata inclusion depends on cache configuration and user role.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get all contexts from cache
 List<Context> contexts = publisher.getAllContexts();
 
 // Iterate through available contexts
 for (Context context : contexts) {
     System.out.println("Context: " + context.getName() + " (" + context.getUuid() + ")");
 }
 

Returns:

List of all contexts accessible to the current user (from cache)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If fails to retrieve contexts from cache or server

getContext

org.gcube.informationsystem.contexts.reference.entities.Context getContext(UUID uuid)
                                                                    throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves a specific context by its UUID using internal cache. Cache Behavior:

• Uses internal context cache - does NOT bypass cache like server-direct methods
• First call may trigger cache population from server if needed
• Subsequent calls use cached data for improved performance
• Cache is automatically maintained and refreshed as needed.

Query Parameters NOT Applicable:

• Standard query parameters like includeMeta, hierarchical are NOT applicable to cached methods
• Metadata inclusion depends on cache configuration and user role
• For direct server access with full query control, use the implementation's FromServer methods.

Authorization Requirements:

• Available to all authenticated users
• Returns context only if accessible based on user authorization level
• Context details are filtered according to user permissions and role.

Context Content:

• Includes basic context information (name, UUID, parent relationships)
• Metadata inclusion depends on user role: IS-Manager/Infrastructure-Manager see complete metadata, others see filtered metadata
• Sensitive information (createdBy, lastUpdatedBy) may be obfuscated for non-administrative users.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get context from cache
 UUID contextUUID = UUID.fromString("c0f314e7-2807-4241-a792-2a6c79ed4fd0");
 Context context = publisher.getContext(contextUUID);
 
 System.out.println("Context name: " + context.getName());
 System.out.println("Context UUID: " + context.getUuid());
 System.out.println("Parent context: " + context.getParent());
 

Parameters:

uuid - The UUID of the context to retrieve

Returns:

The context with the specified UUID (from cache)

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 context retrieval

getCurrentContext

org.gcube.informationsystem.contexts.reference.entities.Context getCurrentContext()
                                                                           throws org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the current context associated with the publisher'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:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get current context from cache
 Context currentContext = publisher.getCurrentContext();
 
 System.out.println("Current context name: " + currentContext.getName());
 System.out.println("Current context UUID: " + currentContext.getUuid());
 System.out.println("Current context parent: " + currentContext.getParent());
 

Returns:

The current context associated with the authorization token (from cache)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

list

<ERElem extends org.gcube.informationsystem.model.reference.ERElement>
List<ERElem> list(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 /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 class 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.

Query Parameters: polymorphic (automatically set from method parameter):

• Whether to include instances of subtypes in the response
• Default: true (includes all subtypes)
• Values: true (includes all subtypes) | false (exact type only)
• Query parameter: InstancePath.POLYMORPHIC_QUERY_PARAMETER.

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 contexts (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: publisher.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: publisher.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: publisher.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: publisher.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.

HTTP Response Codes:

• 200 OK: Instances successfully retrieved
• 400 Bad Request: Invalid type name or query parameters
• 403 Forbidden: Insufficient permissions to list instances or access hierarchical data
• 404 Not Found: Specified type does not exist in the model
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

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

• IS-Manager: Full access to list any instances with hierarchical querying across all contexts; receives complete, unfiltered metadata
• Infrastructure-Manager: Full access to list any instances with hierarchical querying across all contexts; receives complete, unfiltered metadata
• Context-Manager: Full access to list instances within managed contexts with hierarchical querying; receives complete, unfiltered metadata
• All Other Users: Basic access with metadata filtering; receive metadata with sensitive information filtered when includeMeta=true.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get all EService instances including subtypes
 List<EService> services = publisher.list(EService.class, true);
 
 // Get only exact ContactFacet instances (no subtypes)
 List<ContactFacet> contacts = publisher.list(ContactFacet.class, false);
 

Type Parameters:

ERElem - The specific type of Information System element to retrieve

Parameters:

clazz - The class representing the type of instances to retrieve

polymorphic - Whether to include instances of subtypes (true) or only exact type instances (false)

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

list

String list(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 /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: polymorphic (automatically set from method parameter):

• Whether to include instances of subtypes in the response
• Default: true (includes all subtypes)
• Values: true (includes all subtypes) | false (exact type only)
• Query parameter: InstancePath.POLYMORPHIC_QUERY_PARAMETER.

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 contexts (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: publisher.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: publisher.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: publisher.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: publisher.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 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 list instances.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get all EService instances as JSON
 String servicesJson = publisher.list("EService", true);
 
 // Get only exact ContactFacet instances as JSON
 String contactsJson = publisher.list("ContactFacet", false);
 

Parameters:

type - The name of the Information System type whose instances to retrieve

polymorphic - Whether to include instances of subtypes (true) or only exact type instances (false)

Returns:

JSON array string containing the 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

create

<ERElem extends org.gcube.informationsystem.model.reference.ERElement>
ERElem create(ERElem er)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new instance of an Information System element in the Resource Registry. Corresponding REST API: POST /instances/{type-name} Operation Behavior:

• Creates a new entity (Resource, Facet) or relation (ConsistsOf, IsRelatedTo) instance
• The instance is automatically associated with the current context
• Validates the instance against the Information System model schema
• Generates a new UUID for the instance if not already set
• Returns the created instance with server-generated metadata.

HTTP Response Codes:

• 201 Created: Instance successfully created
• 400 Bad Request: Invalid instance data or schema validation failure
• 409 Conflict: Instance with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• Type name is automatically derived from the provided object 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).

Schema Validation:

• All properties and relationships are validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced
• Relation targets must exist and be accessible in compatible contexts.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create instances.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new EService resource
 EService service = new EService();
 ...
 EService createdService = publisher.create(service);
 
 // Create a new ContactFacet
 ContactFacet contact = new ContactFacet();
 ....
 ContactFacet createdContact = publisher.create(contact);
 

Type Parameters:

ERElem - The specific type of Information System element to create

Parameters:

er - The instance to create in the Resource Registry

Returns:

The created instance with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the instance violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - If an instance with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance creation

create

String create(String json)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new instance of an Information System element from JSON representation. Corresponding REST API: POST /instances/{type-name} Operation Behavior:

• Creates a new entity (Resource, Facet) or relation (ConsistsOf, IsRelatedTo) instance from JSON
• The instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the instance if not already set
• Returns the created instance as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: Instance successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: Instance with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying the Information System type
• Must conform to the Information System model JSON schema
• All required properties for the specified type must be present
• Nested objects and relations must be properly formatted.

Schema Validation:

• JSON structure is validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced
• Relation targets must exist and be accessible in compatible contexts.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create instances.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new EService from JSON
 String serviceJson = "...";
 String createdServiceJson = publisher.create(serviceJson);
 
 // Create a new ContactFacet from JSON
 String contactJson = "...";
 String createdContactJson = publisher.create(contactJson);
 

Parameters:

json - JSON representation of the instance to create

Returns:

JSON representation of the created instance with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.AlreadyPresentException - If an instance with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance creation or JSON parsing

exist

<ERElem extends org.gcube.informationsystem.model.reference.ERElement>
boolean exist(ERElem er)
       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. Corresponding REST API: HEAD /instances/{type-name}/{uuid}[?hierarchical={true|false}] Operation Behavior:

• Verifies the existence of the specified instance using its UUID and type
• The type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• Does not return the instance data, only confirms existence
• Checks accessibility within the current context and user authorization.

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: publisher.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 instance 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:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Check if an EService instance exists
 EService eService = new EService();
 eService.setID(someUUID);
 boolean exists = publisher.exist(eService);
 
 // Check if a ContactFacet instance exists
 ContactFacet contact = new ContactFacet();
 contact.setID(anotherUUID);
 boolean contactExists = publisher.exist(contact);
 

Type Parameters:

ERElem - The specific type of Information System element to check

Parameters:

er - The instance to check for existence (must have a valid UUID)

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 (HTTP 403)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

exist

<ERElem extends org.gcube.informationsystem.model.reference.ERElement>
boolean exist(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 /instances/{type-name}/{uuid}[?hierarchical={true|false}] Operation Behavior:

• Verifies the existence of the specified instance using its UUID and class type
• The type name is automatically derived from the provided class using TypeUtility.getTypeName(Class)
• Does not return the instance data, only confirms existence
• Checks accessibility within the current context and user authorization.

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: publisher.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(clazz)
• 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:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Check if an EService instance exists by class and UUID
 UUID serviceUUID = UUID.fromString("...");
 boolean exists = publisher.exist(EService.class, serviceUUID);
 
 // Check if a ContactFacet instance exists by class and UUID
 UUID contactUUID = UUID.fromString("...");
 boolean contactExists = publisher.exist(ContactFacet.class, contactUUID);
 

Type Parameters:

ERElem - The specific type of Information System element to check

Parameters:

clazz - The class representing the type of instance to check

uuid - The UUID of the instance to check for existence

Returns:

true if the instance exists and is accessible in the current context, false if not found

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 403)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

exist

boolean exist(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 /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: publisher.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:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Check if an EService instance exists by type name and UUID
 UUID serviceUUID = UUID.fromString("...");
 boolean exists = publisher.exist("EService", serviceUUID);
 
 // Check if a ContactFacet instance exists by type name and UUID
 UUID contactUUID = UUID.fromString("...");
 boolean contactExists = publisher.exist("ContactFacet", contactUUID);
 

Parameters:

type - The name of the Information System type to check

uuid - The UUID of the instance to check for existence

Returns:

true if the instance exists and is accessible in the current context, false if not found

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 403)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the existence check

read

<ERElem extends org.gcube.informationsystem.model.reference.ERElement>
ERElem read(ERElem er)
     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 using a provided instance object. Corresponding REST API: GET /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 extracting type and UUID from the provided instance
• 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
• The type is automatically determined from the provided instance object.

HTTP Response Codes:

• 200 OK: Instance successfully retrieved
• 404 Not Found: No instance found with the specified UUID 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: publisher.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: publisher.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: publisher.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: publisher.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 instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header.

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:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource
 EService eService = new EService();
 eService.setHeader(new Header(uuid));
 EService readEService = publisher.read(eService);
 

Type Parameters:

ERElem - The specific type of Entity or Relation to read

Parameters:

er - Instance object containing at least the UUID in the header

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 (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

read

<ERElem extends org.gcube.informationsystem.model.reference.ERElement>
ERElem read(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 /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
• 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
• Type validation ensures the UUID corresponds to an instance of the specified class.

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: publisher.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: publisher.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: publisher.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: publisher.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)
• The class must be a valid Information System model type.

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:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource by class and UUID
 UUID serviceUuid = UUID.fromString("...");
 EService service = publisher.read(EService.class, serviceUuid);
 

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 (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

read

String read(String type,
 UUID uuid)
     throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads an existing instance from the Resource Registry by its type name and UUID. Corresponding REST API: GET /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: publisher.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: publisher.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: publisher.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: publisher.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 specified type must be a valid Information System model type name
• 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
• UUID must correspond to an instance of exactly the specified type (no polymorphic matching).

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:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource by type and UUID
 UUID serviceUuid = UUID.fromString("...");
 String serviceJson = publisher.read("EService", serviceUuid);
 

Parameters:

type - The exact type name of the Entity or Relation to read

uuid - The unique identifier of the instance to read

Returns:

JSON representation of 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 (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.AvailableInAnotherContextException - If the instance exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance retrieval

update

<ERElem extends org.gcube.informationsystem.model.reference.ERElement>
ERElem update(ERElem er)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing instance in the Resource Registry using the instance object. REST Endpoint: PUT /instances/{type-name}/{instance-uuid} Request Examples:

• Basic update: EService myService = publisher.update(existingService);
• With metadata in response: publisher.includeMeta(true); EService myService = publisher.update(existingService);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); EService myService = publisher.update(existingService);
• With context information: publisher.includeContexts(true); EService myService = publisher.update(existingService);.

Update Behavior:

• Updates an existing instance with the same UUID as the provided instance
• The instance must already exist in the Resource Registry
• Only modifiable properties are updated; metadata fields are automatically managed
• The instance UUID cannot be changed during update operations.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• The type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header.

Schema Validation:

• All properties and relationships are validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced.

Context Access:

• The instance must be accessible in the current context.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Instance successfully updated
• 400 Bad Request: Invalid request body, malformed instance data, or schema validation failed
• 404 Not Found: The instance does not exist
• 403 Forbidden: Insufficient permissions to update the instance.

Response Format:

• Returns the updated instance object with its properties and relations
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are updated according to the current configuration.

Type Parameters:

ERElem - The generic type extending ERElement (Entity or Relation)

Parameters:

er - The instance object to update with new values

Returns:

The updated instance object with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated instance violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance update

update

String update(String json)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing instance in the Resource Registry using JSON representation. REST Endpoint: PUT /instances/{type-name}/{instance-uuid} Request Examples:

• Basic update: String result = publisher.update(jsonString);
• With metadata in response: publisher.includeMeta(true); String result = publisher.update(jsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String result = publisher.update(jsonString);
• With context information: publisher.includeContexts(true); String result = publisher.update(jsonString);.

Update Behavior:

• Updates an existing instance using JSON representation
• The JSON must contain the UUID of the instance to update
• The instance type is automatically detected from the JSON content
• The instance must already exist in the Resource Registry
• Only modifiable properties are updated; metadata fields are automatically managed.

JSON Format Requirements:

• Valid JSON representation of an Information System instance
• Must include the "id" field with the UUID of the instance to update
• Must include the "type" field to identify the instance type
• Must conform to the schema of the specified type.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• The instance type is automatically detected from the JSON content
• The JSON must contain the UUID of the instance to update.

Schema Validation:

• JSON structure is validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced.

Context Access:

• The instance must be accessible in the current context.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Instance successfully updated
• 400 Bad Request: Invalid JSON format, missing required fields, or schema validation failed
• 404 Not Found: The instance does not exist
• 403 Forbidden: Insufficient permissions to update the instance.

Response Format:

• Returns a JSON string containing the updated instance
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are updated according to the current configuration.

Parameters:

json - JSON representation of the instance to update

Returns:

JSON string containing the updated instance with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated instance violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance update

update

String update(String type,
 String json)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing instance in the Resource Registry using type name and JSON representation. REST Endpoint: PUT /instances/{type-name}/{instance-uuid} Request Examples:

• Basic update: String result = publisher.update("EService", jsonString);
• With metadata in response: publisher.includeMeta(true); String result = publisher.update("EService", jsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String result = publisher.update("EService", jsonString);
• With context information: publisher.includeContexts(true); String result = publisher.update("EService", jsonString);.

Update Behavior:

• Updates an existing instance using explicit type name and JSON representation
• The JSON must contain the UUID of the instance to update
• The provided type name must match the actual instance type
• The instance must already exist in the Resource Registry
• Only modifiable properties are updated; metadata fields are automatically managed.

JSON Format Requirements:

• Valid JSON representation of an Information System instance
• Must include the "id" field with the UUID of the instance to update
• May include the "type" field, but the explicitly provided type parameter takes precedence
• Must conform to the schema of the specified type.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• The provided type name must match the actual instance type
• The JSON must contain the UUID of the instance to update.

Schema Validation:

• JSON structure is validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced.

Context Access:

• The instance must be accessible in the current context.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Instance successfully updated
• 400 Bad Request: Invalid JSON format, type mismatch, missing required fields, or schema validation failed
• 404 Not Found: The instance or specified type does not exist
• 403 Forbidden: Insufficient permissions to update the instance.

Response Format:

• Returns a JSON string containing the updated instance
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are updated according to the current configuration.

Parameters:

type - The name of the Information System type (e.g., "EService", "ContactFacet")

json - JSON representation of the instance to update

Returns:

JSON string containing the updated instance with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated instance violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance to update or the specified type does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance update

update

String update(String type,
 String json,
 UUID uuid)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing instance in the Resource Registry using type name, JSON representation, and explicit UUID. REST Endpoint: PUT /instances/{type-name}/{instance-uuid} Request Examples:

• Basic update: String result = publisher.update("EService", jsonString, instanceUuid);
• With metadata in response: publisher.includeMeta(true); String result = publisher.update("EService", jsonString, instanceUuid);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String result = publisher.update("EService", jsonString, instanceUuid);
• With context information: publisher.includeContexts(true); String result = publisher.update("EService", jsonString, instanceUuid);.

Update Behavior:

• Updates an existing instance using explicit type name, JSON representation, and UUID
• The explicitly provided UUID takes precedence over any UUID in the JSON content
• The provided type name must match the actual instance type
• The instance must already exist in the Resource Registry
• Only modifiable properties are updated; metadata fields are automatically managed
• This method provides the most explicit control over instance identification.

JSON Format Requirements:

• Valid JSON representation of an Information System instance
• The "id" field in JSON is ignored if present; the uuid parameter is used instead
• May include the "type" field, but the explicitly provided type parameter takes precedence
• Must conform to the schema of the specified type.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response instance
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• The explicitly provided UUID takes precedence over any UUID in the JSON content
• The provided type name must match the actual instance type.

Schema Validation:

• JSON structure is validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced.

Context Access:

• The instance must be accessible in the current context.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Instance successfully updated
• 400 Bad Request: Invalid JSON format, type mismatch, invalid UUID, or schema validation failed
• 404 Not Found: The instance with the specified UUID or the specified type does not exist
• 403 Forbidden: Insufficient permissions to update the instance.

Response Format:

• Returns a JSON string containing the updated instance
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are updated according to the current configuration.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for the specific instance type in the current context
• The current context is derived from the authorization token provided during client creation.

Parameters:

type - The name of the Information System type (e.g., "EService", "ContactFacet")

json - JSON representation of the instance to update (UUID in JSON is ignored)

uuid - The unique identifier of the instance to update

Returns:

JSON string containing the updated instance with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated instance violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance with the specified UUID or the specified type does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during instance update

delete

<ERElem extends org.gcube.informationsystem.model.reference.ERElement>
boolean delete(ERElem er)
        throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes an Information System element instance from the Resource Registry. Corresponding REST API: DELETE /instances/{type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified instance from the Resource Registry
• The type and UUID are automatically extracted from the provided element object
• The instance must exist and be accessible in the current context
• Supports both Resource and Facet types and their specializations
• This is a destructive operation that cannot be undone
• Related elements may also be deleted based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Instance successfully deleted
• 404 Not Found: Instance does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the instance
• 409 Conflict: Instance cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type name is automatically derived from the provided element object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the element's header
• Supports all ERElement types: Resources, Facets, ConsistsOf relations, and IsRelatedTo relations.

Context Access:

• The instance must be accessible in the current context.

Deletion Propagation Rules:

• Resources: When a Resource is deleted, all its associated Facets (via ConsistsOf relations) may also be deleted if they become orphaned and the delete propagation constraint is propagate
• Facets: When a Facet is deleted, the parent Resources that reference it may also be affected based on schema constraints
• Relations: When a relation is deleted, the connected elements remain but the relationship is removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the instance will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Facet that is required by an existing Resource; • Deleting a Resource that has mandatory relationships that would be violated; • Operations that would make related elements incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the instance exists.

IS-Manager:

• Can delete any instance in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any instance in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete instances only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete instances only in contexts where they have appropriate permissions
• Operations are limited to instances they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an EService instance
 EService service = publisher.read(EService.class, serviceUUID);
 boolean deleted = publisher.delete(service);
 
 // Delete a ContactFacet instance
 ContactFacet contact = publisher.read(ContactFacet.class, contactUUID);
 boolean contactDeleted = publisher.delete(contact);
 

Type Parameters:

ERElem - The specific type of Information System element to delete

Parameters:

er - The instance to delete (must contain a valid UUID in the header)

Returns:

true if the instance was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the instance would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

delete

boolean delete(String type,
 UUID uuid)
        throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes an Information System element instance from the Resource Registry using type name and UUID. Corresponding REST API: DELETE /instances/{type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified instance from the Resource Registry
• The instance is identified by its type name and UUID
• The instance must exist and be accessible in the current context
• Supports both Resource and Facet types and their specializations
• This is a destructive operation that cannot be undone
• Related elements may also be deleted based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Instance successfully deleted
• 404 Not Found: Instance does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the instance
• 409 Conflict: Instance cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type parameter must be a valid ERElement type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all ERElement types: Resources (e.g., EService, HostingNode), Facets (e.g., StateFacet, ContactFacet), ConsistsOf relations, and IsRelatedTo relations
• The UUID must be a valid UUID that identifies an existing instance.

Context Access:

• The instance must be accessible in the current context.

Deletion Propagation Rules:

• Resources: When a Resource is deleted, all its associated Facets (via ConsistsOf relations) may also be deleted if they become orphaned and the delete propagation constraint is propagate
• Facets: When a Facet is deleted, the parent Resources that reference it may also be affected based on schema constraints
• Relations: When a relation is deleted, the connected elements remain but the relationship is removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the instance will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Facet that is required by an existing Resource; • Deleting a Resource that has mandatory relationships that would be violated; • Operations that would make related elements incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the instance exists.

IS-Manager:

• Can delete any instance in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any instance in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete instances only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete instances only in contexts where they have appropriate permissions
• Operations are limited to instances they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an EService instance by type and UUID
 UUID serviceUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 boolean deleted = publisher.delete("EService", serviceUUID);
 
 // Delete a ContactFacet instance by type and UUID
 UUID contactUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 boolean contactDeleted = publisher.delete("ContactFacet", contactUUID);
 

Parameters:

type - The exact type name of the ERElement to delete

uuid - The UUID of the instance to delete

Returns:

true if the instance was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the instance would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

createFacet

<F extends org.gcube.informationsystem.model.reference.entities.Facet>
F createFacet(F facet)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new Facet instance in the Resource Registry. Corresponding REST API: POST /instances/{facet-type-name} Operation Behavior:

• Creates a new Facet entity in the Information System
• Facets represent specific aspects or properties that can be attached to Resources via ConsistsOf relations
• The instance is automatically associated with the current context
• Validates the facet against the Information System model schema
• Generates a new UUID for the facet if not already set
• Returns the created facet with server-generated metadata.

HTTP Response Codes:

• 201 Created: Facet successfully created
• 400 Bad Request: Invalid facet data or schema validation failure
• 409 Conflict: Facet with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The facet type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Supports all Facet subtypes defined in the Information System model.

Schema Validation:

• All facet properties are validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced
• Facet-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new ContactFacet
 ContactFacet contact = new ContactFacet();
 ...
 ContactFacet createdContact = publisher.createFacet(contact);
 
 // Create a new SoftwareFacet
 SoftwareFacet software = new SoftwareFacet();
 ...
 SoftwareFacet createdSoftware = publisher.createFacet(software);
 

Type Parameters:

F - The specific type of Facet to create

Parameters:

facet - The Facet instance to create in the Resource Registry

Returns:

The created Facet with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the facet violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAlreadyPresentException - If a facet with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during facet creation

createFacet

String createFacet(String facet)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new Facet instance from JSON representation. Corresponding REST API: POST /instances/{facet-type-name} Operation Behavior:

• Creates a new Facet entity from JSON representation
• Facets represent specific aspects or properties that can be attached to Resources via ConsistsOf relations
• The instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the facet if not already set
• Returns the created facet as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: Facet successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: Facet with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying a Facet type
• Must conform to the Information System model JSON schema for Facets
• All required properties for the specified facet type must be present
• Facet-specific properties must be properly formatted.

Schema Validation:

• JSON structure is validated against the Information System model
• Required facet properties must be present and valid
• Property types and constraints are enforced
• Facet-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new ContactFacet from JSON
 String contactJson = "...";
 String createdContactJson = publisher.createFacet(contactJson);
 
 // Create a new SoftwareFacet from JSON
 String softwareJson = "...";
 String createdSoftwareJson = publisher.createFacet(softwareJson);
 

Parameters:

facet - JSON representation of the Facet to create

Returns:

JSON representation of the created Facet with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAlreadyPresentException - If a facet with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during facet creation or JSON parsing

readFacet

<F extends org.gcube.informationsystem.model.reference.entities.Facet>
F readFacet(F facet)
     throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a Facet instance from the Resource Registry using a provided instance object. Corresponding REST API: GET /instances/{facet-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing Facet by extracting type and UUID from the provided instance
• The Facet must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete Facet instance with all properties and metadata
• The type is automatically determined from the provided instance object.

HTTP Response Codes:

• 200 OK: Facet successfully retrieved
• 404 Not Found: No Facet found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks read permissions for the Facet 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: publisher.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: publisher.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: publisher.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 Facets from child contexts of the current context
• Values: true (includes child contexts) | false (current context only)
• Restriction: Only available to IS-Manager, Infrastructure-Manager, and Context-Manager roles
• Query parameter: InstancePath.HIERARCHICAL_MODE_QUERY_PARAMETER.

Input Processing:

• The Facet type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header
• The returned object will be of the same Facet type as the provided instance.

Context Access:

• The Facet 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 Facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read a ContactFacet
 ContactFacet contactFacet = new ContactFacet();
 contactFacet.setHeader(new Header(uuid));
 ContactFacet readContactFacet = publisher.readFacet(contactFacet);
 

Type Parameters:

F - The specific type of Facet to read

Parameters:

facet - Instance object containing at least the UUID in the header

Returns:

The complete Facet instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If no Facet is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAvailableInAnotherContextException - If the Facet exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Facet retrieval

readFacet

String readFacet(String facetType,
 UUID uuid)
          throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a Facet instance from the Resource Registry by its type and UUID. Corresponding REST API: GET /instances/{facet-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing Facet by its type name and unique identifier
• The Facet must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete Facet instance as JSON with all properties and metadata
• Type validation ensures the UUID corresponds to a Facet of the specified type.

HTTP Response Codes:

• 200 OK: Facet successfully retrieved
• 404 Not Found: No Facet found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the Facet 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: publisher.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: publisher.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: publisher.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: publisher.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 specified type must be a valid Facet type in the Information System model
• Supports all Facet types and their subtypes as defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a Facet of exactly the specified type (no polymorphic matching). *

Context Access:

• The Facet 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 Facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read a ContactFacet by type and UUID
 UUID facetUuid = UUID.fromString("...");
 String contactJson = publisher.readFacet("ContactFacet", facetUuid);
 

Parameters:

facetType - The exact type name of the Facet to read

uuid - The unique identifier of the Facet to read

Returns:

JSON representation of the complete Facet instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If no Facet is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetAvailableInAnotherContextException - If the Facet exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Facet retrieval

updateFacet

<F extends org.gcube.informationsystem.model.reference.entities.Facet>
F updateFacet(F facet)
       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing Facet instance in the Resource Registry. REST Endpoint: PUT /instances/{facet-type-name}/{facet-uuid} Request Examples:

• Basic update: ContactFacet updatedFacet = publisher.updateFacet(facetToUpdate);
• With metadata in response: publisher.includeMeta(true); ContactFacet updatedFacet = publisher.updateFacet(facetToUpdate);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); ContactFacet updatedFacet = publisher.updateFacet(facetToUpdate);
• With context information: publisher.includeContexts(true); ContactFacet updatedFacet = publisher.updateFacet(facetToUpdate);.

Update Behavior:

• Updates an existing Facet with new property values from the provided instance
• The Facet must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• The Facet UUID cannot be changed during update operations
• Associated Resources are automatically revalidated after Facet update
• The update affects all Resources that include this Facet via ConsistsOf relations.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response Facet
• Default value: false (basic information only)
• 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: publisher.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: publisher.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.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for Facets in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Facet successfully updated
• 400 Bad Request: Invalid Facet data or schema validation failed
• 404 Not Found: The Facet does not exist
• 403 Forbidden: Insufficient permissions to update the Facet.

Response Format:

• Returns the updated Facet object with its properties
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All properties are updated according to the current configuration.

Type Parameters:

F - The specific type of Facet to update

Parameters:

facet - The Facet instance with updated values (must contain valid UUID)

Returns:

The updated Facet object with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated Facet violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Facet update

updateFacet

String updateFacet(String facet)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing Facet instance in the Resource Registry using JSON representation. REST Endpoint: PUT /instances/{facet-type-name}/{facet-uuid} Request Examples:

• Basic update: String updatedFacet = publisher.updateFacet(facetJsonString);
• With metadata in response: publisher.includeMeta(true); String updatedFacet = publisher.updateFacet(facetJsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String updatedFacet = publisher.updateFacet(facetJsonString);
• With context information: publisher.includeContexts(true); String updatedFacet = publisher.updateFacet(facetJsonString);.

Update Behavior:

• Updates an existing Facet using JSON representation
• The JSON must contain the UUID of the Facet to update
• The Facet type is automatically detected from the JSON content
• The Facet must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• Associated Resources are automatically revalidated after Facet update
• The update affects all Resources that include this Facet via ConsistsOf relations.

JSON Format Requirements:

• Valid JSON representation of a Facet instance
• Must include the "id" field with the UUID of the Facet to update
• Must include the "@class" field to identify the Facet type
• Must conform to the schema of the specified Facet type.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response Facet
• Default value: false (basic information only)
• 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: publisher.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: publisher.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.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for Facets in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Facet successfully updated
• 400 Bad Request: Invalid JSON format, missing required fields, or schema validation failed
• 404 Not Found: The Facet does not exist
• 403 Forbidden: Insufficient permissions to update the Facet.

Response Format:

• Returns a JSON string containing the updated Facet
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All properties are updated according to the current configuration.

Parameters:

facet - JSON representation of the Facet to update

Returns:

JSON string containing the updated Facet with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated Facet violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Facet update

deleteFacet

<F extends org.gcube.informationsystem.model.reference.entities.Facet>
boolean deleteFacet(F facet)
             throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a Facet instance from the Resource Registry. Corresponding REST API: DELETE /instances/{facet-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified Facet instance from the Resource Registry
• The type and UUID are automatically extracted from the provided Facet object
• The Facet must exist and be accessible in the current context
• This is a destructive operation that cannot be undone
• Parent Resources that reference this Facet may also be affected based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Facet successfully deleted
• 404 Not Found: Facet does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the Facet
• 409 Conflict: Facet cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type name is automatically derived from the provided Facet object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Facet's header
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet).

Deletion Propagation Rules:

• Facets: When a Facet is deleted, parent Resources that reference it via ConsistsOf relations may also be affected
• Parent Resources: If the deleted Facet was required for a Resource's schema compliance, the Resource may become invalid or be automatically removed
• ConsistsOf Relations: All ConsistsOf relations connecting Resources to this Facet are automatically removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each Resource type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the Facet will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Facet that is required by an existing Resource; • Deleting Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that would make parent Resources incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the Facet exists.

IS-Manager:

• Can delete any Facet in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any Facet in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete Facets only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete Facets only in contexts where they have appropriate permissions
• Operations are limited to Facets they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete a ContactFacet instance
 ContactFacet contact = publisher.readFacet(ContactFacet.class, contactUUID);
 boolean deleted = publisher.deleteFacet(contact);
 
 // Delete a StateFacet instance
 StateFacet state = publisher.readFacet(StateFacet.class, stateUUID);
 boolean stateDeleted = publisher.deleteFacet(state);
 

Type Parameters:

F - The specific type of Facet to delete

Parameters:

facet - The Facet instance to delete (must contain a valid UUID in the header)

Returns:

true if the Facet was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the Facet would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

deleteFacet

boolean deleteFacet(String facetType,
 UUID uuid)
             throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a Facet instance from the Resource Registry using type name and UUID. Corresponding REST API: DELETE /instances/{facet-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified Facet instance from the Resource Registry
• The Facet is identified by its type name and UUID
• The Facet must exist and be accessible in the current context
• This is a destructive operation that cannot be undone
• Parent Resources that reference this Facet may also be affected based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Facet successfully deleted
• 404 Not Found: Facet does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the Facet
• 409 Conflict: Facet cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The facetType parameter must be a valid Facet type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet, SoftwareFacet)
• The UUID must be a valid UUID that identifies an existing Facet instance.

Deletion Propagation Rules:

• Facets: When a Facet is deleted, parent Resources that reference it via ConsistsOf relations may also be affected
• Parent Resources: If the deleted Facet was required for a Resource's schema compliance, the Resource may become invalid or be automatically removed
• ConsistsOf Relations: All ConsistsOf relations connecting Resources to this Facet are automatically removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each Resource type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the Facet will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Facet that is required by an existing Resource; • Deleting Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that would make parent Resources incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the Facet exists.

IS-Manager:

• Can delete any Facet in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any Facet in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete Facets only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete Facets only in contexts where they have appropriate permissions
• Operations are limited to Facets they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete a ContactFacet by type and UUID
 UUID contactUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 boolean deleted = publisher.deleteFacet("ContactFacet", contactUUID);
 
 // Delete a StateFacet by type and UUID
 UUID stateUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 boolean stateDeleted = publisher.deleteFacet("StateFacet", stateUUID);
 

Parameters:

facetType - The exact type name of the Facet to delete

uuid - The UUID of the Facet instance to delete

Returns:

true if the Facet was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the Facet would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

createResource

<R extends org.gcube.informationsystem.model.reference.entities.Resource>
R createResource(R resource)
          throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new Resource instance in the Resource Registry. Corresponding REST API: POST /instances/{resource-type-name} Operation Behavior:

• Creates a new Resource entity in the Information System
• Resources represent the main entities that can have Facets attached via ConsistsOf relations and can be connected to other Resources via IsRelatedTo relations
• The instance is automatically associated with the current context
• Validates the resource against the Information System model schema
• Generates a new UUID for the resource if not already set
• Returns the created resource with server-generated metadata.

HTTP Response Codes:

• 201 Created: Resource successfully created
• 400 Bad Request: Invalid resource data or schema validation failure
• 409 Conflict: Resource with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The resource type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Supports all Resource subtypes defined in the Information System model.

Schema Validation:

• All resource properties are validated against the Information System model
• Required properties must be present and valid
• Property types and constraints are enforced
• Resource-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create resources.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new EService resource
 EService service = new EService();
 ...
 EService createdService = publisher.createResource(service);
 
 // Create a new HostingNode resource
 HostingNode node = new HostingNode();
 ...
 HostingNode createdNode = publisher.createResource(node);
 

Type Parameters:

R - The specific type of Resource to create

Parameters:

resource - The Resource instance to create in the Resource Registry

Returns:

The created Resource with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the resource violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAlreadyPresentException - If a resource with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during resource creation

createResource

String createResource(String resource)
               throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new Resource instance from JSON representation. Corresponding REST API: POST /instances/{resource-type-name} Operation Behavior:

• Creates a new Resource entity from JSON representation
• Resources represent the main entities that can have Facets attached via ConsistsOf relations and can be connected to other Resources via IsRelatedTo relations
• The instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the resource if not already set
• Returns the created resource as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: Resource successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: Resource with the same UUID already exists
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying a Resource type
• Must conform to the Information System model JSON schema for Resources
• All required properties for the specified resource type must be present
• Resource-specific properties must be properly formatted.

Schema Validation:

• JSON structure is validated against the Information System model
• Required resource properties must be present and valid
• Property types and constraints are enforced
• Resource-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• All users must have a valid token and write permissions for the specific context where they want to create resources.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a new EService from JSON
 String serviceJson = "...";
 String createdServiceJson = publisher.createResource(serviceJson);
 
 // Create a new HostingNode from JSON
 String nodeJson = "...";
 String createdNodeJson = publisher.createResource(nodeJson);
 

Parameters:

resource - JSON representation of the Resource to create

Returns:

JSON representation of the created Resource with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAlreadyPresentException - If a resource with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during resource creation or JSON parsing

readResource

<R extends org.gcube.informationsystem.model.reference.entities.Resource>
R readResource(R resource)
        throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a Resource instance from the Resource Registry using a provided instance object. Corresponding REST API: GET /instances/{resource-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing Resource by extracting type and UUID from the provided instance
• The Resource must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete Resource instance with all properties, ConsistsOf relations, and metadata
• The type is automatically determined from the provided instance object.

HTTP Response Codes:

• 200 OK: Resource successfully retrieved
• 404 Not Found: No Resource found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks read permissions for the Resource 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: publisher.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: publisher.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: publisher.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: publisher.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 Resource type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header
• The returned object will be of the same Resource type as the provided instance.

Context Access:

• The Resource 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 resources.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource
 EService eService = new EService();
 eService.setHeader(new Header(uuid));
 EService readEService = publisher.readResource(eService);
 

Type Parameters:

R - The specific type of Resource to read

Parameters:

resource - Instance object containing at least the UUID in the header

Returns:

The complete Resource instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If no Resource is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAvailableInAnotherContextException - If the Resource exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Resource retrieval

readResource

String readResource(String resourceType,
 UUID uuid)
             throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a Resource instance from the Resource Registry by its type and UUID. Corresponding REST API: GET /instances/{resource-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing Resource by its type name and unique identifier
• The Resource must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete Resource instance as JSON with all properties, ConsistsOf relations, and metadata
• Type validation ensures the UUID corresponds to a Resource of the specified type.

HTTP Response Codes:

• 200 OK: Resource successfully retrieved
• 404 Not Found: No Resource found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the Resource 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: publisher.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: publisher.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: publisher.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: publisher.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 specified type must be a valid Resource type in the Information System model
• Supports Resource subtypes defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a Resource of exactly the specified type (no polymorphic matching).

Context Access:

• The Resource 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 resources.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an EService Resource by type and UUID
 UUID resourceUuid = UUID.fromString("...");
 String serviceJson = publisher.readResource("EService", resourceUuid);
 

Parameters:

resourceType - The exact type name of the Resource to read

uuid - The unique identifier of the Resource to read

Returns:

JSON representation of the complete Resource instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If no Resource is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceAvailableInAnotherContextException - If the Resource exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Resource retrieval

updateResource

<R extends org.gcube.informationsystem.model.reference.entities.Resource>
R updateResource(R resource)
          throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing Resource instance in the Resource Registry. REST Endpoint: PUT /instances/{resource-type-name}/{resource-uuid} Request Examples:

• Basic update: EService updatedResource = publisher.updateResource(resourceToUpdate);
• With metadata in response: publisher.includeMeta(true); EService updatedResource = publisher.updateResource(resourceToUpdate);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); EService updatedResource = publisher.updateResource(resourceToUpdate);
• With context information: publisher.includeContexts(true); EService updatedResource = publisher.updateResource(resourceToUpdate);.

Update Behavior:

• Updates an existing Resource with new property values from the provided instance
• The Resource must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• The Resource UUID cannot be changed during update operations
• Associated Facets via ConsistsOf relations are preserved unless explicitly modified
• Existing ConsistsOf relations and their target Facets remain unchanged unless modified through separate operations.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response Resource
• Default value: false (basic information only)
• 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: publisher.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: publisher.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.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for Resources in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Resource successfully updated
• 400 Bad Request: Invalid Resource data or schema validation failed
• 404 Not Found: The Resource does not exist
• 403 Forbidden: Insufficient permissions to update the Resource.

Response Format:

• Returns the updated Resource object with its properties and relations
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are included according to the current configuration.

Type Parameters:

R - The specific type of Resource to update

Parameters:

resource - The Resource instance with updated values (must contain valid UUID)

Returns:

The updated Resource object with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated Resource violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Resource update

updateResource

String updateResource(String resource)
               throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing Resource instance in the Resource Registry using JSON representation. REST Endpoint: PUT /instances/{resource-type-name}/{resource-uuid} Request Examples:

• Basic update: String updatedResource = publisher.updateResource(resourceJsonString);
• With metadata in response: publisher.includeMeta(true); String updatedResource = publisher.updateResource(resourceJsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String updatedResource = publisher.updateResource(resourceJsonString);
• With context information: publisher.includeContexts(true); String updatedResource = publisher.updateResource(resourceJsonString);.

Update Behavior:

• Updates an existing Resource using JSON representation
• The JSON must contain the UUID of the Resource to update
• The Resource type is automatically detected from the JSON content
• The Resource must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• Associated Facets via ConsistsOf relations are preserved unless explicitly modified
• Existing ConsistsOf relations and their target Facets remain unchanged unless modified through separate operations.

JSON Format Requirements:

• Valid JSON representation of a Resource instance
• Must include the "id" field with the UUID of the Resource to update
• Must include the "@class" field to identify the Resource type
• Must conform to the schema of the specified Resource type
• ConsistsOf relations should be included if they need to be updated.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response Resource
• Default value: false (basic information only)
• 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: publisher.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: publisher.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.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for Resources in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: Resource successfully updated
• 400 Bad Request: Invalid JSON format, missing required fields, or schema validation failed
• 404 Not Found: The Resource does not exist
• 403 Forbidden: Insufficient permissions to update the Resource.

Response Format:

• Returns a JSON string containing the updated Resource
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are included according to the current configuration.

Parameters:

resource - JSON representation of the Resource to update

Returns:

JSON string containing the updated Resource with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated Resource violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during Resource update

deleteResource

<R extends org.gcube.informationsystem.model.reference.entities.Resource>
boolean deleteResource(R resource)
                throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a Resource instance from the Resource Registry. Corresponding REST API: DELETE /instances/{resource-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified Resource instance from the Resource Registry
• The type and UUID are automatically extracted from the provided Resource object
• The Resource must exist and be accessible in the current context
• This is a destructive operation that cannot be undone
• Associated Facets and ConsistsOf relations may also be deleted based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Resource successfully deleted
• 404 Not Found: Resource does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the Resource
• 409 Conflict: Resource cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type name is automatically derived from the provided Resource object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Resource's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software, Dataset).

Deletion Propagation Rules:

• Resources: When a Resource is deleted, all its associated Facets (via ConsistsOf relations) may also be deleted if they become orphaned and the delete propagation constraint is propagate
• Associated Facets: Facets connected to the Resource via ConsistsOf relations are automatically removed if no other Resources reference them
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are automatically removed
• IsRelatedTo Relations: IsRelatedTo relations where this Resource is source or target are automatically removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each Resource type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the Resource will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Resource that is required by other Resources via IsRelatedTo relations; • Deleting Resources that violate cardinality constraints (min occurrences) defined in the schema; • Operations that would make related Resources incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the Resource exists.

IS-Manager:

• Can delete any Resource in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any Resource in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete Resources only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete Resources only in contexts where they have appropriate permissions
• Operations are limited to Resources they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an EService instance
 EService service = publisher.readResource(EService.class, serviceUUID);
 boolean deleted = publisher.deleteResource(service);
 
 // Delete a HostingNode instance
 HostingNode host = publisher.readResource(HostingNode.class, hostUUID);
 boolean hostDeleted = publisher.deleteResource(host);
 

Type Parameters:

R - The specific type of Resource to delete

Parameters:

resource - The Resource instance to delete (must contain a valid UUID in the header)

Returns:

true if the Resource was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

deleteResource

boolean deleteResource(String resourceType,
 UUID uuid)
                throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a Resource instance from the Resource Registry using type name and UUID. Corresponding REST API: DELETE /instances/{resource-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified Resource instance from the Resource Registry
• The Resource is identified by its type name and UUID
• The Resource must exist and be accessible in the current context
• This is a destructive operation that cannot be undone
• Associated Facets and ConsistsOf relations may also be deleted based on propagation constraints defined in the schema.

HTTP Response Codes:

• 200 OK: Resource successfully deleted
• 404 Not Found: Resource does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the Resource
• 409 Conflict: Resource cannot be deleted due to existing relationships or schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The resourceType parameter must be a valid Resource type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software, Dataset, VirtualMachine)
• The UUID must be a valid UUID that identifies an existing Resource instance.

Deletion Propagation Rules:

• Resources: When a Resource is deleted, all its associated Facets (via ConsistsOf relations) may also be deleted if they become orphaned and the delete propagation constraint is propagate
• Associated Facets: Facets connected to the Resource via ConsistsOf relations are automatically removed if no other Resources reference them
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are automatically removed
• IsRelatedTo Relations: IsRelatedTo relations where this Resource is source or target are automatically removed
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for each Resource type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the Resource will not violate schema constraints
• If deletion would leave required relationships unsatisfied or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a Resource that is required by other Resources via IsRelatedTo relations; • Deleting Resources that violate cardinality constraints (min occurrences) defined in the schema; • Operations that would make related Resources incomplete according to their schema definition. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the Resource exists.

IS-Manager:

• Can delete any Resource in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any Resource in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete Resources only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete Resources only in contexts where they have appropriate permissions
• Operations are limited to Resources they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an EService by type and UUID
 UUID serviceUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 boolean deleted = publisher.deleteResource("EService", serviceUUID);
 
 // Delete a HostingNode by type and UUID
 UUID hostUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 boolean hostDeleted = publisher.deleteResource("HostingNode", hostUUID);
 

Parameters:

resourceType - The exact type name of the Resource to delete

uuid - The UUID of the Resource instance to delete

Returns:

true if the Resource was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

createConsistsOf

<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Facet>>
C createConsistsOf(C consistsOf)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new ConsistsOf relation instance in the Resource Registry. Corresponding REST API: POST /instances/{consistsof-type-name} Operation Behavior:

• Creates a new ConsistsOf relation between a Resource and a Facet
• ConsistsOf relations represent the composition relationship where a Resource consists of one or more Facets
• The relation instance is automatically associated with the current context
• Validates the relation against the Information System model schema
• Generates a new UUID for the relation if not already set
• Returns the created relation with server-generated metadata.

HTTP Response Codes:

• 201 Created: ConsistsOf relation successfully created
• 400 Bad Request: Invalid relation data or schema validation failure
• 409 Conflict: ConsistsOf relation with the same UUID already exists
• 404 Not Found: Source Resource or target Facet does not exist
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The relation type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Supports ConsistsOf types and subtypes defined in the Information System model

Schema Validation:

• All relation properties are validated against the Information System model
• Source and target entities must exist and be accessible in compatible contexts
• Relation constraints and cardinality rules are enforced
• ConsistsOf-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• User must have write permissions in the current context
• Both source Resource and target Facet must be available in the current context.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a ConsistsOf relation between an EService and ContactFacet
 IsIdentifiedBy<EService, ContactFacet> identifiedBy = new IsIdentifiedBy<>();
 identifiedBy.setSource(eservice);
 identifiedBy.setTarget(contact);
 ...
 IsIdentifiedBy<EService, ContactFacet> createdRelation = publisher.createConsistsOf(identifiedBy);
 

Type Parameters:

C - The specific type of ConsistsOf relation to create

Parameters:

consistsOf - The ConsistsOf relation instance to create in the Resource Registry

Returns:

The created ConsistsOf relation with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the relation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAlreadyPresentException - If a relation with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the source Resource or target Facet does not exist (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation creation

createConsistsOf

String createConsistsOf(String consistsOf)
                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new ConsistsOf relation instance from JSON representation. Corresponding REST API: POST /instances/{consistsof-type-name} Operation Behavior:

• Creates a new ConsistsOf relation between a Resource and a Facet from JSON representation
• ConsistsOf relations represent the composition relationship where a Resource consists of one or more Facets
• The relation instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the relation if not already set
• Returns the created relation as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: ConsistsOf relation successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: ConsistsOf relation with the same UUID already exists
• 404 Not Found: Source Resource or target Facet does not exist
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying a ConsistsOf type
• Must conform to the Information System model JSON schema for ConsistsOf relations
• Must include valid source and target references
• All required properties for the specified relation type must be present.

Schema Validation:

• JSON structure is validated against the Information System model
• Source and target entity references are validated
• Relation constraints and cardinality rules are enforced
• ConsistsOf-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• User must have write permissions in the current context
• Both source Resource and target Facet must be available in the current context.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create a ConsistsOf relation from JSON
 String consistsOfJson = "...";
 String createdRelationJson = publisher.createConsistsOf(consistsOfJson);
 

Parameters:

consistsOf - JSON representation of the ConsistsOf relation to create

Returns:

JSON representation of the created ConsistsOf relation with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAlreadyPresentException - If a relation with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the source Resource or target Facet does not exist (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation creation or JSON parsing

readConsistsOf

<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Facet>>
C readConsistsOf(C consistsOf)
          throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a ConsistsOf relation instance from the Resource Registry using a provided instance object. Corresponding REST API: GET /instances/{consistsof-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing ConsistsOf relation by extracting type and UUID from the provided instance
• The relation must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete ConsistsOf relation with source Resource, target Facet, and all properties
• The type is automatically determined from the provided instance object.

HTTP Response Codes:

• 200 OK: ConsistsOf relation successfully retrieved
• 404 Not Found: No ConsistsOf relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks read permissions for the relation 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: publisher.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: publisher.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: publisher.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: publisher.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 ConsistsOf type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The UUID is extracted from the provided instance's header
• The returned object will be of the same ConsistsOf relation type as the provided instance.

Context Access:

• The ConsistsOf relation 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.

Relation Context:

• ConsistsOf relations represent aggregation relationships between Resources and Facets
• The source of the relation is always a Resource, the target is always a Facet
• The relation defines how a Resource is composed of various Facets.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read a ConsistsOf relation
 ConsistsOf<EService, SoftwareFacet> co = new ConsistsOf<>();
 co.setHeader(new Header(uuid));
 ConsistsOf<EService, SoftwareFacet> readCO = publisher.readConsistsOf(co);
 

Type Parameters:

C - The specific type of ConsistsOf relation to read

Parameters:

consistsOf - Instance object containing at least the UUID in the header

Returns:

The complete ConsistsOf relation instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If no ConsistsOf relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAvailableInAnotherContextException - If the relation exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation retrieval

readConsistsOf

String readConsistsOf(String consistsOfType,
 UUID uuid)
               throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads a ConsistsOf relation instance from the Resource Registry by its type and UUID. Corresponding REST API: GET /instances/{consistsof-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing ConsistsOf relation by its type name and unique identifier
• The relation must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete ConsistsOf relation as JSON with source Resource, target Facet, and all properties
• Type validation ensures the UUID corresponds to a ConsistsOf relation of the specified type.

HTTP Response Codes:

• 200 OK: ConsistsOf relation successfully retrieved
• 404 Not Found: No ConsistsOf relation found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the relation 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: publisher.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: publisher.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: publisher.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: publisher.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 specified type must be a valid ConsistsOf relation type in the Information System model
• Supports all ConsistsOf relation types and their subtypes as defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a ConsistsOf relation of exactly the specified type (no polymorphic matching).

Context Access:

• The ConsistsOf relation 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.

Relation Context:

• ConsistsOf relations represent aggregation relationships between Resources and Facets
• The JSON response includes source Resource reference, target Facet reference, and relation properties
• Relation cardinality and constraints are validated according to the Information System model.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read a ConsistsOf relation by type and UUID
 UUID relationUuid = UUID.fromString("...");
 String relationJson = publisher.readConsistsOf("ConsistsOf", relationUuid);
 

Parameters:

consistsOfType - The exact type name of the ConsistsOf relation to read

uuid - The unique identifier of the ConsistsOf relation to read

Returns:

JSON representation of the complete ConsistsOf relation instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If no ConsistsOf relation is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfAvailableInAnotherContextException - If the relation exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation retrieval

updateConsistsOf

<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Facet>>
C updateConsistsOf(C consistsOf)
            throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing ConsistsOf relation instance in the Resource Registry. REST Endpoint: PUT /instances/{consistsof-type-name}/{consistsof-uuid} Request Examples:

• Basic update: ConsistsOf updatedRelation = publisher.updateConsistsOf(relationToUpdate);
• With metadata in response: publisher.includeMeta(true); ConsistsOf updatedRelation = publisher.updateConsistsOf(relationToUpdate);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); ConsistsOf updatedRelation = publisher.updateConsistsOf(relationToUpdate);
• With context information: publisher.includeContexts(true); ConsistsOf updatedRelation = publisher.updateConsistsOf(relationToUpdate);.

Update Behavior:

• Updates an existing ConsistsOf relation with new property values from the provided instance
• The ConsistsOf relation must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• The ConsistsOf UUID cannot be changed during update operations
• Source Resource and target Facet cannot be changed during update (only properties)
• The source Resource is automatically revalidated after ConsistsOf update to ensure schema compliance.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response ConsistsOf relation
• Default value: false (basic information only)
• 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: publisher.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: publisher.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.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for ConsistsOf relations in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: ConsistsOf relation successfully updated
• 400 Bad Request: Invalid relation data or schema validation failed
• 404 Not Found: The ConsistsOf relation does not exist
• 403 Forbidden: Insufficient permissions to update the ConsistsOf relation.

Response Format:

• Returns the updated ConsistsOf relation object with its properties
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are included according to the current configuration.

Type Parameters:

C - The specific type of ConsistsOf relation to update

Parameters:

consistsOf - The ConsistsOf relation instance with updated values (must contain valid UUID)

Returns:

The updated ConsistsOf relation object with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated ConsistsOf relation violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If the ConsistsOf relation to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during ConsistsOf relation update

updateConsistsOf

String updateConsistsOf(String consistsOf)
                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing ConsistsOf relation instance in the Resource Registry using JSON representation. REST Endpoint: PUT /instances/{consistsof-type-name}/{consistsof-uuid} Request Examples:

• Basic update: String updatedRelation = publisher.updateConsistsOf(relationJsonString);
• With metadata in response: publisher.includeMeta(true); String updatedRelation = publisher.updateConsistsOf(relationJsonString);
• Full metadata context: publisher.includeMeta(true); publisher.allMeta(true); String updatedRelation = publisher.updateConsistsOf(relationJsonString);
• With context information: publisher.includeContexts(true); String updatedRelation = publisher.updateConsistsOf(relationJsonString);.

Update Behavior:

• Updates an existing ConsistsOf relation using JSON representation
• The JSON must contain the UUID of the ConsistsOf relation to update
• The ConsistsOf type is automatically detected from the JSON content
• The ConsistsOf relation must already exist in the Resource Registry
• All modifiable properties are updated; metadata fields are automatically managed
• Source Resource and target Facet cannot be changed during update (only properties)
• The source Resource is automatically revalidated after ConsistsOf update to ensure schema compliance.

JSON Format Requirements:

• Valid JSON representation of a ConsistsOf relation instance
• Must include the "id" field with the UUID of the ConsistsOf relation to update
• Must include the "@class" field to identify the ConsistsOf type
• Must conform to the schema of the specified ConsistsOf type
• Source and target references should remain unchanged.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response ConsistsOf relation
• Default value: false (basic information only)
• 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: publisher.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: publisher.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.

Authorization Requirements:

• Valid authorization token required for accessing the current context
• Update permissions required for ConsistsOf relations in the current context
• The current context is derived from the authorization token provided during client creation.

Response Codes:

• 200 OK: ConsistsOf relation successfully updated
• 400 Bad Request: Invalid JSON format, missing required fields, or schema validation failed
• 404 Not Found: The ConsistsOf relation does not exist
• 403 Forbidden: Insufficient permissions to update the ConsistsOf relation.

Response Format:

• Returns a JSON string containing the updated ConsistsOf relation
• Response structure depends on includeMeta, allMeta, and includeContexts settings
• All nested elements are included according to the current configuration.

Parameters:

consistsOf - JSON representation of the ConsistsOf relation to update

Returns:

JSON string containing the updated ConsistsOf relation with current data from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated ConsistsOf relation violates type schema constraints

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If the ConsistsOf relation to update does not exist

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during ConsistsOf relation update

deleteConsistsOf

<C extends org.gcube.informationsystem.model.reference.relations.ConsistsOf<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Facet>>
boolean deleteConsistsOf(C consistsOf)
                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a ConsistsOf relation instance from the Resource Registry. Corresponding REST API: DELETE /instances/{consistsof-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified ConsistsOf relation instance from the Resource Registry
• The type and UUID are automatically extracted from the provided ConsistsOf object
• The ConsistsOf relation must exist and be accessible in the current context
• This operation removes the relationship between a Resource and a Facet
• This is a destructive operation that cannot be undone
• The connected Resource and Facet elements may be affected based on propagation constraints.

HTTP Response Codes:

• 200 OK: ConsistsOf relation successfully deleted
• 404 Not Found: ConsistsOf relation does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the ConsistsOf relation
• 409 Conflict: ConsistsOf relation cannot be deleted due to schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The type name is automatically derived from the provided ConsistsOf object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the ConsistsOf relation's header
• Supports all ConsistsOf relation types and their specializations.

Deletion Effects and Propagation:

• ConsistsOf Relations: When a ConsistsOf relation is deleted, the relationship between the Resource and Facet is removed
• Connected Resource: The source Resource remains but loses the connection to the target Facet
• Connected Facet: The target Facet may become orphaned if this was its only connection to a Resource
• Orphaned Facets: Facets that become orphaned (not connected to any Resource) may be automatically deleted based on schema configuration
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for the specific ConsistsOf type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the ConsistsOf relation will not violate schema constraints
• If deletion would leave the Resource incomplete or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a ConsistsOf relation to a required Facet (violates min cardinality); • Removing mandatory relationships that make the Resource invalid according to its schema; • Operations that would violate schema-defined constraints for the Resource type. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the ConsistsOf relation exists.

IS-Manager:

• Can delete any ConsistsOf relation in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any ConsistsOf relation in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete ConsistsOf relations only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete ConsistsOf relations only in contexts where they have appropriate permissions
• Operations are limited to relations they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete a ConsistsOf relation instance
 ConsistsOf<EService, StateFacet> consistsOf = publisher.readConsistsOf(ConsistsOf.class, relationUUID);
 boolean deleted = publisher.deleteConsistsOf(consistsOf);
 
 // Delete a specific ConsistsOf relation between a HostingNode and a StateFacet
 ConsistsOf<HostingNode, StateFacet> hostState = publisher.readConsistsOf(ConsistsOf.class, hostStateUUID);
 boolean relationDeleted = publisher.deleteConsistsOf(hostState);
 

Type Parameters:

C - The specific type of ConsistsOf relation to delete

Parameters:

consistsOf - The ConsistsOf relation instance to delete (must contain a valid UUID in the header)

Returns:

true if the ConsistsOf relation was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the ConsistsOf relation would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If the ConsistsOf relation does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

deleteConsistsOf

boolean deleteConsistsOf(String consistsOfType,
 UUID uuid)
                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes a ConsistsOf relation instance from the Resource Registry using type name and UUID. Corresponding REST API: DELETE /instances/{consistsof-type-name}/{uuid} Operation Behavior:

• Permanently deletes the specified ConsistsOf relation instance from the Resource Registry
• The ConsistsOf relation is identified by its type name and UUID
• The ConsistsOf relation must exist and be accessible in the current context
• This operation removes the relationship between a Resource and a Facet
• This is a destructive operation that cannot be undone
• The connected Resource and Facet elements may be affected based on propagation constraints.

HTTP Response Codes:

• 200 OK: ConsistsOf relation successfully deleted
• 404 Not Found: ConsistsOf relation does not exist or is not accessible in the current context
• 403 Forbidden: User lacks permissions to delete the ConsistsOf relation
• 409 Conflict: ConsistsOf relation cannot be deleted due to schema constraints
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The consistsOfType parameter must be a valid ConsistsOf relation type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all ConsistsOf relation types and their specializations
• The UUID must be a valid UUID that identifies an existing ConsistsOf relation instance.

Deletion Effects and Propagation:

• ConsistsOf Relations: When a ConsistsOf relation is deleted, the relationship between the Resource and Facet is removed
• Connected Resource: The source Resource remains but loses the connection to the target Facet
• Connected Facet: The target Facet may become orphaned if this was its only connection to a Resource
• Orphaned Facets: Facets that become orphaned (not connected to any Resource) may be automatically deleted based on schema configuration
• Cascade Effects: The actual propagation behavior depends on the schema-defined constraints for the specific ConsistsOf type.

Schema Validation and Constraints:

• Before deletion, the system validates that removing the ConsistsOf relation will not violate schema constraints
• If deletion would leave the Resource incomplete or violate cardinality constraints, a SchemaViolationException is thrown
• This results in an HTTP 409 Conflict response with details about the constraint violation
• Example scenarios that prevent deletion:

• Deleting a ConsistsOf relation to a required Facet (violates min cardinality); • Removing mandatory relationships that make the Resource invalid according to its schema; • Operations that would violate schema-defined constraints for the Resource type. Authorization Requirements:

• All users must have a valid token and delete permissions for the specific context where the ConsistsOf relation exists.

IS-Manager:

• Can delete any ConsistsOf relation in any context
• Full administrative privileges across all contexts.

Infrastructure-Manager:

• Can delete any ConsistsOf relation in any context
• Full administrative privileges across all contexts.

Context-Manager:

• Can delete ConsistsOf relations only in contexts where they have Context-Manager role
• Operations are limited to their assigned contexts.

Other Users:

• Can delete ConsistsOf relations only in contexts where they have appropriate permissions
• Operations are limited to relations they have access to in their authorized contexts.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete a ConsistsOf relation by type and UUID
 UUID relationUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 boolean deleted = publisher.deleteConsistsOf("ConsistsOf", relationUUID);
 
 // Delete a specific ConsistsOf relation type
 UUID specificRelationUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 boolean relationDeleted = publisher.deleteConsistsOf("SpecificConsistsOfType", specificRelationUUID);
 

Parameters:

consistsOfType - The exact type name of the ConsistsOf relation to delete

uuid - The UUID of the ConsistsOf relation instance to delete

Returns:

true if the ConsistsOf relation was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If deleting the ConsistsOf relation would violate Information System model constraints (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.consistsof.ConsistsOfNotFoundException - If the ConsistsOf relation does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the delete operation

createIsRelatedTo

<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Resource>>
I createIsRelatedTo(I isRelatedTo)
             throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new IsRelatedTo relation instance in the Resource Registry. Corresponding REST API: POST /instances/{isrelatedto-type-name} Operation Behavior:

• Creates a new IsRelatedTo relation between two Resources
• IsRelatedTo relations represent various types of relationships between Resources (e.g., dependency, hosting, derivation)
• The relation instance is automatically associated with the current context
• Validates the relation against the Information System model schema
• Generates a new UUID for the relation if not already set
• Returns the created relation with server-generated metadata.

HTTP Response Codes:

• 201 Created: IsRelatedTo relation successfully created
• 400 Bad Request: Invalid relation data or schema validation failure
• 409 Conflict: IsRelatedTo relation with the same UUID already exists
• 404 Not Found: Source Resource or target Resource does not exist
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The relation type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Supports all IsRelatedTo subtypes defined in the Information System model.

Schema Validation:

• All relation properties are validated against the Information System model
• Source and target Resources must exist and be accessible in compatible contexts
• Relation constraints and cardinality rules are enforced
• IsRelatedTo-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• User must have write permissions in the current context
• Both source and target Resources must be available in the current context.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create an IsRelatedTo relation between two EServices
 Activates<EService, EService> activates = new Activates<>();
 activates.setSource(sourceService);
 activates.setTarget(targetService);
 ...
 Activates<EService, EService> createdRelation = publisher.createIsRelatedTo(activates);
 

Type Parameters:

I - The specific type of IsRelatedTo relation to create

Parameters:

isRelatedTo - The IsRelatedTo relation instance to create in the Resource Registry

Returns:

The created IsRelatedTo relation with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the relation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAlreadyPresentException - If a relation with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the source or target Resource does not exist (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation creation

createIsRelatedTo

String createIsRelatedTo(String isRelatedTo)
                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAlreadyPresentException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Creates a new IsRelatedTo relation instance from JSON representation. Corresponding REST API: POST /instances/{isrelatedto-type-name} Operation Behavior:

• Creates a new IsRelatedTo relation between two Resources from JSON representation
• IsRelatedTo relations represent various types of relationships between Resources (e.g., dependency, hosting, derivation)
• The relation instance is automatically associated with the current context
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Generates a new UUID for the relation if not already set
• Returns the created relation as JSON with server-generated metadata.

HTTP Response Codes:

• 201 Created: IsRelatedTo relation successfully created
• 400 Bad Request: Invalid JSON data or schema validation failure
• 409 Conflict: IsRelatedTo relation with the same UUID already exists
• 404 Not Found: Source Resource or target Resource does not exist
• 403 Forbidden: User lacks write permissions in the current context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying an IsRelatedTo type
• Must conform to the Information System model JSON schema for IsRelatedTo relations
• Must include valid source and target Resource references
• All required properties for the specified relation type must be present.

Schema Validation:

• JSON structure is validated against the Information System model
• Source and target Resource references are validated
• Relation constraints and cardinality rules are enforced
• IsRelatedTo-specific validation rules are applied.

Context Access:

• The instance is automatically associated with the current context.

Authorization Requirements:

• User must have write permissions in the current context
• Both source and target Resources must be available in the current context.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Create an IsRelatedTo relation from JSON
 String isRelatedToJson = "...";
 String createdRelationJson = publisher.createIsRelatedTo(isRelatedToJson);
 

Parameters:

isRelatedTo - JSON representation of the IsRelatedTo relation to create

Returns:

JSON representation of the created IsRelatedTo relation with server-generated metadata and UUID

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAlreadyPresentException - If a relation with the same UUID already exists (HTTP 409)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the source or target Resource does not exist (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation creation or JSON parsing

readIsRelatedTo

<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Resource>>
I readIsRelatedTo(I isRelatedTo)
           throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads an IsRelatedTo relation instance from the Resource Registry by its UUID. Corresponding REST API: GET /instances/{isrelatedto-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing IsRelatedTo relation by its unique identifier
• The relation must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete relation instance with all properties and metadata
• The type is automatically determined from the provided object instance.

HTTP Response Codes:

• 200 OK: IsRelatedTo relation successfully retrieved
• 404 Not Found: No IsRelatedTo relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks read permissions for the relation 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: publisher.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: publisher.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: publisher.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: publisher.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 relation type is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• The returned object will be of the same type as the provided instance.

Context Access:

• The relation 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.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an Activates relation
 Activates<EService, EService> activates = new Activates<>();
 activates.setHeader(new Header(uuid));
 Activates<EService, EService> readActivates = publisher.readIsRelatedTo(activates);
 

Type Parameters:

I - The specific type of IsRelatedTo relation to read

Parameters:

isRelatedTo - Instance object containing at least the UUID in the header

Returns:

The complete IsRelatedTo relation instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no IsRelatedTo relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAvailableInAnotherContextException - If the IsRelatedTo relation is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation retrieval

readIsRelatedTo

String readIsRelatedTo(String isRelatedToType,
 UUID uuid)
                throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAvailableInAnotherContextException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Reads an IsRelatedTo relation instance from the Resource Registry by its type and UUID. Corresponding REST API: GET /instances/{isrelatedto-type-name}/{uuid}[?includeMeta={true|false}&allMeta={true|false}&includeContexts={true|false}&hierarchical={true|false}] Operation Behavior:

• Retrieves an existing IsRelatedTo relation by its type name and unique identifier
• The relation must be accessible in the current context or in child contexts (based on hierarchical mode)
• Returns the complete relation instance as JSON with all properties and metadata
• Type validation ensures the UUID corresponds to a relation of the specified type.

HTTP Response Codes:

• 200 OK: IsRelatedTo relation successfully retrieved
• 404 Not Found: No IsRelatedTo relation found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks read permissions for the relation 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: publisher.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: publisher.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: publisher.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: publisher.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 specified type must be a valid IsRelatedTo type in the Information System model
• Supports all IsRelatedTo types and their subtypes as defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a relation of exactly the specified type (no polymorphic matching). *

Context Access:

• The relation 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.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Read an Activates relation by type and UUID
 UUID relationUuid = UUID.fromString("...");
 String relationJson = publisher.readIsRelatedTo("Activates", relationUuid);
 

Parameters:

isRelatedToType - The exact type name of the IsRelatedTo relation to read

uuid - The unique identifier of the IsRelatedTo relation to read

Returns:

JSON representation of the complete IsRelatedTo relation instance from the Resource Registry

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToAvailableInAnotherContextException - If the relation exists but is not accessible in the current context (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation retrieval

updateIsRelatedTo

<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Resource>>
I updateIsRelatedTo(I isRelatedTo)
             throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing IsRelatedTo relation instance in the Resource Registry. Corresponding REST API: PUT /instances/{isrelatedto-type-name}/{uuid} Operation Behavior:

• Updates an existing IsRelatedTo relation with new property values
• The relation must exist and be accessible in the current context
• All provided properties will replace the existing ones (full update, not partial)
• Validates the updated relation against the Information System model schema
• Preserves the original UUID and creation metadata
• Returns the updated relation with current metadata.

HTTP Response Codes:

• 200 OK: IsRelatedTo relation successfully updated
• 400 Bad Request: Invalid relation data or schema validation failure
• 404 Not Found: No IsRelatedTo relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks write permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The relation type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Type cannot be changed during update (UUID must correspond to existing relation of same type).

Schema Validation:

• All relation properties are validated against the Information System model
• Source and target Resources must exist and be accessible in compatible contexts
• Relation constraints and cardinality rules are enforced
• IsRelatedTo-specific validation rules are applied.

Update Behavior:

• This is a complete replacement of the relation (not a merge)
• All properties not specified in the update will be lost
• Source and target Resource references can be changed if valid
• Context association cannot be changed through update.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Update an Activates relation
 Activates<EService, EService> relation = ...; // Retrieved relation
 // Modify properties
 relation.setStartTime(...);
 Activates<EService, EService> updatedRelation = publisher.updateIsRelatedTo(relation);
 

Type Parameters:

I - The specific type of IsRelatedTo relation to update

Parameters:

isRelatedTo - The IsRelatedTo relation instance with updated values

Returns:

The updated IsRelatedTo relation with current server metadata

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the updated relation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation update

updateIsRelatedTo

String updateIsRelatedTo(String isRelatedTo)
                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Updates an existing IsRelatedTo relation instance from JSON representation. Corresponding REST API: PUT /instances/{isrelatedto-type-name}/{uuid} Operation Behavior:

• Updates an existing IsRelatedTo relation with new property values from JSON representation
• The relation must exist and be accessible in the current context
• All provided properties will replace the existing ones (full update, not partial)
• Validates the JSON against the Information System model schema
• Type is determined from the JSON @class property
• Preserves the original UUID and creation metadata
• Returns the updated relation as JSON with current metadata.

HTTP Response Codes:

• 200 OK: IsRelatedTo relation successfully updated
• 400 Bad Request: Invalid JSON data or schema validation failure
• 404 Not Found: No IsRelatedTo relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks write permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

JSON Format Requirements:

• Must contain a valid @class property specifying an IsRelatedTo type
• Must contain a valid header with the UUID of the relation to update
• Must conform to the Information System model JSON schema for IsRelatedTo relations
• Must include valid source and target Resource references
• All required properties for the specified relation type must be present.

Schema Validation:

• JSON structure is validated against the Information System model
• Source and target Resource references are validated
• Relation constraints and cardinality rules are enforced
• IsRelatedTo-specific validation rules are applied.

Update Behavior:

• This is a complete replacement of the relation (not a merge)
• All properties not specified in the JSON will be lost
• Source and target Resource references can be changed if valid
• Context association cannot be changed through update.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Update an IsRelatedTo relation from JSON
 String updatedRelationJson = "..."; // JSON with same UUID but updated properties
 String resultJson = publisher.updateIsRelatedTo(updatedRelationJson);
 

Parameters:

isRelatedTo - JSON representation of the IsRelatedTo relation with updated values

Returns:

JSON representation of the updated IsRelatedTo relation with current server metadata

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the JSON violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation update or JSON parsing

deleteIsRelatedTo

<I extends org.gcube.informationsystem.model.reference.relations.IsRelatedTo<? extends org.gcube.informationsystem.model.reference.entities.Resource,
? extends org.gcube.informationsystem.model.reference.entities.Resource>>
boolean deleteIsRelatedTo(I isRelatedTo)
                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes an IsRelatedTo relation instance from the Resource Registry. Corresponding REST API: DELETE /instances/{isrelatedto-type-name}/{uuid} Operation Behavior:

• Permanently removes an IsRelatedTo relation from the Resource Registry
• The relation must exist and be accessible in the current context
• Only the relation is deleted; source and target Resources remain unaffected
• The operation is irreversible once completed
• Returns boolean indicating successful deletion.

HTTP Response Codes:

• 204 No Content: IsRelatedTo relation successfully deleted
• 404 Not Found: No IsRelatedTo relation found with the specified UUID or not accessible in current context
• 403 Forbidden: User lacks write permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The relation type name is automatically derived from the provided object using TypeUtility.getTypeName(Class)
• Only the UUID from the header is used for identification.

Deletion Behavior:

• The relation is permanently removed from the Information System
• Source and target Resources are not affected by the deletion
• Any cascading effects depend on Information System model constraints
• The operation cannot be undone.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an Activates relation
 Activates<EService, EService> relation = new Activates<>();
 relation.setHeader(new Header(uuid));
 boolean deleted = publisher.deleteIsRelatedTo(relation);
 

Type Parameters:

I - The specific type of IsRelatedTo relation to delete

Parameters:

isRelatedTo - Instance object containing at least the UUID in the header

Returns:

true if the IsRelatedTo relation was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation deletion

deleteIsRelatedTo

boolean deleteIsRelatedTo(String isRelatedToType,
 UUID uuid)
                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Deletes an IsRelatedTo relation instance from the Resource Registry by its type and UUID. Corresponding REST API: DELETE /instances/{isrelatedto-type-name}/{uuid} Operation Behavior:

• Permanently removes an IsRelatedTo relation from the Resource Registry
• The relation must exist and be accessible in the current context
• Only the relation is deleted; source and target Resources remain unaffected
• Type validation ensures the UUID corresponds to a relation of the specified type
• The operation is irreversible once completed
• Returns boolean indicating successful deletion.

HTTP Response Codes:

• 204 No Content: IsRelatedTo relation successfully deleted
• 404 Not Found: No IsRelatedTo relation found with the specified UUID and type, or not accessible in current context
• 403 Forbidden: User lacks write permissions for the relation or its context
• 401 Unauthorized: Invalid or missing authentication credentials.

Input Processing:

• The specified type must be a valid IsRelatedTo type in the Information System model
• Supports all IsRelatedTo types and their subtypes as defined in the Information System model
• Type names are case-sensitive and must match exactly the class names defined in the Information System model
• UUID must correspond to a relation of exactly the specified type (no polymorphic matching). *

Deletion Behavior:

• The relation is permanently removed from the Information System
• Source and target Resources are not affected by the deletion
• Any cascading effects depend on Information System model constraints
• The operation cannot be undone.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Delete an Activates relation by type and UUID
 UUID relationUuid = UUID.fromString("...");
 boolean deleted = publisher.deleteIsRelatedTo("Activates", relationUuid);
 

Parameters:

isRelatedToType - The exact type name of the IsRelatedTo relation to delete

uuid - The unique identifier of the IsRelatedTo relation to delete

Returns:

true if the IsRelatedTo relation was successfully deleted, false otherwise

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.relations.isrelatedto.IsRelatedToNotFoundException - If no relation is found with the specified UUID and type (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during relation deletion

addToContext

List<org.gcube.informationsystem.model.reference.ERElement> addToContext(String type,
 UUID instanceUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an Information System element instance to a specific context. Corresponding REST API: PUT /instances/{type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing instance (Entity or Relation) to the specified target context
• The instance must already exist and be accessible in the context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the instance itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them.

HTTP Response Codes:

• 200 OK: Instance successfully added to context (or dry-run completed)
• 404 Not Found: Instance or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of an instance to a context even if the instance is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding an instance to a context even if the instance exists only in other contexts
• When false: Standard validation applies - instance must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• The 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 Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Facets: When added to a context, the Resource that reference it (via ConsistsOf relation) is also added to the same context
• ConsistsOf Relations: add both facet and resource to the same context
• IsRelatedTo Relations: add both source and target resources to the same context.

Propagation Constraints and Cascade Effects:

• When an instance is added to a context, related instances may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding instances that violate cardinality constraints (max occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to add instances.

IS-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService to a specific context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addToContext("EService", serviceUUID, targetContextUUID, false);
 
 // Preview what would be affected by adding a ContactFacet to a context
 UUID facetUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.addToContext("ContactFacet", facetUUID, targetContextUUID, true);
 

Parameters:

type - The exact type name of the Information System element to add

instanceUUID - The UUID of the instance to add to the context

contextUUID - The UUID of the target context where the instance should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance or context is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addToContext

List<org.gcube.informationsystem.model.reference.ERElement> addToContext(org.gcube.informationsystem.model.reference.ERElement er,
 UUID contextUUID,
 Boolean dryRun)
                                                                  throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an Information System element instance to a specific context using a provided instance object. Corresponding REST API: PUT /instances/{type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing instance (Entity or Relation) to the specified target context
• The type and UUID are automatically extracted from the provided instance object
• The instance must already exist and be accessible in the context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the instance itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them.

HTTP Response Codes:

• 200 OK: Instance successfully added to context (or dry-run completed)
• 404 Not Found: Instance or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of an instance to a context even if the instance is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding an instance to a context even if the instance exists only in other contexts
• When false: Standard validation applies - instance must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• Type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• UUID is extracted from the instance's header using standard Information System model conventions
• 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 Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Facets: When added to a context, the Resource that reference it (via ConsistsOf relation) is also added to the same context
• ConsistsOf Relations: add both facet and resource to the same context
• IsRelatedTo Relations: add both source and target resources to the same context.

Propagation Constraints and Cascade Effects:

• When an instance is added to a context, related instances may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding instances that violate cardinality constraints (max occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to add instances.

IS-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService instance to a specific context
 EService service = new EService();
 service.setHeader(new Header(serviceUUID));
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addToContext(service, targetContextUUID, false);
 
 // Preview what would be affected by adding a ContactFacet to a context
 ContactFacet contact = publisher.read(ContactFacet.class, contactUUID);
 List<ERElement> preview = publisher.addToContext(contact, targetContextUUID, true);
 

Parameters:

er - The instance to add to the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context where the instance should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance or context is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addToCurrentContext

List<org.gcube.informationsystem.model.reference.ERElement> addToCurrentContext(String type,
 UUID instanceUUID,
 Boolean dryRun)
                                                                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an Information System element instance to the current context. Corresponding REST API: PUT /instances/{type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing instance (Entity or Relation) to the current context derived from the authorization token
• The instance must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the instance itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID.

HTTP Response Codes:

• 200 OK: Instance successfully added to current context (or dry-run completed)
• 404 Not Found: Instance does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of an instance to a context even if the instance is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding an instance to a context even if the instance exists only in other contexts
• When false: Standard validation applies - instance must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• The type name must be a valid Information System model type
• Supports all Information System model types: Entities (Resources, Facets) and Relations (ConsistsOf, IsRelatedTo) and their specialization
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Facets: When added to a context, the Resource that reference it (via ConsistsOf relation) is also added to the same context
• ConsistsOf Relations: add both facet and resource to the same context
• IsRelatedTo Relations: add both source and target resources to the same context.

Propagation Constraints and Cascade Effects:

• When an instance is added to a context, related instances may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding instances that violate cardinality constraints (max occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add instances.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService to the current context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addToCurrentContext("EService", serviceUUID, false);
 
 // Preview what would be affected by adding a ContactFacet to the current context
 UUID facetUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.addToCurrentContext("ContactFacet", facetUUID, true);
 

Parameters:

type - The exact type name of the Information System element to add

instanceUUID - The UUID of the instance to add to the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addToCurrentContext

List<org.gcube.informationsystem.model.reference.ERElement> addToCurrentContext(org.gcube.informationsystem.model.reference.ERElement er,
 Boolean dryRun)
                                                                         throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds an Information System element instance to the current context using a provided instance object. Corresponding REST API: PUT /instances/{type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing instance (Entity or Relation) to the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided instance object
• The instance must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the instance itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID.

HTTP Response Codes:

• 200 OK: Instance successfully added to current context (or dry-run completed)
• 404 Not Found: Instance does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of an instance to a context even if the instance is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding an instance to a context even if the instance exists only in other contexts
• When false: Standard validation applies - instance must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• Type name is automatically derived from the provided instance using TypeUtility.getTypeName(Class)
• UUID is extracted from the instance's header using standard Information System model conventions
• 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.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Facets: When added to a context, the Resource that reference it (via ConsistsOf relation) is also added to the same context
• ConsistsOf Relations: add both facet and resource to the same context
• IsRelatedTo Relations: add both source and target resources to the same context.

Propagation Constraints and Cascade Effects:

• When an instance is added to a context, related instances may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding instances that violate cardinality constraints (max occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add instances.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any instance in any context
• Can use forceAddToContext=true to add instances from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on instances accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService instance to the current context
 EService service = new EService();
 service.setHeader(new Header(serviceUUID));
 List<ERElement> affected = publisher.addToCurrentContext(service, false);
 
 // Preview what would be affected by adding a ContactFacet to the current context
 ContactFacet contact = publisher.read(ContactFacet.class, contactUUID);
 List<ERElement> preview = publisher.addToCurrentContext(contact, true);
 

Parameters:

er - The instance to add to the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

removeFromContext

List<org.gcube.informationsystem.model.reference.ERElement> removeFromContext(String type,
 UUID instanceUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an Information System element instance from a specific context. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{type-name}/{instance-uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing instance (Entity or Relation) from the specified target context
• The instance must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the instance itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them.

HTTP Response Codes:

• 200 OK: Instance successfully removed from context (or dry-run completed)
• 404 Not Found: Instance or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• The 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 Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Facets: When removed from a context, the Resource that reference it (via ConsistsOf relation) is also removed from the same context if the Facet was the last one required by the Resource in that context
• ConsistsOf Relations: Remove both facet and resource from the same context
• IsRelatedTo Relations: Remove both source and target resources from the same context.

Propagation Constraints and Cascade Effects:

• When an instance is removed from a context, related instances may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet or ConsistsOf relation from a Resource; • Removing instances that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove instances.

IS-Manager:

• Can perform REMOVE operations on any instance in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any instance in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on instances accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on instances accessible in their current context
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService from a specific context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFromContext("EService", serviceUUID, targetContextUUID, false);
 
 // Preview what would be affected by removing a ContactFacet from a context
 UUID facetUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeFromContext("ContactFacet", facetUUID, targetContextUUID, true);
 

Parameters:

type - The exact type name of the Information System element to remove

instanceUUID - The UUID of the instance to remove from the context

contextUUID - The UUID of the target context from which the instance should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance or context is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFromContext

List<org.gcube.informationsystem.model.reference.ERElement> removeFromContext(org.gcube.informationsystem.model.reference.ERElement er,
 UUID contextUUID,
 Boolean dryRun)
                                                                       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an Information System element instance from a specific context using a provided instance object. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{type-name}/{instance-uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing instance (Entity or Relation) from the specified target context
• The instance must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the instance itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method accepts an Information System instance object directly, which provides type safety and convenience.

HTTP Response Codes:

• 200 OK: Instance successfully removed from context (or dry-run completed)
• 404 Not Found: Instance or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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: publisher.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.

Input Processing:

• The instance object must contain a valid UUID in its header
• 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)
• The actual type is determined from the instance object's class.

Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Facets: When removed from a context, the Resource that reference it (via ConsistsOf relation) is also removed from the same context if the Facet was the last one required by the Resource in that context
• ConsistsOf Relations: Remove both facet and resource from the same context
• IsRelatedTo Relations: Remove both source and target resources from the same context.

Propagation Constraints and Cascade Effects:

• When an instance is removed from a context, related instances may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for ConsistsOf Relations and Facets:

• When operations are performed on ConsistsOf relations or Facet instances, the parent Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet or ConsistsOf relation from a Resource; • Removing instances that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove instances.

IS-Manager:

• Can perform REMOVE operations on any instance in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any instance in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on instances accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on instances accessible in their current context
• Operations are limited to instances they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService instance from a specific context
 EService service = publisher.read(EService.class, serviceUUID);
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFromContext(service, targetContextUUID, false);
 
 // Preview what would be affected by removing a ContactFacet from a context
 ContactFacet contact = publisher.read(ContactFacet.class, contactUUID);
 List<ERElement> preview = publisher.removeFromContext(contact, targetContextUUID, true);
 

Parameters:

er - The instance to remove from the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context from which the instance should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the instance itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the instance or context is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFromCurrentContext

List<org.gcube.informationsystem.model.reference.ERElement> removeFromCurrentContext(String type,
 UUID instanceUUID,
 Boolean dryRun)
                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an ERElement instance from the current context. Corresponding REST API: POST /sharing/contexts/{type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing ERElement instance from the current context derived from the authorization token
• The ERElement (Resource or Facet) must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the ERElement itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method works with both Resource and Facet types.

HTTP Response Codes:

• 200 OK: ERElement successfully removed from current context (or dry-run completed)
• 404 Not Found: ERElement does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 ERElement and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present.

Input Processing:

• The type name must be a valid ERElement type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet)
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• ConsistsOf Relations: All ConsistsOf relations connecting Resources to Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When an ERElement is removed from a context, related elements may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation:

• When an ERElement is removed from a context, the ERElement is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Removing a required/mandatory Facet from a Resource; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related elements incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove ERElements.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any ERElement in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any ERElement in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on ERElements accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on ERElements accessible in their current context
• Operations are limited to ERElements they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService from the current context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFromCurrentContext("EService", serviceUUID, false);
 
 // Preview what would be affected by removing a StateFacet from the current context
 UUID stateFacetUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeFromCurrentContext("StateFacet", stateFacetUUID, true);
 

Parameters:

type - The exact type name of the ERElement to remove

instanceUUID - The UUID of the ERElement instance to remove from the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the ERElement itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the ERElement is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFromCurrentContext

List<org.gcube.informationsystem.model.reference.ERElement> removeFromCurrentContext(org.gcube.informationsystem.model.reference.ERElement er,
 Boolean dryRun)
                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes an ERElement instance from the current context using a provided ERElement object. Corresponding REST API: POST /sharing/contexts/{type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing ERElement instance from the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided ERElement object
• The ERElement (Resource or Facet) must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the ERElement itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for both Resource and Facet types.

HTTP Response Codes:

• 200 OK: ERElement successfully removed from current context (or dry-run completed)
• 404 Not Found: ERElement does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 ERElement and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present.

Input Processing:

• The type name is automatically derived from the provided ERElement object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the ERElement's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• ConsistsOf Relations: All ConsistsOf relations connecting Resources to Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When an ERElement is removed from a context, related elements may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation:

• When an ERElement is removed from a context, the ERElement is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Removing a required/mandatory Facet from a Resource; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related elements incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove ERElements.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any ERElement in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any ERElement in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on ERElements accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on ERElements accessible in their current context
• Operations are limited to ERElements they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService instance from the current context
 EService service = publisher.read(EService.class, serviceUUID);
 List<ERElement> affected = publisher.removeFromCurrentContext(service, false);
 
 // Preview what would be affected by removing a StateFacet from the current context
 StateFacet facet = publisher.read(StateFacet.class, facetUUID);
 List<ERElement> preview = publisher.removeFromCurrentContext(facet, true);
 

Parameters:

er - The ERElement instance to remove from the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the ERElement itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException - If the ERElement is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

getElementContexts

Map<UUID,String> getElementContexts(String type,
 UUID instanceUUID)
                             throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
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 /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:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get contexts for an EService by type and UUID
 UUID serviceUuid = UUID.fromString("48af15ad-7e56-4157-b624-71c98cea4f8f");
 Map<UUID, String> contexts = publisher.getElementContexts("EService", serviceUuid);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Parameters:

type - The exact type name of the Information System element (e.g., "EService", "ContactFacet")

instanceUUID - 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.ResourceRegistryException - If an error occurs during context retrieval

getElementContexts

<ERElem extends org.gcube.informationsystem.model.reference.ERElement>
Map<UUID,String> getElementContexts(ERElem er)
                             throws org.gcube.informationsystem.resourceregistry.api.exceptions.NotFoundException,
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 /instances/{type-name}/{instance-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified element object (Resource, Facet, ConsistsOf, or IsRelatedTo) is present
• The element's type and UUID are automatically extracted from the provided object
• 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 or is not accessible
• 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:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Assuming you have an EService instance
 EService service = ...; // Retrieved from previous operations
 
 // Get contexts for the service object
 Map<UUID, String> contexts = publisher.getElementContexts(service);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Type Parameters:

ERElem - The type of Information System element (Resource, Facet, ConsistsOf, or IsRelatedTo)

Parameters:

er - The Information System 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 the specified element does not exist or is not accessible

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

addResourceToContext

List<org.gcube.informationsystem.model.reference.ERElement> addResourceToContext(String resourceType,
 UUID resourceUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                          throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Resource instance to a specific context. Corresponding REST API: PUT /instances/{resource-type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing Resource instance to the specified target context
• The Resource must already exist and be accessible in the context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Resource itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully added to context (or dry-run completed)
• 404 Not Found: Resource or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Resource to a context even if the Resource is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Resource to a context even if the Resource exists only in other contexts
• When false: Standard validation applies - Resource must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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.

Input Processing:

• The type name must be a valid Resource type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Type name is case-sensitive and must match exactly.

Resource-Specific Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically included
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also added to the context.

Propagation Constraints and Cascade Effects:

• When a Resource is added to a context, all related Facets may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is added to a context, the Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Resource that violates cardinality constraints defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to add Resources.

IS-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService to a specific context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addResourceToContext("EService", serviceUUID, targetContextUUID, false);
 
 // Preview what would be affected by adding a HostingNode to a context
 UUID hostUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.addResourceToContext("HostingNode", hostUUID, targetContextUUID, true);
 

Parameters:

resourceType - The exact type name of the Resource to add

resourceUUID - The UUID of the Resource instance to add to the context

contextUUID - The UUID of the target context where the Resource should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addResourceToContext

<R extends org.gcube.informationsystem.model.reference.entities.Resource>
List<org.gcube.informationsystem.model.reference.ERElement> addResourceToContext(R resource,
 UUID contextUUID,
 Boolean dryRun)
                                                                          throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Resource instance to a specific context using a provided Resource object. Corresponding REST API: PUT /instances/{resource-type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing Resource instance to the specified target context
• The type and UUID are automatically extracted from the provided Resource object
• The Resource must already exist and be accessible in the context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Resource itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This method provides compile-time type safety for Resource types.

HTTP Response Codes:

• 200 OK: Resource successfully added to context (or dry-run completed)
• 404 Not Found: Resource or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Resource to a context even if the Resource is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Resource to a context even if the Resource exists only in other contexts
• When false: Standard validation applies - Resource must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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.

Input Processing:

• The type name is automatically derived from the provided Resource object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Resource's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software).

Resource-Specific Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically included
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also added to the context.

Propagation Constraints and Cascade Effects:

• When a Resource is added to a context, all related Facets may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is added to a context, the Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Resource that violates cardinality constraints defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to add Resources.

IS-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService instance to a specific context
 EService service = new EService();
 service.setHeader(new Header(serviceUUID));
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addResourceToContext(service, targetContextUUID, false);
 
 // Preview what would be affected by adding a HostingNode to a context
 HostingNode host = publisher.read(HostingNode.class, hostUUID);
 List<ERElement> preview = publisher.addResourceToContext(host, targetContextUUID, true);
 

Type Parameters:

R - The specific type of Resource to add

Parameters:

resource - The Resource instance to add to the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context where the Resource should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addResourceToCurrentContext

List<org.gcube.informationsystem.model.reference.ERElement> addResourceToCurrentContext(String resourceType,
 UUID resourceUUID,
 Boolean dryRun)
                                                                                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Resource instance to the current context. Corresponding REST API: PUT /instances/{resource-type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing Resource instance to the current context derived from the authorization token
• The Resource must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Resource itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully added to current context (or dry-run completed)
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Resource to a context even if the Resource is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Resource to a context even if the Resource exists only in other contexts
• When false: Standard validation applies - Resource must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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.

Input Processing:

• The type name must be a valid Resource type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Resource-Specific Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically included
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also added to the context.

Propagation Constraints and Cascade Effects:

• When a Resource is added to a context, all related Facets may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is added to a context, the Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Resource that violates cardinality constraints defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add Resources.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService to the current context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.addResourceToCurrentContext("EService", serviceUUID, false);
 
 // Preview what would be affected by adding a HostingNode to the current context
 UUID hostUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.addResourceToCurrentContext("HostingNode", hostUUID, true);
 

Parameters:

resourceType - The exact type name of the Resource to add

resourceUUID - The UUID of the Resource instance to add to the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addResourceToCurrentContext

<R extends org.gcube.informationsystem.model.reference.entities.Resource>
List<org.gcube.informationsystem.model.reference.ERElement> addResourceToCurrentContext(R resource,
 Boolean dryRun)
                                                                                 throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Resource instance to the current context using a provided Resource object. Corresponding REST API: PUT /instances/{resource-type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing Resource instance to the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided Resource object
• The Resource must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Resource itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for Resource types.

HTTP Response Codes:

• 200 OK: Resource successfully added to current context (or dry-run completed)
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Resource to a context even if the Resource is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Resource to a context even if the Resource exists only in other contexts
• When false: Standard validation applies - Resource must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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.

Input Processing:

• The type name is automatically derived from the provided Resource object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Resource's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Resource-Specific Context Propagation Rules:

• Resources: When added to a context, all their associated Facets (via ConsistsOf relations) are also added to the same context if the add propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically included
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also added to the context.

Propagation Constraints and Cascade Effects:

• When a Resource is added to a context, all related Facets may also be automatically added due to propagation constraints
• The response includes all instances that were added as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is added to a context, the Resource is automatically validated against its schema definition
• If the Resource is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Resource that violates cardinality constraints defined in the schema; • Operations that make the Resource incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add Resources.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Resource in any context
• Can use forceAddToContext=true to add Resources from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Resources accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add an EService instance to the current context
 EService service = new EService();
 service.setHeader(new Header(serviceUUID));
 List<ERElement> affected = publisher.addResourceToCurrentContext(service, false);
 
 // Preview what would be affected by adding a HostingNode to the current context
 HostingNode host = publisher.read(HostingNode.class, hostUUID);
 List<ERElement> preview = publisher.addResourceToCurrentContext(host, true);
 

Type Parameters:

R - The specific type of Resource to add

Parameters:

resource - The Resource instance to add to the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

removeResourceFromContext

List<org.gcube.informationsystem.model.reference.ERElement> removeResourceFromContext(String resourceType,
 UUID resourceUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                               throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Resource instance from a specific context. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{resource-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Resource instance from the specified target context
• The Resource must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Resource itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully removed from context (or dry-run completed)
• 404 Not Found: Resource or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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.

Input Processing:

• The type name must be a valid Resource type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Type name is case-sensitive and must match exactly.

Resource-Specific Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically removed if they become orphaned
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Resource is removed from a context, all related Facets may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is removed from a context, the Resource is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove Resources.

IS-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService from a specific context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeResourceFromContext("EService", serviceUUID, targetContextUUID, false);
 
 // Preview what would be affected by removing a HostingNode from a context
 UUID hostUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeResourceFromContext("HostingNode", hostUUID, targetContextUUID, true);
 

Parameters:

resourceType - The exact type name of the Resource to remove

resourceUUID - The UUID of the Resource instance to remove from the context

contextUUID - The UUID of the target context from which the Resource should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeResourceFromContext

<R extends org.gcube.informationsystem.model.reference.entities.Resource>
List<org.gcube.informationsystem.model.reference.ERElement> removeResourceFromContext(R resource,
 UUID contextUUID,
 Boolean dryRun)
                                                                               throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Resource instance from a specific context using a provided Resource object. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{resource-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Resource instance from the specified target context
• The Resource must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Resource itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method accepts a Resource instance object directly, which provides type safety and convenience
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully removed from context (or dry-run completed)
• 404 Not Found: Resource or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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.

Input Processing:

• The Resource object must contain a valid UUID in its header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• The actual type is determined from the Resource object's class.

Resource-Specific Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically removed if they become orphaned
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Resource is removed from a context, all related Facets may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is removed from a context, the Resource is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove Resources.

IS-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService instance from a specific context
 EService service = publisher.read(EService.class, serviceUUID);
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeResourceFromContext(service, targetContextUUID, false);
 
 // Preview what would be affected by removing a HostingNode from a context
 HostingNode host = publisher.read(HostingNode.class, hostUUID);
 List<ERElement> preview = publisher.removeResourceFromContext(host, targetContextUUID, true);
 

Type Parameters:

R - The type of Resource (EService, HostingNode, Software, etc.)

Parameters:

resource - The Resource instance to remove from the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context from which the Resource should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeResourceFromCurrentContext

List<org.gcube.informationsystem.model.reference.ERElement> removeResourceFromCurrentContext(String resourceType,
 UUID resourceUUID,
 Boolean dryRun)
                                                                                      throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Resource instance from the current context. Corresponding REST API: POST /sharing/contexts/{resource-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Resource instance from the current context derived from the authorization token
• The Resource must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Resource itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method is specifically designed for Resource types and provides type safety.

HTTP Response Codes:

• 200 OK: Resource successfully removed from current context (or dry-run completed)
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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.

Input Processing:

• The type name must be a valid Resource type in the Information System model
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software)
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Resource-Specific Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically removed if they become orphaned
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Resource is removed from a context, all related Facets may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is removed from a context, the Resource is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove Resources.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService from the current context with actual changes
 UUID serviceUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeResourceFromCurrentContext("EService", serviceUUID, false);
 
 // Preview what would be affected by removing a HostingNode from the current context
 UUID hostUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeResourceFromCurrentContext("HostingNode", hostUUID, true);
 

Parameters:

resourceType - The exact type name of the Resource to remove

resourceUUID - The UUID of the Resource instance to remove from the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeResourceFromCurrentContext

<R extends org.gcube.informationsystem.model.reference.entities.Resource>
List<org.gcube.informationsystem.model.reference.ERElement> removeResourceFromCurrentContext(R resource,
 Boolean dryRun)
                                                                                      throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Resource instance from the current context using a provided Resource object. Corresponding REST API: POST /sharing/contexts/{resource-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Resource instance from the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided Resource object
• The Resource must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Resource itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for Resource types.

HTTP Response Codes:

• 200 OK: Resource successfully removed from current context (or dry-run completed)
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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: publisher.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 Resource and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.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.

Input Processing:

• The type name is automatically derived from the provided Resource object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Resource's header
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Resource-Specific Context Propagation Rules:

• Resources: When removed from a context, all their associated Facets (via ConsistsOf relations) are also removed from the same context if the remove propagation constraint is propagate
• Associated Facets: All Facets connected to the Resource via ConsistsOf relations are automatically removed if they become orphaned
• ConsistsOf Relations: All ConsistsOf relations connecting the Resource to its Facets are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Resource is removed from a context, all related Facets may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Resource and ConsistsOf Relations:

• When a Resource is removed from a context, the Resource is automatically validated against its schema definition
• If the operation would violate schema constraints after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a Resource that would leave required Facets orphaned; • Operations that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make related Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove Resources.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Resource in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Resources accessible in their current context
• Operations are limited to Resources they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove an EService instance from the current context
 EService service = publisher.read(EService.class, serviceUUID);
 List<ERElement> affected = publisher.removeResourceFromCurrentContext(service, false);
 
 // Preview what would be affected by removing a HostingNode from the current context
 HostingNode host = publisher.read(HostingNode.class, hostUUID);
 List<ERElement> preview = publisher.removeResourceFromCurrentContext(host, true);
 

Type Parameters:

R - The specific type of Resource to remove

Parameters:

resource - The Resource instance to remove from the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Resource itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the Resource is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

getResourceContexts

Map<UUID,String> getResourceContexts(String resourceType,
 UUID resourceUUID)
                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Resource is present in the Resource Registry. Corresponding REST API: GET /instances/{resource-type-name}/{resource-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified Resource is present
• The Resource 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 Resource's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Resource does not exist with the specified type and UUID
• 403 Forbidden: Resource 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 Resource across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any Resource across the entire infrastructure
• Context-Manager: Can retrieve context information for Resources accessible within their managed contexts
• Other Users: Can retrieve context information for Resources 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 Resource exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Resource Context Rules:

• Resources: Present in all contexts that form the union of contexts of all their Facets
• A Resource is present in a context if at least one of its associated Facets (via ConsistsOf relations) is present in that context
• If a Resource has no Facets, it may still be present in contexts based on direct context assignments.

Type Safety:

• This method is specifically designed for Resource types and provides compile-time type safety
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software, Dataset).

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get contexts for an EService by type and UUID
 UUID serviceUuid = UUID.fromString("48af15ad-7e56-4157-b624-71c98cea4f8f");
 Map<UUID, String> contexts = publisher.getResourceContexts("EService", serviceUuid);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Parameters:

resourceType - The exact type name of the Resource (e.g., "EService", "HostingNode")

resourceUUID - The unique identifier of the Resource whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the Resource is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If no Resource is found with the specified type and UUID

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

getResourceContexts

<R extends org.gcube.informationsystem.model.reference.entities.Resource>
Map<UUID,String> getResourceContexts(R resource)
                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Resource is present in the Resource Registry. Corresponding REST API: GET /instances/{resource-type-name}/{resource-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified Resource object is present
• The Resource's type and UUID are automatically extracted from the provided object
• The Resource 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 Resource's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Resource does not exist or is not accessible
• 403 Forbidden: Resource 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 Resource across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any Resource across the entire infrastructure
• Context-Manager: Can retrieve context information for Resources accessible within their managed contexts
• Other Users: Can retrieve context information for Resources 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 Resource exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Resource Context Rules:

• Resources: Present in all contexts that form the union of contexts of all their Facets
• A Resource is present in a context if at least one of its associated Facets (via ConsistsOf relations) is present in that context
• If a Resource has no Facets, it may still be present in contexts based on direct context assignments.

Type Safety:

• This method provides compile-time type safety by accepting any Resource subtype
• The Resource's type is automatically determined from the object's class
• Supports all Resource types and their specializations (e.g., EService, HostingNode, Software, Dataset).

Object-based Operation:

• This method accepts a Resource instance object directly, which provides convenience and type safety
• The Resource object must contain a valid UUID in its header metadata
• The type is automatically inferred from the object's runtime class.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Assuming you have an EService instance
 EService service = ...; // Retrieved from previous operations
 
 // Get contexts for the service object
 Map<UUID, String> contexts = publisher.getResourceContexts(service);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Type Parameters:

R - The type of Resource (EService, HostingNode, Software, etc.)

Parameters:

resource - The Resource instance whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the Resource is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.resource.ResourceNotFoundException - If the specified Resource does not exist or is not accessible

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

addFacetToContext

List<org.gcube.informationsystem.model.reference.ERElement> addFacetToContext(String facetType,
 UUID facetUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Facet instance to a specific context using type name and UUID. Corresponding REST API: PUT /instances/{facet-type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing Facet instance to the specified context
• The Facet must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the target context
• Returns the list of affected elements (the Facet itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them.

HTTP Response Codes:

• 200 OK: Facet successfully added to specified context (or dry-run completed)
• 404 Not Found: Facet or context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the target context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Facet to a context even if the Facet is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Facet to a context even if the Facet exists only in other contexts
• When false: Standard validation applies - Facet must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.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 Facet and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet is present in all contexts that are part of the union of contexts of all Resources that use it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their source Resources and target Facets are both present.

Input Processing:

• The facetType parameter must be a valid Facet type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all Facet types and their specializations (e.g., StateFacet, SoftwareFacet, AccessPointFacet).

Target Context:

• The contextUUID parameter specifies the exact context where the Facet should be added
• The user must have appropriate permissions in this context
• The context must exist and be accessible.

Facet-Specific Context Propagation Rules:

• Facets: When added to a context, no automatic propagation occurs as Facets do not have dependent elements
• Related Resources: Resources that use this Facet via ConsistsOf relations are NOT automatically added to the context
• Consistency Check: The Facet must be associated with Resources that are already present in the target context
• Important: Adding a Facet to a context where its associated Resources are not present may create inconsistencies.

Propagation Constraints and Cascade Effects:

• When a Facet is added to a context, there are typically no cascade effects since Facets are leaf elements
• However, the schema may define specific constraints for certain Facet types that could trigger validation
• The response includes the Facet instance and any validation-related information.

Schema Validation for Facet:

• When a Facet is added to a context, the Facet is automatically validated against its schema definition
• If the Facet is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Facet that violates property constraints defined in the schema; • Operations that make the Facet incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Facet type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Facet type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the target context where they want to add Facets.

IS-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Facets accessible in contexts where they have Context-Manager role
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Facets accessible in contexts where they have appropriate permissions
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Facets they have access to in their authorized contexts
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add a StateFacet instance to a specific context
 UUID stateFacetUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 UUID targetContextUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 List<ERElement> affected = publisher.addFacetToContext("StateFacet", stateFacetUUID, targetContextUUID, false);
 
 // Preview what would be affected by adding an AccessPointFacet to a specific context
 UUID accessPointUUID = UUID.fromString("11223344-5566-7788-9900-aabbccddeeff");
 UUID contextUUID = UUID.fromString("ffeeddcc-bbaa-0099-8877-665544332211");
 List<ERElement> preview = publisher.addFacetToContext("AccessPointFacet", accessPointUUID, contextUUID, true);
 

Parameters:

facetType - The type name of the Facet to add (must be a valid Facet type)

facetUUID - The UUID of the Facet instance to add to the specified context

contextUUID - The UUID of the target context where the Facet should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addFacetToContext

<F extends org.gcube.informationsystem.model.reference.entities.Facet>
List<org.gcube.informationsystem.model.reference.ERElement> addFacetToContext(F facet,
 UUID contextUUID,
 Boolean dryRun)
                                                                       throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Facet instance to a specific context using a provided Facet object. Corresponding REST API: PUT /instances/{facet-type-name}/{uuid}/contexts/{context-uuid}[?dryRun={true|false}] Operation Behavior:

• Adds an existing Facet instance to the specified context
• The type and UUID are automatically extracted from the provided Facet object
• The Facet must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the target context
• Returns the list of affected elements (the Facet itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This method provides compile-time type safety for Facet types.

HTTP Response Codes:

• 200 OK: Facet successfully added to specified context (or dry-run completed)
• 404 Not Found: Facet or context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the target context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Facet to a context even if the Facet is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Facet to a context even if the Facet exists only in other contexts
• When false: Standard validation applies - Facet must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.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 Facet and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet is present in all contexts that are part of the union of contexts of all Resources that use it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their source Resources and target Facets are both present.

Input Processing:

• The type name is automatically derived from the provided Facet object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Facet's header
• Supports all Facet types and their specializations (e.g., StateFacet, SoftwareFacet, AccessPointFacet).

Target Context:

• The contextUUID parameter specifies the exact context where the Facet should be added
• The user must have appropriate permissions in this context
• The context must exist and be accessible.

Facet-Specific Context Propagation Rules:

• Facets: When added to a context, no automatic propagation occurs as Facets do not have dependent elements
• Related Resources: Resources that use this Facet via ConsistsOf relations are NOT automatically added to the context
• Consistency Check: The Facet must be associated with Resources that are already present in the target context
• Important: Adding a Facet to a context where its associated Resources are not present may create inconsistencies.

Propagation Constraints and Cascade Effects:

• When a Facet is added to a context, there are typically no cascade effects since Facets are leaf elements
• However, the schema may define specific constraints for certain Facet types that could trigger validation
• The response includes the Facet instance and any validation-related information.

Schema Validation for Facet:

• When a Facet is added to a context, the Facet is automatically validated against its schema definition
• If the Facet is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Facet that violates property constraints defined in the schema; • Operations that make the Facet incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Facet type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Facet type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the target context where they want to add Facets.

IS-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Facets accessible in contexts where they have Context-Manager role
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Facets accessible in contexts where they have appropriate permissions
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Facets they have access to in their authorized contexts
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add a StateFacet instance to a specific context
 StateFacet facet = new StateFacet();
 facet.setHeader(new Header(facetUUID));
 UUID targetContextUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 List<ERElement> affected = publisher.addFacetToContext(facet, targetContextUUID, false);
 
 // Preview what would be affected by adding an AccessPointFacet to a specific context
 AccessPointFacet accessPoint = publisher.read(AccessPointFacet.class, accessPointUUID);
 UUID contextUUID = UUID.fromString("ffeeddcc-bbaa-0099-8877-665544332211");
 List<ERElement> preview = publisher.addFacetToContext(accessPoint, contextUUID, true);
 

Type Parameters:

F - The specific type of Facet to add

Parameters:

facet - The Facet instance to add to the specified context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context where the Facet should be added

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addFacetToCurrentContext

List<org.gcube.informationsystem.model.reference.ERElement> addFacetToCurrentContext(String facetType,
 UUID facetUUID,
 Boolean dryRun)
                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Facet instance to the current context using type name and UUID. Corresponding REST API: PUT /instances/{facet-type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing Facet instance to the current context derived from the authorization token
• The Facet must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Facet itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID.

HTTP Response Codes:

• 200 OK: Facet successfully added to current context (or dry-run completed)
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Facet to a context even if the Facet is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Facet to a context even if the Facet exists only in other contexts
• When false: Standard validation applies - Facet must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.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 Facet and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet is present in all contexts that are part of the union of contexts of all Resources that use it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their source Resources and target Facets are both present.

Input Processing:

• The facetType parameter must be a valid Facet type name registered in the Information System
• Type names are case-sensitive and must match exactly
• Supports all Facet types and their specializations (e.g., StateFacet, SoftwareFacet, AccessPointFacet).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Facet-Specific Context Propagation Rules:

• Facets: When added to a context, no automatic propagation occurs as Facets do not have dependent elements
• Related Resources: Resources that use this Facet via ConsistsOf relations are NOT automatically added to the context
• Consistency Check: The Facet must be associated with Resources that are already present in the target context
• Important: Adding a Facet to a context where its associated Resources are not present may create inconsistencies.

Propagation Constraints and Cascade Effects:

• When a Facet is added to a context, there are typically no cascade effects since Facets are leaf elements
• However, the schema may define specific constraints for certain Facet types that could trigger validation
• The response includes the Facet instance and any validation-related information.

Schema Validation for Facet:

• When a Facet is added to a context, the Facet is automatically validated against its schema definition
• If the Facet is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Facet that violates property constraints defined in the schema; • Operations that make the Facet incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Facet type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Facet type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add Facets.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Facets accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Facets accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add a StateFacet instance to the current context
 UUID stateFacetUUID = UUID.fromString("12345678-1234-1234-1234-123456789abc");
 List<ERElement> affected = publisher.addFacetToCurrentContext("StateFacet", stateFacetUUID, false);
 
 // Preview what would be affected by adding an AccessPointFacet to the current context
 UUID accessPointUUID = UUID.fromString("87654321-4321-4321-4321-cba987654321");
 List<ERElement> preview = publisher.addFacetToCurrentContext("AccessPointFacet", accessPointUUID, true);
 

Parameters:

facetType - The type name of the Facet to add (must be a valid Facet type)

facetUUID - The UUID of the Facet instance to add to the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

addFacetToCurrentContext

<F extends org.gcube.informationsystem.model.reference.entities.Facet>
List<org.gcube.informationsystem.model.reference.ERElement> addFacetToCurrentContext(F facet,
 Boolean dryRun)
                                                                              throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Adds a Facet instance to the current context using a provided Facet object. Corresponding REST API: PUT /instances/{facet-type-name}/{uuid}/contexts[?dryRun={true|false}] Operation Behavior:

• Adds an existing Facet instance to the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided Facet object
• The Facet must already exist and be accessible in the context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Facet itself and any related elements that are also added)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for Facet types.

HTTP Response Codes:

• 200 OK: Facet successfully added to current context (or dry-run completed)
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: forceAddToContext (configurable via client configuration):

• Forces the addition of a Facet to a context even if the Facet is not present in the current context
• Default value: false (standard validation applies)
• Usage: publisher.addHeader(SharingPath.FORCE_ADD_TO_CONTEXT_QUERY_PARAMETER, true)
• Values: true | false
• When true: Allows adding a Facet to a context even if the Facet exists only in other contexts
• When false: Standard validation applies - Facet must be accessible in the current context for ADD operations
• Authorization Required: Only available to IS-Manager and Infrastructure-Manager

includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.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 Facet and its nested elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet is present in all contexts that are part of the union of contexts of all Resources that use it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their source Resources and target Facets are both present.

Input Processing:

• The type name is automatically derived from the provided Facet object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Facet's header
• Supports all Facet types and their specializations (e.g., StateFacet, SoftwareFacet, AccessPointFacet).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Facet-Specific Context Propagation Rules:

• Facets: When added to a context, no automatic propagation occurs as Facets do not have dependent elements
• Related Resources: Resources that use this Facet via ConsistsOf relations are NOT automatically added to the context
• Consistency Check: The Facet must be associated with Resources that are already present in the target context
• Important: Adding a Facet to a context where its associated Resources are not present may create inconsistencies.

Propagation Constraints and Cascade Effects:

• When a Facet is added to a context, there are typically no cascade effects since Facets are leaf elements
• However, the schema may define specific constraints for certain Facet types that could trigger validation
• The response includes the Facet instance and any validation-related information.

Schema Validation for Facet:

• When a Facet is added to a context, the Facet is automatically validated against its schema definition
• If the Facet is no longer compliant with its schema after the add operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Adding a Facet that violates property constraints defined in the schema; • Operations that make the Facet incomplete or invalid according to its schema definition.

• Constraint Sources: Constraints are defined by the specific Facet type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Facet type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to add Facets.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform ADD operations on any Facet in any context
• Can use forceAddToContext=true to add Facets from other contexts
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform ADD operations only on Facets accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform ADD operations only on Facets accessible in their current context
• Cannot use forceAddToContext=true (parameter is ignored if provided)
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Add a StateFacet instance to the current context
 StateFacet facet = new StateFacet();
 facet.setHeader(new Header(facetUUID));
 List<ERElement> affected = publisher.addFacetToCurrentContext(facet, false);
 
 // Preview what would be affected by adding an AccessPointFacet to the current context
 AccessPointFacet accessPoint = publisher.read(AccessPointFacet.class, accessPointUUID);
 List<ERElement> preview = publisher.addFacetToCurrentContext(accessPoint, true);
 

Type Parameters:

F - The specific type of Facet to add

Parameters:

facet - The Facet instance to add to the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the add operation

removeFacetFromContext

List<org.gcube.informationsystem.model.reference.ERElement> removeFacetFromContext(String facetType,
 UUID facetUUID,
 UUID contextUUID,
 Boolean dryRun)
                                                                            throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Facet instance from a specific context. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{facet-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Facet instance from the specified target context
• The Facet must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Facet itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method is specifically designed for Facet types and provides type safety.

HTTP Response Codes:

• 200 OK: Facet successfully removed from context (or dry-run completed)
• 404 Not Found: Facet or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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, parent Resources, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.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 Facet and its related elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets.

Input Processing:

• The type name must be a valid Facet type in the Information System model
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet)
• Type name is case-sensitive and must match exactly.

Facet-Specific Context Propagation Rules:

• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• Associated Resources: Parent Resources connected to the Facet via ConsistsOf relations are automatically affected based on propagation constraints
• ConsistsOf Relations: All ConsistsOf relations connecting parent Resources to this Facet are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Facet is removed from a context, related Resources may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Facets and ConsistsOf Relations:

• When a Facet is removed from a context, the parent Resources are automatically validated against their schema definitions
• If any parent Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet from a Resource; • Removing Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make parent Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove Facets.

IS-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove a StateFacet from a specific context with actual changes
 UUID stateFacetUUID = UUID.fromString("...");
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFacetFromContext("StateFacet", stateFacetUUID, targetContextUUID, false);
 
 // Preview what would be affected by removing an AccessPointFacet from a context
 UUID accessPointUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeFacetFromContext("AccessPointFacet", accessPointUUID, targetContextUUID, true);
 

Parameters:

facetType - The exact type name of the Facet to remove

facetUUID - The UUID of the Facet instance to remove from the context

contextUUID - The UUID of the target context from which the Facet should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFacetFromContext

<F extends org.gcube.informationsystem.model.reference.entities.Facet>
List<org.gcube.informationsystem.model.reference.ERElement> removeFacetFromContext(F facet,
 UUID contextUUID,
 Boolean dryRun)
                                                                            throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Facet instance from a specific context using a provided Facet object. Corresponding REST API: POST /sharing/contexts/{context-uuid}/{facet-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Facet instance from the specified target context
• The Facet must already exist and be accessible in the target context where the user is performing the request
• The target context must exist and the user must have the rights to perform such a request
• Returns the list of affected elements (the Facet itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This method accepts a Facet instance object directly, which provides type safety and convenience
• This method is specifically designed for Facet types and provides type safety.

HTTP Response Codes:

• 200 OK: Facet successfully removed from context (or dry-run completed)
• 404 Not Found: Facet or target context does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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, parent Resources, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.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 Facet and its related elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets.

Input Processing:

• The Facet object must contain a valid UUID in its header
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet)
• The actual type is determined from the Facet object's class.

Facet-Specific Context Propagation Rules:

• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• Associated Resources: Parent Resources connected to the Facet via ConsistsOf relations are automatically affected based on propagation constraints
• ConsistsOf Relations: All ConsistsOf relations connecting parent Resources to this Facet are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Facet is removed from a context, related Resources may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Facets and ConsistsOf Relations:

• When a Facet is removed from a context, the parent Resources are automatically validated against their schema definitions
• If any parent Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet from a Resource; • Removing Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make parent Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the specific context where they want to remove Facets.

IS-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove a StateFacet instance from a specific context
 StateFacet facet = publisher.read(StateFacet.class, facetUUID);
 UUID targetContextUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFacetFromContext(facet, targetContextUUID, false);
 
 // Preview what would be affected by removing an AccessPointFacet from a context
 AccessPointFacet accessPoint = publisher.read(AccessPointFacet.class, accessPointUUID);
 List<ERElement> preview = publisher.removeFacetFromContext(accessPoint, targetContextUUID, true);
 

Type Parameters:

F - The type of Facet (StateFacet, ContactFacet, AccessPointFacet, etc.)

Parameters:

facet - The Facet instance to remove from the context (must contain a valid UUID in the header)

contextUUID - The UUID of the target context from which the Facet should be removed

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the target context does not exist or is not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFacetFromCurrentContext

List<org.gcube.informationsystem.model.reference.ERElement> removeFacetFromCurrentContext(String facetType,
 UUID facetUUID,
 Boolean dryRun)
                                                                                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Facet instance from the current context. Corresponding REST API: POST /sharing/contexts/{facet-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Facet instance from the current context derived from the authorization token
• The Facet must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Facet itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method is specifically designed for Facet types and provides type safety.

HTTP Response Codes:

• 200 OK: Facet successfully removed from current context (or dry-run completed)
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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, parent Resources, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.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 Facet and its related elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets.

Input Processing:

• The type name must be a valid Facet type in the Information System model
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet)
• Type name is case-sensitive and must match exactly.

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Facet-Specific Context Propagation Rules:

• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• Associated Resources: Parent Resources connected to the Facet via ConsistsOf relations are automatically affected based on propagation constraints
• ConsistsOf Relations: All ConsistsOf relations connecting parent Resources to this Facet are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Facet is removed from a context, related Resources may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Facets and ConsistsOf Relations:

• When a Facet is removed from a context, the parent Resources are automatically validated against their schema definitions
• If any parent Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet from a Resource; • Removing Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make parent Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove Facets.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove a StateFacet from the current context with actual changes
 UUID stateFacetUUID = UUID.fromString("...");
 List<ERElement> affected = publisher.removeFacetFromCurrentContext("StateFacet", stateFacetUUID, false);
 
 // Preview what would be affected by removing an AccessPointFacet from the current context
 UUID accessPointUUID = UUID.fromString("...");
 List<ERElement> preview = publisher.removeFacetFromCurrentContext("AccessPointFacet", accessPointUUID, true);
 

Parameters:

facetType - The exact type name of the Facet to remove

facetUUID - The UUID of the Facet instance to remove from the current context

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

removeFacetFromCurrentContext

<F extends org.gcube.informationsystem.model.reference.entities.Facet>
List<org.gcube.informationsystem.model.reference.ERElement> removeFacetFromCurrentContext(F facet,
 Boolean dryRun)
                                                                                   throws org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException,
org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Removes a Facet instance from the current context using a provided Facet object. Corresponding REST API: POST /sharing/contexts/{facet-type-name}/{uuid}?operation=REMOVE[&dryRun={true|false}][&includeMeta={true|false}][&allMeta={true|false}][&includeContexts={true|false}] Operation Behavior:

• Removes an existing Facet instance from the current context derived from the authorization token
• The type and UUID are automatically extracted from the provided Facet object
• The Facet must already exist and be accessible in the current context where the user is performing the request
• The user must have the rights to perform such a request in the current context
• Returns the list of affected elements (the Facet itself and any related elements that are also removed)
• Supports dry-run mode to preview changes without applying them
• This is a convenience method that uses the current context instead of requiring an explicit context UUID
• This method provides compile-time type safety for Facet types.

HTTP Response Codes:

• 200 OK: Facet successfully removed from current context (or dry-run completed)
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: User lacks permissions to perform the request in the current context
• 400 Bad Request: Invalid parameters or schema validation failure
• 401 Unauthorized: Invalid or missing authentication credentials.

Query Parameters: includeMeta (configurable via client configuration):

• Whether to include metadata in the response for affected instances
• Default value: false (basic information only)
• Usage: publisher.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, parent Resources, etc.) in the response
• Must be used in conjunction with includeMeta=true
• Default value: false (metadata only for main instance, more human-readable)
• Usage: publisher.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 Facet and its related elements are available in the response
• Default value: false (context information not included)
• Usage: publisher.setIncludeContexts(true)
• Values: true (shows context availability) | false (no context information)
• Query parameter: InstancePath.INCLUDE_CONTEXTS_QUERY_PARAMETER
• Note: A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Note: ConsistsOf relations are present in all contexts where their target Facets are present
• Note: A Resource is present in all contexts that form the union of contexts of all its Facets.

Input Processing:

• The type name is automatically derived from the provided Facet object using TypeUtility.getTypeName(Class)
• The UUID is extracted from the Facet's header
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet).

Current Context:

• The current context is automatically derived from the authorization token provided during client creation
• No explicit context UUID is required
• The user must have appropriate permissions in this context.

Facet-Specific Context Propagation Rules:

• Facets: When removed from a context, the parent Resource that references it (via ConsistsOf relation) may also be removed from the same context if the Facet was required for the Resource's presence in that context
• Associated Resources: Parent Resources connected to the Facet via ConsistsOf relations are automatically affected based on propagation constraints
• ConsistsOf Relations: All ConsistsOf relations connecting parent Resources to this Facet are also removed from the context.

Propagation Constraints and Cascade Effects:

• When a Facet is removed from a context, related Resources may also be automatically removed due to propagation constraints
• The response includes all instances that were removed as part of the cascade effect
• Propagation follows the schema-defined relationships and their constraints.

Schema Validation for Facets and ConsistsOf Relations:

• When a Facet is removed from a context, the parent Resources are automatically validated against their schema definitions
• If any parent Resource is no longer compliant with its schema after the remove operation, a SchemaViolationException is thrown
• This results in an HTTP 400 Bad Request response with details about the schema violation
• Example scenarios that violate schema constraints:

• Removing a required/mandatory Facet from a Resource; • Removing Facets that violate cardinality constraints (min occurrences) defined in the schema; • Operations that make parent Resources incomplete or invalid according to their schema definition.

• Constraint Sources: Constraints are defined by the specific Resource type definitions that have been installed on the system
• Schema validation ensures the integrity and consistency by enforcing the constraints defined in each Resource type's schema during operations.

Authorization Requirements:

• All users must have a valid token and appropriate permissions for the current context where they want to remove Facets.
• The current context is derived from the authorization token provided during client creation.

IS-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Infrastructure-Manager:

• Can perform REMOVE operations on any Facet in any context
• Full administrative privileges across all contexts
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Context-Manager:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to contexts where they have Context-Manager role
• See complete metadata including sensitive information (createdBy, lastUpdatedBy) when includeMeta=true.

Other Users:

• Can perform REMOVE operations only on Facets accessible in their current context
• Operations are limited to Facets they have access to in their authorized context
• See filtered metadata with sensitive fields obfuscated when includeMeta=true.

Response Format:

• Returns a JSON array containing all instances affected by the operation
• Each instance object includes its UUID, type, and relevant metadata
• For dryRun=true: Shows what would be affected without making changes
• For dryRun=false: Shows what was actually affected by the completed operation.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Remove a StateFacet instance from the current context
 StateFacet facet = publisher.read(StateFacet.class, facetUUID);
 List<ERElement> affected = publisher.removeFacetFromCurrentContext(facet, false);
 
 // Preview what would be affected by removing an AccessPointFacet from the current context
 AccessPointFacet accessPoint = publisher.read(AccessPointFacet.class, accessPointUUID);
 List<ERElement> preview = publisher.removeFacetFromCurrentContext(accessPoint, true);
 

Type Parameters:

F - The specific type of Facet to remove

Parameters:

facet - The Facet instance to remove from the current context (must contain a valid UUID in the header)

dryRun - Whether to perform a dry-run (true) or apply actual changes (false)

Returns:

List of all elements affected by this operation (including the Facet itself and any related elements)

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.types.SchemaViolationException - If the operation violates Information System model constraints (HTTP 400)

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the Facet is not found or not accessible (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.contexts.ContextNotFoundException - If the current context cannot be determined or accessed (HTTP 404)

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during the remove operation

getFacetContexts

Map<UUID,String> getFacetContexts(String facetType,
 UUID facetUUID)
                           throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Facet is present in the Resource Registry. Corresponding REST API: GET /instances/{facet-type-name}/{facet-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified Facet is present
• The Facet 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 Facet's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Facet does not exist with the specified type and UUID
• 403 Forbidden: Facet 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 Facet across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any Facet across the entire infrastructure
• Context-Manager: Can retrieve context information for Facets accessible within their managed contexts
• Other Users: Can retrieve context information for Facets 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 Facet exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Facet Context Rules:

• Facets: Present in the contexts where they are explicitly available
• A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Facets are present in contexts based on their direct context assignments and their association with Resources.

Type Safety:

• This method is specifically designed for Facet types and provides compile-time type safety
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet, SoftwareFacet).

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Get contexts for a ContactFacet by type and UUID
 UUID contactUuid = UUID.fromString("4023d5b2-8601-47a5-83ef-49ffcbfc7d86");
 Map<UUID, String> contexts = publisher.getFacetContexts("ContactFacet", contactUuid);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Parameters:

facetType - The exact type name of the Facet (e.g., "ContactFacet", "StateFacet")

facetUUID - The unique identifier of the Facet whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the Facet is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If no Facet is found with the specified type and UUID

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval

getFacetContexts

<F extends org.gcube.informationsystem.model.reference.entities.Facet>
Map<UUID,String> getFacetContexts(F facet)
                           throws org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException,
org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException

Retrieves the list of contexts where a specific Facet is present in the Resource Registry. Corresponding REST API: GET /instances/{facet-type-name}/{facet-uuid}/contexts Operation Behavior:

• Retrieves all contexts where the specified Facet object is present
• The Facet's type and UUID are automatically extracted from the provided object
• The Facet 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 Facet's presence across different VREs and organizational contexts.

HTTP Response Codes:

• 200 OK: Context list successfully retrieved
• 404 Not Found: Facet does not exist or is not accessible
• 403 Forbidden: Facet 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 Facet across the entire infrastructure
• Infrastructure-Manager: Can retrieve context information for any Facet across the entire infrastructure
• Context-Manager: Can retrieve context information for Facets accessible within their managed contexts
• Other Users: Can retrieve context information for Facets 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 Facet exists but is not present in any contexts
• Each context path represents the complete hierarchical path (e.g., "/gcube/devsec/devVRE").

Facet Context Rules:

• Facets: Present in the contexts where they are explicitly available
• A Facet's context availability depends on the Resources that include it via ConsistsOf relations
• Facets are present in contexts based on their direct context assignments and their association with Resources.

Type Safety:

• This method provides compile-time type safety by accepting any Facet subtype
• The Facet's type is automatically determined from the object's class
• Supports all Facet types and their specializations (e.g., StateFacet, ContactFacet, AccessPointFacet, SoftwareFacet).

Object-based Operation:

• This method accepts a Facet instance object directly, which provides convenience and type safety
• The Facet object must contain a valid UUID in its header metadata
• The type is automatically inferred from the object's runtime class.

Example Usage:

 ResourceRegistryPublisher publisher = ResourceRegistryPublisherFactory.create();
 
 // Assuming you have a ContactFacet instance
 ContactFacet contact = ...; // Retrieved from previous operations
 
 // Get contexts for the facet object
 Map<UUID, String> contexts = publisher.getFacetContexts(contact);
 
 // Process the results
 for (Map.Entry<UUID, String> entry : contexts.entrySet()) {
     System.out.println("Context UUID: " + entry.getKey() + " -> Path: " + entry.getValue());
 }
 

Type Parameters:

F - The type of Facet (ContactFacet, StateFacet, AccessPointFacet, etc.)

Parameters:

facet - The Facet instance whose contexts to retrieve

Returns:

Map containing context UUID to context path mappings where the Facet is present

Throws:

org.gcube.informationsystem.resourceregistry.api.exceptions.entities.facet.FacetNotFoundException - If the specified Facet does not exist or is not accessible

org.gcube.informationsystem.resourceregistry.api.exceptions.ResourceRegistryException - If an error occurs during context retrieval