Chapter 5. Configuring Data Grid to Marshall Java Objects

Procedure

1. Add the protostream-processor dependency to your pom.xml.

   <dependencyManagement>
     <dependencies>
       <dependency>
         <groupId>org.infinispan</groupId>
         <artifactId>infinispan-bom</artifactId>
         <version>${version.infinispan}</version>
         <type>pom</type>
       </dependency>
     </dependencies>
   </dependencyManagement>
   
   <dependencies>
     <dependency>
       <groupId>org.infinispan.protostream</groupId>
       <artifactId>protostream-processor</artifactId>
       <!--
         This dependency should be declared in the "provided" scope or made "optional"
         because it is a compile-only dependency and is not required at runtime.
         Transitive propagation of this dependency should be also be avoided.
       -->
       <scope>provided</scope>
     </dependency>
   </dependencies>

2. Annotate the Java objects that you want to marshall with @ProtoField and @ProtoFactory.

   Author.java

   import org.infinispan.protostream.annotations.ProtoFactory;
   import org.infinispan.protostream.annotations.ProtoField;
   
   public class Author {
      @ProtoField(number = 1)
      final String name;
   
      @ProtoField(number = 2)
      final String surname;
   
      @ProtoFactory
      Author(String name, String surname) {
         this.name = name;
         this.surname = surname;
      }
      // public Getter methods omitted for brevity
   }

   Book.java

   import org.infinispan.protostream.annotations.ProtoFactory;
   import org.infinispan.protostream.annotations.ProtoField;
   ...
   
   public class Book {
      @ProtoField(number = 1)
      final String title;
   
      @ProtoField(number = 2)
      final String description;
   
      @ProtoField(number = 3, defaultValue = "0")
      final int publicationYear;
   
      @ProtoField(number = 4, collectionImplementation = ArrayList.class)
      final List<Author> authors;
   
      @ProtoFactory
      Book(String title, String description, int publicationYear, List<Author> authors) {
         this.title = title;
         this.description = description;
         this.publicationYear = publicationYear;
         this.authors = authors;
      }
      // public Getter methods omitted for brevity
   }

3. Define an interface that extends SerializationContextInitializer and is annotated with @AutoProtoSchemaBuilder.

   @AutoProtoSchemaBuilder(
         includeClasses = {
               Book.class,
               Author.class,
         },
         schemaFileName = "library.proto", 1
         schemaFilePath = "proto/", 2
         schemaPackageName = "book_sample")
   interface LibraryInitializer extends SerializationContextInitializer {
   }

   1

   Names the generated .proto schema file.

   2

   Sets the path under target/classes where the schema file is generated.

Procedure

1. Create a Protobuf schema, .proto file, that provides a structured representations of the Java objects to marshall.

   package book_sample;
   
   message Book {
       optional string title = 1;
       optional string description = 2;
       optional int32 publicationYear = 3; // no native Date type available in Protobuf
   
       repeated Author authors = 4;
   }
   
   message Author {
       optional string name = 1;
       optional string surname = 2;
   }

   The preceding .library.proto file defines an entity (Protobuf message type) named Book that is contained in the book_sample package. Book declares several fields of primitive types and an array (Protobuf repeatable field) named authors, which is the Author message type.

   • You can nest messages but the resulting structure is strictly a tree, never a graph.
   • Type inheritance is not possible.
   • Collections are not supported but you can emulate arrays with repeated fields.

2. Use the org.infinispan.protostream.MessageMarshaller interface to implement marshallers for your classes.

   Note

   The MessageMarshaller interface is now deprecated.

   The next version of Data Grid provides an alternative implementation that lets you create an adaptor class that uses the @ProtoAdaptor annotation for any external, third-party Java object classes.

   BookMarshaller.java

   import org.infinispan.protostream.MessageMarshaller;
   
   public class BookMarshaller implements MessageMarshaller<Book> {
   
      @Override
      public String getTypeName() {
         return "book_sample.Book";
      }
   
      @Override
      public Class<? extends Book> getJavaClass() {
         return Book.class;
      }
   
      @Override
      public void writeTo(MessageMarshaller.ProtoStreamWriter writer, Book book) throws IOException {
         writer.writeString("title", book.getTitle());
         writer.writeString("description", book.getDescription());
         writer.writeInt("publicationYear", book.getPublicationYear());
         writer.writeCollection("authors", book.getAuthors(), Author.class);
      }
   
      @Override
      public Book readFrom(MessageMarshaller.ProtoStreamReader reader) throws IOException {
         String title = reader.readString("title");
         String description = reader.readString("description");
         int publicationYear = reader.readInt("publicationYear");
         List<Author> authors = reader.readCollection("authors", new ArrayList<>(), Author.class);
         return new Book(title, description, publicationYear, authors);
      }
   }

   AuthorMarshaller.java

   import org.infinispan.protostream.MessageMarshaller;
   
   public class AuthorMarshaller implements MessageMarshaller<Author> {
   
      @Override
      public String getTypeName() {
         return "book_sample.Author";
      }
   
      @Override
      public Class<? extends Author> getJavaClass() {
         return Author.class;
      }
   
      @Override
      public void writeTo(MessageMarshaller.ProtoStreamWriter writer, Author author) throws IOException {
         writer.writeString("name", author.getName());
         writer.writeString("surname", author.getSurname());
      }
   
      @Override
      public Author readFrom(MessageMarshaller.ProtoStreamReader reader) throws IOException {
         String name = reader.readString("name");
         String surname = reader.readString("surname");
         return new Author(name, surname);
      }
   }

