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 io.netty.buffer.ByteBuf;
  23 import io.netty.buffer.ByteBufUtil;
  24 import io.netty.buffer.Unpooled;
  25 import java.io.IOException;
  26 import java.io.InputStream;
  27 import java.io.OutputStream;
  28 import java.nio.ByteBuffer;
  29
  30 /**
  31  * Support for serialization of {@link Journal} entries.
  32  *
  33  * @deprecated due to dependency on outdated Kryo library, {@link ByteBufMapper} to be used instead.
  34  */
  35 @Deprecated(forRemoval = true, since="9.0.3")
  36 public interface JournalSerdes {
  37     /**
  38      * Serializes given object to byte array.
  39      *
  40      * @param obj Object to serialize
  41      * @return serialized bytes
  42      */
  43     byte[] serialize(Object obj);
  44
  45     /**
  46      * Serializes given object to byte array.
  47      *
  48      * @param obj        Object to serialize
  49      * @param bufferSize maximum size of serialized bytes
  50      * @return serialized bytes
  51      */
  52     byte[] serialize(Object obj, int bufferSize);
  53
  54     /**
  55      * Serializes given object to byte buffer.
  56      *
  57      * @param obj    Object to serialize
  58      * @param buffer to write to
  59      */
  60     void serialize(Object obj, ByteBuffer buffer);
  61
  62     /**
  63      * Serializes given object to OutputStream.
  64      *
  65      * @param obj    Object to serialize
  66      * @param stream to write to
  67      */
  68     void serialize(Object obj, OutputStream stream);
  69
  70     /**
  71      * Serializes given object to OutputStream.
  72      *
  73      * @param obj        Object to serialize
  74      * @param stream     to write to
  75      * @param bufferSize size of the buffer in front of the stream
  76      */
  77     void serialize(Object obj, OutputStream stream, int bufferSize);
  78
  79     /**
  80      * Deserializes given byte array to Object.
  81      *
  82      * @param bytes serialized bytes
  83      * @param <T>   deserialized Object type
  84      * @return deserialized Object
  85      */
  86     <T> T deserialize(byte[] bytes);
  87
  88     /**
  89      * Deserializes given byte buffer to Object.
  90      *
  91      * @param buffer input with serialized bytes
  92      * @param <T>    deserialized Object type
  93      * @return deserialized Object
  94      */
  95     <T> T deserialize(final ByteBuffer buffer);
  96
  97     /**
  98      * Deserializes given InputStream to an Object.
  99      *
 100      * @param stream input stream
 101      * @param <T>    deserialized Object type
 102      * @return deserialized Object
 103      */
 104     <T> T deserialize(InputStream stream);
 105
 106     /**
 107      * Deserializes given InputStream to an Object.
 108      *
 109      * @param stream     input stream
 110      * @param <T>        deserialized Object type
 111      * @param bufferSize size of the buffer in front of the stream
 112      * @return deserialized Object
 113      */
 114     <T> T deserialize(final InputStream stream, final int bufferSize);
 115
 116     /**
 117      * Returns a {@link ByteBufMapper} backed by this object.
 118      *
 119      * @return a {@link ByteBufMapper} backed by this object
 120      */
 121     default <T> ByteBufMapper<T> toMapper() {
 122         return new ByteBufMapper<>() {
 123             @Override
 124             public ByteBuf objectToBytes(final T obj) {
 125                 return Unpooled.wrappedBuffer(serialize(obj));
 126             }
 127
 128             @Override
 129             public T bytesToObject(final ByteBuf buf) {
 130                 // FIXME: ByteBufUtil creates a copy -- we do not want to do that!
 131                 return deserialize(ByteBufUtil.getBytes(buf));
 132             }
 133         };
 134     }
 135
 136     /**
 137      * Creates a new {@link JournalSerdes} builder.
 138      *
 139      * @return builder
 140      */
 141     static Builder builder() {
 142         return new KryoJournalSerdesBuilder();
 143     }
 144
 145     /**
 146      * Builder for {@link JournalSerdes}.
 147      */
 148     interface Builder {
 149         /**
 150          * Builds a {@link JournalSerdes} instance.
 151          *
 152          * @return A {@link JournalSerdes} implementation.
 153          */
 154         JournalSerdes build();
 155
 156         /**
 157          * Builds a {@link JournalSerdes} instance.
 158          *
 159          * @param friendlyName friendly name for the namespace
 160          * @return A {@link JournalSerdes} implementation.
 161          */
 162         JournalSerdes build(String friendlyName);
 163
 164         /**
 165          * Registers serializer for the given set of classes.
 166          * <p>
 167          * When multiple classes are registered with an explicitly provided serializer, the namespace guarantees
 168          * all instances will be serialized with the same type ID.
 169          *
 170          * @param classes list of classes to register
 171          * @param serdes  serializer to use for the class
 172          * @return this builder
 173          */
 174         Builder register(EntrySerdes<?> serdes, Class<?>... classes);
 175
 176         /**
 177          * Sets the namespace class loader.
 178          *
 179          * @param classLoader the namespace class loader
 180          * @return this builder
 181          */
 182         Builder setClassLoader(ClassLoader classLoader);
 183     }
 184
 185     /**
 186      * Input data stream exposed to {@link EntrySerdes#read(EntryInput)}.
 187      */
 188     @Beta
 189     interface EntryInput {
 190
 191         byte[] readBytes(int length) throws IOException;
 192
 193         long readLong() throws IOException;
 194
 195         String readString() throws IOException;
 196
 197         Object readObject() throws IOException;
 198
 199         @VisibleForTesting
 200         int readVarInt() throws IOException;
 201     }
 202
 203     /**
 204      * Output data stream exposed to {@link EntrySerdes#write(EntryOutput, Object)}.
 205      */
 206     @Beta
 207     interface EntryOutput {
 208
 209         void writeBytes(byte[] bytes) throws IOException;
 210
 211         void writeLong(long value) throws IOException;
 212
 213         void writeObject(Object value) throws IOException;
 214
 215         void writeString(String value) throws IOException;
 216
 217         @VisibleForTesting
 218         void writeVarInt(int value) throws IOException;
 219     }
 220
 221     /**
 222      * A serializer/deserializer for an entry.
 223      *
 224      * @param <T> Entry type
 225      */
 226     interface EntrySerdes<T> {
 227
 228         T read(EntryInput input) throws IOException;
 229
 230         void write(EntryOutput output, T entry) throws IOException;
 231     }
 232 }