キャッシュのエンコードとマーシャリング

ProtoStream ライブラリーを使用して、キャッシュエントリーを Protocol Buffers(Protobuf) として保存するように Data Grid を設定します。

<distributed-cache>
   <encoding>
      <key media-type="application/x-protostream"/>
      <value media-type="application/x-protostream"/>
   </encoding>
</distributed-cache>

//Create cache configuration that encodes keys and values as ProtoStream
ConfigurationBuilder builder = new ConfigurationBuilder();
builder.clustering().cacheMode(CacheMode.DIST_SYNC)
       .encoding().key().mediaType("application/x-protostream")
       .encoding().value().mediaType("application/x-protostream");

または、キーと値に同じエンコーディングを使用できます。

<encoding media-type="application/x-protostream"/>

.encoding().mediaType("application/x-protostream");

テキストベースのメディアタイプで鍵と値を格納するようにエンコーディングを設定する場合、これらのキャッシュで動作するようにクライアントを設定する必要もあります。

Hot Rod クライアント

Data Grid は ProtoStream ライブラリーを使用して、String および byte[] タイプをネイティブに処理します。text/plain メディアタイプでキャッシュエンコーディングを設定する場合、Hot Rod クライアントはキャッシュ操作を実行するためのマーシャラー設定を必要とするとは限りません。

JSON や XML などの他のテキストベースのメディアタイプでは、Hot Rod クライアントは、text/plain メディアタイプで変換する org.infinispan.commons.marshall.UTF8StringMarshaller マーシャラーを使用できます。

REST クライアント

REST クライアントには、要求ヘッダーにキャッシュのメディアタイプを含める必要があります。

たとえば、キャッシュエンコーディングを text/plain; charset=UTF-8 として設定した場合、REST クライアントは以下のヘッダーを送信します。

Hot Rod Java クライアントをマーシャラーを使用するように設定する場合は、そのマーシャラーのエンコーディングでキャッシュを設定する必要があります。

それぞれのマーシャラーは異なるメディアタイプを使用して、クライアントが Data Grid Server に送信できる byte[] コンテンツを生成します。サーバーから読み取る場合、クライアントマーシャラーは逆の操作を行います。メディアタイプを使用して byte[] コンテンツからデータを生成します。

キャッシュエンコーディングは Hot Rod クライアントマーシャラーと互換性がある必要があります。たとえば、キャッシュエンコーディングを application/x-protostream として設定している場合、クライアント上で ProtoStream マーシャラーを使用して、そのキャッシュ上で動作させることができます。ただし、クライアントマーシャラーが、Data Grid が application/x-protostream との間で変換できないエンコーディングを使用する場合、Data Grid はエラーメッセージを出力します。

JavaSerializationMarshaller または GenericJBossMarshaller を使用する場合は、キャッシュを application/x-java-serialized-object または application/x-jboss-marshalling メディアタイプでエンコードする必要があります。

これにより、REST クライアントは要求ヘッダーに JSON メディアタイプを追加し、ProtoStream エンコーディングを使用するキャッシュで操作を実行することができます。

Data Grid はこれを推奨しませんが、クライアントは application/x-java-object メディアタイプでアンマーシャリングされた POJO を格納するキャッシュで操作できます。

Hot Rod クライアント

Hot Rod クライアントマーシャラーは、Java オブジェクトをデシリアライズできるように Data Grid Server で利用できる必要があります。デフォルトでは、ProtoStream および Java Serialization マーシャラーはサーバー上で利用できます。

REST クライアント

REST クライアントは、キーと値に JSON または XML を使用し、Data Grid が POJO との間で変換できるようにします。

Data Grid は、キーと値の以下の型、およびプリミティブタイプの場合にボックスのない同等を処理できる ProtoStream ライブラリーを使用します。

追加のタイプコレクション

ProtoStream ライブラリーには、一般的な Java タイプ用のアダプタークラスが複数含まれます。以下に例を示します。

Data Grid は、protostream-types アーティファクトにある一部の一般的な JDK クラスのすべてのアダプタークラスを提供します。これは、infinispan-core および infinispan-client-hotrod 依存関係に含まれます。アダプタークラスをキーまたは値として保存する設定は必要ありません。

しかし、アダプタークラスを ProtoStream-annotated POJO でマーシャリング可能なフィールドとして使用する場合は、以下の方法で実行できます。

@ProtoSchema(dependsOn = {org.infinispan.protostream.types.java.CommonTypes, org.infinispan.protostream.types.java.CommonContainerTypes}, schemaFileName = "library.proto", schemaFilePath = "proto", schemaPackageName = "example")
public interface LibraryInitalizer extends SerializationContextInitializer {
}

@ProtoSchema(includeClasses = { Author.class, Book.class, UUIDAdapter.class, java.math.BigInteger }, schemaFileName = "library.proto", schemaFilePath = "proto", schemaPackageName = "library")
public interface LibraryInitalizer extends SerializationContextInitializer {

}

