# Resource Registry Ecosystem: Tooling & Clients

This chapter provides an overview of the Java ecosystem, libraries, and clients available to support the development and integration with the Resource Registry. The ecosystem is designed to be highly modular, minimizing dependencies and simplifying the interaction with the underlying Information System (IS).

## The `information-system-model` Library

The `information-system-model` Java library provides much more than just a set of base classes. It acts as a comprehensive toolkit for developers looking to interact with or extend the IS-Model.

### Type Generation via Annotations

Instead of requiring developers to manually write complex JSON Type schemas by hand, the library relies on a rich set of Java annotations.
By defining **Resource**, **Facet**, and **Relation** schemas as annotated Java classes, developers leverage the Java compiler and IDE features (like autocompletion and Javadoc) as "first-class citizens". The library automatically parses these annotations to generate the strict, compliant JSON Type representation required by the Resource Registry APIs.
*(Note: A developer is free to use pure POJOs for marshalling/unmarshalling without annotations, but they must manually provide the JSON schema for Type Registration).*

### Model Extension Discovery

The library includes a powerful *Discovery* utility class capable of scanning the Java classpath to dynamically find all custom extensions of the IS-Model.
This is heavily used during the Resource Registry startup and Database initialization phases to automatically locate, translate, and register new Type schemas into the information system without manual configuration.

### Marshalling, Unmarshalling, and Utilities

The library provides native, robust marshalling and unmarshalling capabilities to effortlessly convert between the JSON representations returned by the REST APIs and strongly-typed Java objects. It also includes utility methods to facilitate graph navigation and payload manipulation.

## Automated Documentation Generator

The ecosystem includes the `information-system-model-documentation-generator` library.
This tool programmatically inspects the Java annotations embedded in the `information-system-model` (and any of its extensions, like `gcube-model`) to auto-generate the official reference documentation, including the appendix of this documentation.

Because the Java code inherently serves as the single source of truth for the model's structural constraints (cardinalities, descriptions, validation rules), this generator ensures the documentation is always perfectly aligned with the runtime validation schemas.

## Modular REST Clients

To enforce the principle of least privilege and minimize the dependency footprint (avoiding a monolithic "mega-client" that drags unnecessary transitive dependencies), the Resource Registry provides a suite of strictly segregated Java clients.

Each client corresponds to a specific REST API port-type (collection). An integrator only needs to import the client(s) relevant to their specific operational scope:

- **`resource-registry-context-client`**: A lightweight client dedicated exclusively to managing and querying the Context hierarchy (`/contexts`). Perfect for administrative services that need to configure tenant visibility and VRE lifecycle.
- **`resource-registry-schema-client`**: Focused on Type management (`/types`). Primarily used by administrative and bootstrapping tools to register DDL schemas and inspect type definitions. Provides in-memory snapshot reads (`read`, `exist`) as well as direct server-side read operations (`getTypeFromServer`, `existTypeFromServer`).
- **`resource-registry-publisher`**: The primary write-capable client operating against the `/instances` endpoints. Used for managing (creating, updating, deleting) **Resource**, **Facet**, **IsRelatedTo**, and **ConsistsOf** instances, as well as orchestrating Context membership (sharing operations). Supports cross-SDK parity aliases (`getInstances`, `jsonQuery`).
- **`resource-registry-query-template-client`**: Dedicated to managing and executing stored Query Templates (`/query-templates`), ideal for UI dashboards or reporting microservices. Provides definition discovery (`all`, `list`, `query`, `jsonQuery`) and instance execution (`run`, `runGetString`).
- **`resource-registry-client`**: The primary read-only client operating against the `/access` facade. Because the `/access` facade mirrors all read operations across the entire infrastructure, this client provides safe, internet-facing methods for discovering and reading Contexts, Types, Query Templates, and Instances, as well as executing queries. Supports cross-SDK parity aliases (`list`, `query`, `getInstanceContexts`).

*(Note: `resource-registry-publisher` and other write-capable clients operate against endpoints restricted to internal microservice traffic. `resource-registry-client` is the appropriate client for any component deployed in an internet-accessible network zone).*

### Client API Alignment & Parity

To provide a consistent developer experience across read-only and write-capable SDKs, common operations share aligned method names and native convenience aliases:

| Operation | Read Client (`resource-registry-client`) | Publisher (`resource-registry-publisher`) | Schema Client (`resource-registry-schema-client`) |
|---|---|---|---|
| **List Instances** | `getInstances(...)` / `list(...)` | `list(...)` / `getInstances(...)` | — |
| **Instance Query** | `jsonQuery(...)` / `query(...)` | `query(...)` / `jsonQuery(...)` | — |
| **Instance Contexts** | `getInstanceContexts(...)` | `getElementContexts(...)` / `getInstanceContexts(...)` | — |
| **Server-Side Type Read** | `readType(...)` (via `/access/types`) | — | `getTypeFromServer(...)`, `existTypeFromServer(...)` |
| **Local Cached Type Read** | — | — | `read(...)`, `exist(...)` (in-memory snapshot) |

### Request Options and Response Metadata

All modern Resource Registry clients share common cross-cutting mechanisms for option configuration and HTTP response inspection:

- **`ResourceRegistryRequestOptions`**: Configured per-request or via thread-local context (`RequestOptionsContext`). Allows setting pagination (`limit`, `offset`), traversal directives (`depth`, `hierarchical`, `polymorphic`), representation policies (`metadataPolicy`, `contextsPolicy`, `membershipScope`), and custom HTTP headers.
- **`serverResponses()` (`ResourceRegistryResponses`)**: Exposes observable response metadata from the most recent server interaction on that client, including HTTP status codes, canonical `Content-Location`, RFC 8288 `Link` headers (`first`, `prev`, `next`, `parent`, `collection`, `up`, `type`, `supertype`), `X-Warning` diagnostic tokens, and `X-Result-Scope` scope indicators.

### Summary

This segregated client architecture ensures that microservices only pull the dependencies they actually need. For example, if an external microservice only requires safe, read-only discovery of the infrastructure topology (Contexts and instances), it can exclusively import the `resource-registry-client` without carrying the weight of the publisher or schema management machinery. Conversely, a backend microservice strictly dedicated to provisioning new VREs only needs the `resource-registry-context-client`.
