Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

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
Copiar o link

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
Copiar o link

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
Copiar o link

  • 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
Copiar o link

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

5.1.4. Result Objects
Copiar o link

  • 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");
Copy to Clipboard Toggle word wrap

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
Copiar o link

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
Copiar o link

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}
Copy to Clipboard Toggle word wrap

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"
  }
}
Copy to Clipboard Toggle word wrap
  • 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
Copiar o link

Retrieve Protobuf schema from Data Grid with GET requests. 

GET /rest/v2/schemas/{schemaName}
Copy to Clipboard Toggle word wrap

5.2.3. Updating Protobuf Schemas
Copiar o link

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}
Copy to Clipboard Toggle word wrap

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"
  }
}
Copy to Clipboard Toggle word wrap
  • 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
Copiar o link

Remove Protobuf schemas from Data Grid clusters with DELETE requests. 

DELETE /rest/v2/schemas/{schemaName}
Copy to Clipboard Toggle word wrap

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

5.2.5. Listing Protobuf Schemas
Copiar o link

List all available Protobuf schemas with GET requests. 

GET /rest/v2/schemas/
Copy to Clipboard Toggle word wrap

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
}]
Copy to Clipboard Toggle word wrap
  • 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
Copiar o link

List all available Protobuf types with GET requests. 

GET /rest/v2/schemas?action=types
Copy to Clipboard Toggle word wrap

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

["org.infinispan.Person", "org.infinispan.Phone"]
Copy to Clipboard Toggle word wrap
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2026 Red HatVoltar ao topo