ProtoStream API には、Protobuf スキーマを定義するために Java アプリケーションに追加できるアノテーションが含まれます。これにより、オブジェクトに構造化された形式が提供されます。

このトピックでは、ProtoStream アノテーションに関する追加情報を提供します。詳細は、org.infinispan.protostream.annotations パッケージのドキュメントを参照してください。

Proto

@Proto は、すべてのフィールドに @ProtoField アノテーションを付ける必要なく、Protocol Buffers メッセージを定義します。

ProtoField

@ProtoField は Protobuf message フィールドを定義します。

このアノテーションは、フィールドだけでなく、getter メソッドと setter メソッドにも適用されます。@Proto アノテーションを使用していない限り、Data Grid が Protobuf としてマーシャリングする前に、クラスに @ProtoField アノテーションが付けられたフィールドを 1 つ以上設定する必要があります。

ProtoFactory

@ProtoFactory は、メッセージクラスのインスタンスを作成するための単一のコンストラクターまたは静的ファクトリーメソッドをマークします。

このアノテーションを使用してイミュータブルメッセージクラスをサポートすることができます。@ProtoField アノテーションが付けられたフィールドはすべてパラメーターに追加する必要があります。

ProtoSchema

@ProtoSchema は、SerializationContextInitializer を拡張するクラスまたはインターフェイスの実装を生成します。

アクティブの場合、ProtoStream プロセッサーは、Impl 接尾辞または className パラメーターで指定した名前と同じパッケージで、コンパイル時に実装を生成します。

includeClasses または basePackages パラメーターは、ProtoStream プロセッサーがスキャンして Protobuf スキーマおよびマーシャラーに含める必要があるクラスを参照します。これらのパラメーターのいずれかを設定しないと、ProtoStream プロセッサーはソースパス全体をスキャンします。これにより、予期しない結果が発生する可能性があり、推奨されません。basePackages パラメーターと excludeClasses パラメーターを使用して、クラスを除外することもできます。

schemaFileName パラメーターおよび schemaPackageName パラメーターは、この名前で生成された Protobuf スキーマを登録します。これらのパラメーターを設定しないと、アノテーション付きの単純なクラス名が名前なしのパッケージ、またはデフォルトパッケージで使用されます。スキーマ名は、.proto ファイル拡張子で終了する必要があります。marshallersOnly を使用してマーシャラーのみを生成し、Protobuf スキーマの生成を抑制することもできます。

ProtoStream プロセスは、META-INF/services サービスメタデータファイルを自動的に生成します。このファイルを使用すると、Data Grid Server が JAR を自動的に検出して Protobuf スキーマを登録します。

dependsOn パラメーターは、最初に実行するように SerializedContextInitializer を実装するアノテーション付きクラスをリスト表示します。クラスが SerializedContextInitializer を実装していない場合、または ProtoSchema でアノテーションが付けられていない場合は、コンパイル時エラーが発生します。

ProtoAdapter

@ProtoAdapter は、直接アノテーションを付けることができないクラスまたは列挙のマーシャリングアダプターです。

以下の項目に、このアノテーションを使用する場合、

ProtoName

@ProtoName は、Protobuf メッセージまたは列挙型の名前を指定するオプションのアノテーションです。クラス、レコード、列挙で使用できます。

ProtoEnumValue

@ProtoEnumValue は Protobuf 列挙値を定義します。このアノテーションは、Java enum のメンバーにのみ適用できます。

ProtoReserved および ProtoReservedStatements

@ProtoReserved および @ProtoReservedStatements は、生成されたメッセージまたは列挙定義に reserved ステートメントを追加し、番号、範囲、および名前の使用を防ぎます。

ProtoTypeId

@ProtoTypeId は任意で、Protobuf メッセージまたは enum タイプのグローバル一意の数値型識別子を指定します。

ProtoUnknownFieldSet

@ProtoUnknownFieldSet はオプションで、未知のフィールドを保存するタイプ {@link org.infinispan.protostream.UnknownFieldSet} のフィールドまたは JavaBean プロパティーを示します。

その他の注釈

Data Grid は、クラス、フィールド、およびメソッドのその他の注釈を、生成された Protobuf スキーマにコメントとしてコピーします。これには、@Indexed や @Basic などの索引付けアノテーションが含まれます。

Data Grid は、コンパイル時にクラスの Java アノテーションを処理する ProtoStream プロセッサーアーティファクトを提供し、Protobuf スキーマ、付随マーシャラー、および SerializationContextInitializer インターフェイスの具体的な実装を生成します。

Java クラスとそのメンバーにアノテーションを追加して ProtoStream メタデータを宣言します。次に、Data Grid は ProtoStream プロセッサーを使用して Protobuf スキーマと、それらのアノテーションから関連するマーシャラーを生成します。

以下の Author.java および Book.java の例は、@ProtoField および @ProtoFactory のアノテーションが付けられた Java クラスを示しています。

import org.infinispan.protostream.annotations.ProtoFactory;
import org.infinispan.protostream.annotations.ProtoField;

