third-party/atomix/storage/src/main/java/io/atomix/storage/journal/JournalSerdes.java

   1 /*
   2  * Copyright 2014-2021 Open Networking Foundation
   3  * Copyright 2023 PANTHEON.tech, s.r.o.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  * http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17 package io.atomix.storage.journal;
  18
  19 import com.google.common.annotations.Beta;
  20 import com.google.common.annotations.VisibleForTesting;
  21 import io.atomix.utils.serializer.KryoJournalSerdesBuilder;
  22 import java.io.IOException;
  23 import java.io.InputStream;
  24 import java.io.OutputStream;
  25 import java.nio.ByteBuffer;
  26
  27 /**
  28  * Support for serialization of {@link Journal} entries.
  29  */
  30 public interface JournalSerdes {
  31     /**
  32      * Serializes given object to byte array.
  33      *
  34      * @param obj Object to serialize
  35      * @return serialized bytes
  36      */
  37     byte[] serialize(Object obj);
  38
  39     /**
  40      * Serializes given object to byte array.
  41      *
  42      * @param obj        Object to serialize
  43      * @param bufferSize maximum size of serialized bytes
  44      * @return serialized bytes
  45      */
  46     byte[] serialize(Object obj, int bufferSize);
  47
  48     /**
  49      * Serializes given object to byte buffer.
  50      *
  51      * @param obj    Object to serialize
  52      * @param buffer to write to
  53      */
  54     void serialize(Object obj, ByteBuffer buffer);
  55
  56     /**
  57      * Serializes given object to OutputStream.
  58      *
  59      * @param obj    Object to serialize
  60      * @param stream to write to
  61      */
  62     void serialize(Object obj, OutputStream stream);
  63
  64     /**
  65      * Serializes given object to OutputStream.
  66      *
  67      * @param obj        Object to serialize
  68      * @param stream     to write to
  69      * @param bufferSize size of the buffer in front of the stream
  70      */
  71     void serialize(Object obj, OutputStream stream, int bufferSize);
  72
  73     /**
  74      * Deserializes given byte array to Object.
  75      *
  76      * @param bytes serialized bytes
  77      * @param <T>   deserialized Object type
  78      * @return deserialized Object
  79      */
  80     <T> T deserialize(byte[] bytes);
  81
  82     /**
  83      * Deserializes given byte buffer to Object.
  84      *
  85      * @param buffer input with serialized bytes
  86      * @param <T>    deserialized Object type
  87      * @return deserialized Object
  88      */
  89     <T> T deserialize(final ByteBuffer buffer);
  90
  91     /**
  92      * Deserializes given InputStream to an Object.
  93      *
  94      * @param stream input stream
  95      * @param <T>    deserialized Object type
  96      * @return deserialized Object
  97      */
  98     <T> T deserialize(InputStream stream);
  99
 100     /**
 101      * Deserializes given InputStream to an Object.
 102      *
 103      * @param stream     input stream
 104      * @param <T>        deserialized Object type
 105      * @param bufferSize size of the buffer in front of the stream
 106      * @return deserialized Object
 107      */
 108     <T> T deserialize(final InputStream stream, final int bufferSize);
 109
 110     /**
 111      * Creates a new {@link JournalSerdes} builder.
 112      *
 113      * @return builder
 114      */
 115     static Builder builder() {
 116         return new KryoJournalSerdesBuilder();
 117     }
 118
 119     /**
 120      * Builder for {@link JournalSerdes}.
 121      */
 122     interface Builder {
 123         /**
 124          * Builds a {@link JournalSerdes} instance.
 125          *
 126          * @return A {@link JournalSerdes} implementation.
 127          */
 128         JournalSerdes build();
 129
 130         /**
 131          * Builds a {@link JournalSerdes} instance.
 132          *
 133          * @param friendlyName friendly name for the namespace
 134          * @return A {@link JournalSerdes} implementation.
 135          */
 136         JournalSerdes build(String friendlyName);
 137
 138         /**
 139          * Registers serializer for the given set of classes.
 140          * <p>
 141          * When multiple classes are registered with an explicitly provided serializer, the namespace guarantees
 142          * all instances will be serialized with the same type ID.
 143          *
 144          * @param classes list of classes to register
 145          * @param serdes  serializer to use for the class
 146          * @return this builder
 147          */
 148         Builder register(EntrySerdes<?> serdes, Class<?>... classes);
 149
 150         /**
 151          * Sets the namespace class loader.
 152          *
 153          * @param classLoader the namespace class loader
 154          * @return this builder
 155          */
 156         Builder setClassLoader(ClassLoader classLoader);
 157     }
 158
 159     /**
 160      * Input data stream exposed to {@link EntrySerdes#read(EntryInput)}.
 161      */
 162     @Beta
 163     interface EntryInput {
 164
 165         byte[] readBytes(int length) throws IOException;
 166
 167         long readLong() throws IOException;
 168
 169         String readString() throws IOException;
 170
 171         Object readObject() throws IOException;
 172
 173         @VisibleForTesting
 174         int readVarInt() throws IOException;
 175     }
 176
 177     /**
 178      * Output data stream exposed to {@link EntrySerdes#write(EntryOutput, Object)}.
 179      */
 180     @Beta
 181     interface EntryOutput {
 182
 183         void writeBytes(byte[] bytes) throws IOException;
 184
 185         void writeLong(long value) throws IOException;
 186
 187         void writeObject(Object value) throws IOException;
 188
 189         void writeString(String value) throws IOException;
 190
 191         @VisibleForTesting
 192         void writeVarInt(int value) throws IOException;
 193     }
 194
 195     /**
 196      * A serializer/deserializer for an entry.
 197      *
 198      * @param <T> Entry type
 199      */
 200     interface EntrySerdes<T> {
 201
 202         T read(EntryInput input) throws IOException;
 203
 204         void write(EntryOutput output, T entry) throws IOException;
 205     }
 206 }