Red Hat Summit Red Hat SummitSupportoConsoleSviluppatoriInizia una provaContatti

Questo contenuto non è disponibile nella lingua selezionata.

Chapter 5. Managing schemas in Data Grid

This documentation explains how to create, register, and manage Protostream schemas in Data Grid. Schemas are registered in the Data Grid server and/or client so that ProtoStream knows how to interpret data in the caches.

5.1. Hotrod Java Client management API
Copia collegamento

The RemoteSchemasAdmin interface provides methods to manage Protostream schemas in a remote Data Grid server. It allows you to create, update, retrieve, and delete schemas, as well as check for validation errors. This API is marked as @Experimental and may change in future releases.

5.1.1. Overview
Copia collegamento

Schemas define how objects are serialized and deserialized using Protostream. With RemoteSchemasAdmin, you can perform schema operations programmatically through the Hot Rod client.

5.1.2. Key Operations
Copia collegamento

  • Get a schema Retrieve a schema by name.

    • get(String schemaName)
    • getAsync(String schemaName)

  • Retrieve schema errors Check if a schema has validation or parsing errors.

    • retrieveError(String schemaName)
    • retrieveAllSchemaErrors()

  • Create a schema Add a new schema from a Schema object or FileDescriptorSource.

    • create(Schema schema)
    • create(FileDescriptorSource fileDescriptorSource)

  • Update a schema Update an existing schema safely or force the update.

    • update(Schema schema, boolean force)
    • update(FileDescriptorSource fileDescriptorSource)

  • Create or update a schema Create the schema if it does not exist, or update it if it does.

    • createOrUpdate(Schema schema, boolean force)
    • createOrUpdate(FileDescriptorSource fileDescriptorSource)

  • Delete a schema Remove a schema by name, with optional force to bypass cache dependencies. If a cache uses one of the schema messages for indexing, the remove operation fails unless force is set to true.

    • remove(String schemaName, boolean force)

  • Check schema existence Verify if a schema is already registered.

    • exists(String schemaName)

5.1.3. Async Support
Copia collegamento

All operations have asynchronous variants that return CompletionStage<T> for non-blocking execution.

5.1.4. Result Objects
Copia collegamento

  • SchemaOpResult — Holds the operation result type (CREATED, UPDATED, DELETED, NONE, ERROR) and any validation errors.
  • SchemaErrors — Contains multiple schema errors mapped by schema name.

Schema management API example

// create or obtain your RemoteCacheManager
RemoteCacheManager manager = ...;
RemoteSchemasAdmin schemasAdmin = manager.administration().schemas();

Schema schema = Schema.buildFromStringContent("schema.proto", "message M { optional string json_key = 1; }");

// Create or Update schema - non-blocking
schemasAdmin.createOrUpdateAsync(schema);

// Create or Update schema - blocking
RemoteSchemasAdmin.SchemaOpResult result = schemasAdmin.createOrUpdate(schema);

// Prints 'true' if the schema validation reported an error
System.out.println(result.hasError());

// Prints an error if such exist
System.out.println(result.getError());

// Gets the op type : CREATE, UPDATE or NONE if nothing has been done.
System.out.println(result.getType());

// Prints an error if such exist
System.out.println(schemasAdmin.retrieveError("schema.proto"));

// Gets the schema if such exist
Optional<Schema> = schemasAdmin.get("schema.proto");

// Removes the schema if such exists
schemasAdmin.remove("schema.proto");

Note
  • Schema updates are version-safe unless forced.
  • For large deployments, use asynchronous methods to avoid blocking client threads.
  • Forced operations (force=true) should be used cautiously to prevent errors.

5.2. Schema Management in the Console
Copia collegamento

From the Data Grid web console, you can list, create, update, and manage schemas, and reindex the related caches. The web interface is simple and easy to use.

Figure 5.1. Schemas management interface

schemas admin console

5.2.1. Creating Protobuf Schemas
Copia collegamento

Create Protobuf schemas across Data Grid clusters with POST requests that include the content of a protobuf file in the payload. 

POST /rest/v2/schemas/{schemaName}

If the schema already exists, Data Grid returns HTTP 409 (Conflict). If the schema is not valid, either because of syntax errors, or because some of its dependencies are missing, Data Grid stores the schema and returns the error in the response body.

Data Grid responds with the schema name and any errors. 

{
  "name" : "users.proto",
  "error" : {
    "message": "Schema users.proto has errors",
    "cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
  }
}
  • name is the name of the Protobuf schema.
  • error is null for valid Protobuf schemas. If Data Grid cannot successfully validate the schema, it returns errors.

If the operation successfully completes, the service returns 201 (Created).

5.2.2. Reading Protobuf Schemas
Copia collegamento

Retrieve Protobuf schema from Data Grid with GET requests. 

GET /rest/v2/schemas/{schemaName}

5.2.3. Updating Protobuf Schemas
Copia collegamento

Modify Protobuf schemas with PUT requests that include the content of a protobuf file in the payload.

Important

When you make changes to the existing Protobuf schema definition, you must either update or rebuild the index schema. If the changes involve modifying the existing fields, then you must rebuild the index. When you add new fields without touching existing schema, you can update the index schema instead of rebuilding it. 

PUT /rest/v2/schemas/{schemaName}

If the schema is not valid, either because of syntax errors, or because some of its dependencies are missing, Data Grid updates the schema and returns the error in the response body. 

{
  "name" : "users.proto",
  "error" : {
    "message": "Schema users.proto has errors",
    "cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
  }
}
  • name is the name of the Protobuf schema.
  • error is null for valid Protobuf schemas. If Data Grid cannot successfully validate the schema, it returns errors.

5.2.4. Deleting Protobuf Schemas
Copia collegamento

Remove Protobuf schemas from Data Grid clusters with DELETE requests. 

DELETE /rest/v2/schemas/{schemaName}

If the operation successfully completes, the service returns 204 (No Content).

5.2.5. Listing Protobuf Schemas
Copia collegamento

List all available Protobuf schemas with GET requests. 

GET /rest/v2/schemas/

Data Grid responds with a list of all schemas available on the cluster. 

[ {
  "name" : "users.proto",
  "error" : {
    "message": "Schema users.proto has errors",
    "cause": "java.lang.IllegalStateException:Syntax error in error.proto at 3:8: unexpected label: messoge"
  }
}, {
  "name" : "people.proto",
  "error" : null
}]
  • name is the name of the Protobuf schema.
  • error is null for valid Protobuf schemas. If Data Grid cannot successfully validate the schema, it returns errors.

5.2.6. Listing Protobuf Types
Copia collegamento

List all available Protobuf types with GET requests. 

GET /rest/v2/schemas?action=types

Data Grid responds with a list of all types available on the cluster. 

["org.infinispan.Person", "org.infinispan.Phone"]
Red Hat logoGithubredditYoutubeTwitter

Formazione

Prova, acquista e vendi

Community

Informazioni sulla documentazione di Red Hat

Aiutiamo gli utenti Red Hat a innovarsi e raggiungere i propri obiettivi con i nostri prodotti e servizi grazie a contenuti di cui possono fidarsi. Esplora i nostri ultimi aggiornamenti.

Rendiamo l’open source più inclusivo

Red Hat si impegna a sostituire il linguaggio problematico nel codice, nella documentazione e nelle proprietà web. Per maggiori dettagli, visita il Blog di Red Hat.

Informazioni su Red Hat

Forniamo soluzioni consolidate che rendono più semplice per le aziende lavorare su piattaforme e ambienti diversi, dal datacenter centrale all'edge della rete.

Theme

© 2026 Red HatTorna in cima