3. Create a SerializationContextInitializer implementation that registers the .proto schema and the ProtoStream marshaller implementations with a SerializationContext.

   ManualSerializationContextInitializer.java

   import org.infinispan.protostream.FileDescriptorSource;
   import org.infinispan.protostream.SerializationContext;
   import org.infinispan.protostream.SerializationContextInitializer;
   ...
   
   public class ManualSerializationContextInitializer implements SerializationContextInitializer {
      @Override
      public String getProtoFileName() {
         return "library.proto";
      }
   
      @Override
      public String getProtoFile() throws UncheckedIOException {
         // Assumes that the file is located in a Jar's resources, we must provide the path to the library.proto file
         return FileDescriptorSource.getResourceAsString(getClass(), "/" + getProtoFileName());
      }
   
      @Override
      public void registerSchema(SerializationContext serCtx) {
         serCtx.registerProtoFiles(FileDescriptorSource.fromString(getProtoFileName(), getProtoFile()));
      }
   
      @Override
      public void registerMarshallers(SerializationContext serCtx) {
         serCtx.registerMarshaller(new AuthorMarshaller());
         serCtx.registerMarshaller(new BookMarshaller());
      }
   }

Procedure

1. Add the infinispan-jboss-marshalling dependency to your classpath.
2. Configure Data Grid to use the GenericJBossMarshaller.

3. Add your Java classes to the deserialization whitelist.

   • Programmatically:

     GlobalConfigurationBuilder builder = new GlobalConfigurationBuilder();
     builder.serialization()
            .marshaller(new GenericJBossMarshaller())
            .whiteList()
            .addRegexps("org.infinispan.example.", "org.infinispan.concrete.SomeClass");

   • Declaratively:

     <serialization marshaller="org.infinispan.jboss.marshalling.commons.GenericJBossMarshaller">
       <white-list>
           <class>org.infinispan.concrete.SomeClass</class>
           <regex>org.infinispan.example.*</regex>
       <white-list>
     </serialization>

Procedure

1. Configure Data Grid to use JavaSerializationMarshaller as the marshaller.

2. Add your Java classes to the deserialization whitelist.

   • Programmatically:

     GlobalConfigurationBuilder builder = new GlobalConfigurationBuilder();
     builder.serialization()
            .marshaller(new JavaSerializationMarshaller())
            .whiteList()
            .addRegexps("org.infinispan.example.", "org.infinispan.concrete.SomeClass");

   • Declaratively:

     <serialization marshaller="org.infinispan.commons.marshall.JavaSerializationMarshaller">
         <white-list>
             <class>org.infinispan.concrete.SomeClass</class>
             <regex>org.infinispan.example.*</regex>
         </white-list>
     </serialization>

1. Copy infinispan-marshaller-kryo-bundle.jar from the Data Grid Maven repository.
2. Add the JAR file to the server/lib directory in your Data Grid server installation directory.

1. Add the infinispan-marshaller-kryo dependency to your pom.xml.

   <dependency>
     <groupId>org.infinispan</groupId>
     <artifactId>infinispan-marshaller-kryo</artifactId>
     <version>${version.infinispan}</version>
   </dependency>

2. Specify the org.infinispan.marshaller.kryo.KryoMarshaller class as the marshaller.

   GlobalConfigurationBuilder builder = new GlobalConfigurationBuilder();
   builder.serialization()
          .marshaller(new org.infinispan.marshaller.kryo.KryoMarshaller());

Procedure

1. Implement a service provider for the SerializerRegistryService.java interface.

2. Place all serializer registrations in the register(Kryo) method; where serializers are registered with the supplied Kryo object using the Kryo API, for example:

   kryo.register(ExampleObject.class, new ExampleObjectSerializer())

3. Specify the full path of implementing classes in your deployment JAR file within:

   META-INF/services/org/infinispan/marshaller/kryo/SerializerRegistryService

1. Copy infinispan-marshaller-protostuff-bundle.jar from the Data Grid Maven repository.
2. Add the JAR file to the server/lib directory in your Data Grid server installation directory.

1. Add the infinispan-marshaller-protostuff dependency to your pom.xml.

   <dependency>
     <groupId>org.infinispan</groupId>
     <artifactId>infinispan-marshaller-protostuff</artifactId>
     <version>${version.infinispan}</version>
   </dependency>

2. Specify the org.infinispan.marshaller.protostuff.ProtostuffMarshaller class as the marshaller.

   GlobalConfigurationBuilder builder = new GlobalConfigurationBuilder();
   builder.serialization()
          .marshaller(new org.infinispan.marshaller.protostuff.ProtostuffMarshaller());

Procedure

1. Implement the Marshaller interface.
2. Configure Data Grid to use your marshaller.

3. Add your Java classes to the deserialization whitelist.

   • Programmatically:

     GlobalConfigurationBuilder builder = new GlobalConfigurationBuilder();
     builder.serialization()
           .marshaller(new org.infinispan.example.marshall.CustomMarshaller())
           .whiteList().addRegexp("org.infinispan.example.*");

   • Declaratively:

     <serialization marshaller="org.infinispan.example.marshall.CustomMarshaller">
         <white-list>
             <class>org.infinispan.concrete.SomeClass</class>
             <regex>org.infinispan.example.*</regex>
         </white-list>
     </serialization>