public class Author {
   @ProtoField(1)
   final String name;

   @ProtoField(2)
   final String surname;

   @ProtoFactory
   Author(String name, String surname) {
      this.name = name;
      this.surname = surname;
   }
   // public Getter methods omitted for brevity
}

import org.infinispan.protostream.annotations.ProtoFactory;
import org.infinispan.protostream.annotations.ProtoField;

public class Book {
   @ProtoField(number = 1)
   public final UUID id;

   @ProtoField(number = 2)
   final String title;

   @ProtoField(number = 3)
   final String description;

   @ProtoField(number = 4, defaultValue = "0")
   final int publicationYear;

   @ProtoField(number = 5, collectionImplementation = ArrayList.class)
   final List<Author> authors;

   @ProtoField(number = 6)
   public Language language;

   @ProtoFactory
   Book(UUID id, String title, String description, int publicationYear, List<Author> authors, Language language) {
      this.id = id;
      this.title = title;
      this.description = description;
      this.publicationYear = publicationYear;
      this.authors = authors;
      this.language = language;
   }
   // public Getter methods not included for brevity
}

以下の Language.java の例は、対応する Protobuf スキーマとともに @ProtoEnumValue アノテーションが付けられた Java 列挙を示しています。

import org.infinispan.protostream.annotations.ProtoEnumValue;

public enum Language {
  @ProtoEnumValue(number = 0, name = "EN")
  ENGLISH,
  @ProtoEnumValue(number = 1, name = "DE")
  GERMAN,
  @ProtoEnumValue(number = 2, name = "IT")
  ITALIAN,
  @ProtoEnumValue(number = 3, name = "ES")
  SPANISH,
  @ProtoEnumValue(number = 4, name = "FR")
  FRENCH;

}

enum Language {

   EN = 0;

   DE = 1;

   IT = 2;

   ES = 3;

   FR = 4;
}

ProtoStream は @ProtoAdapter アノテーションを提供し、これを使用して、直接アノテーションを付けることができない外部のサードパーティーの Java オブジェクトクラスをマーシャリングすることができます。

ProtoStream プロセッサーを追加して Java クラスにアノテーションを付けると、Data Grid が Protobuf スキーマ、付随するマーシャラー、および SerializationContextInitializer の具体的な実装を生成するように、@ProtoSchema アノテーションをインターフェイスに追加できます。

次の例は、@ProtoSchema でアノテーションが付けられた GeneratedSchema インターフェイスを示しています。

@ProtoSchema(
      includeClasses = {
            Book.class,
            Author.class,
            UUIDAdapter.class,
            Language.class
      },
      schemaFileName = "library.proto",
      schemaFilePath = "proto/",
      schemaPackageName = "book_sample")
interface LibraryInitializer extends GeneratedSchema {
}

リモートキャッシュを使用する場合は、SerializationContextInitializer 実装を Data Grid Server に登録する必要があります。

Protocol Buffers のドキュメントには、下位互換性を維持するためにメッセージを設計する方法とスキーマを 進化させる 方法に関する ベストプラクティス のリストが記載されています。

Data Grid は、スキーマが更新されたときに自動的に互換性チェックを実行し、非互換性が検出された場合は更新を拒否できます。チェックの種類は、グローバル serialization 設定の schema-compatibility 属性を介して設定できます。利用可能なレベルは次のとおりです。

次の表は、各レベルで有効になっている互換性チェックルールを示しています。

組み込みキャッシュの場合、Data Grid は java.util.ServiceLoader を使用してアノテーションが付けられた SerializationContextInitializer 実装にシリアル化コンテキストおよびマーシャラーを自動的に登録します。

必要に応じて、SerializationContextInitializer 実装の自動登録を無効にして、手動で登録することができます。

<serialization>
    <context-initializer class="org.infinispan.example.LibraryInitializerImpl"/>
    <context-initializer class="org.infinispan.example.another.SCIImpl"/>
</serialization>

GlobalConfigurationBuilder builder = new GlobalConfigurationBuilder();
builder.serialization()
       .addContextInitializers(new LibraryInitializerImpl(), new SCIImpl());

Ickle クエリーを実行する場合、または application/x-protostream から application/json などの他のメディアタイプに変換する場合は、Data Grid Server に Protobuf スキーマを登録する必要があります。

ConfigurationBuilder remoteBuilder = new ConfigurationBuilder();
remoteBuilder.addServer().host(host).port(Integer.parseInt(port));

// Add your generated SerializationContextInitializer implementation.
LibraryInitalizer initializer = new LibraryInitalizerImpl();
remoteBuilder.addContextInitializer(initializer);

ProtobufTagMarshaller および RawProtobufMarshaller アノテーションを使用して SerializationContextInitializer または GeneratedSchema インターフェイスを手動で実装できます。

ただし、手動の実装には多くの面倒なオーバーヘッドが必要で、エラーが発生する可能性が高くなります。protostream-processor アーティファクトを使用して生成する実装は、ProtoStream マーシャリングを設定するより効率的で信頼できる方法です。