View Javadoc
1   /*
2    * Logback: the reliable, generic, fast and flexible logging framework.
3    * Copyright (C) 1999-2026, QOS.ch. All rights reserved.
4    *
5    * This program and the accompanying materials are dual-licensed under
6    * either the terms of the Eclipse Public License v2.0 as published by
7    * the Eclipse Foundation
8    *
9    *   or (per the licensee's choosing)
10   *
11   * under the terms of the GNU Lesser General Public License version 2.1
12   * as published by the Free Software Foundation.
13   */
14  package ch.qos.logback.core.kryo;
15  
16  import com.esotericsoftware.kryo.kryo5.Kryo;
17  import com.esotericsoftware.kryo.kryo5.KryoException;
18  import com.esotericsoftware.kryo.kryo5.Serializer;
19  import com.esotericsoftware.kryo.kryo5.io.Input;
20  import com.esotericsoftware.kryo.kryo5.io.Output;
21  import com.esotericsoftware.kryo.kryo5.minlog.Log;
22  
23  import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_CRC3_POLY;
24  import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_CRC_BITS;
25  import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_CRC_MASK;
26  import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_DATA_BITS;
27  import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_DATA_MASK;
28  import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_ID_MASK;
29  import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_NEW_FLAG;
30  import static ch.qos.logback.core.kryo.KryoCoreConstants.MAX_SERIALIZER_ID;
31  import static ch.qos.logback.core.kryo.KryoCoreConstants.UNREGISTERED_ID;
32  
33  /**
34   * Base Kryo serializer with optional value↔id caching.
35   *
36   * <p>When a bimap is configured, each value is introduced with a 2-byte header packing
37   * a 13-bit data word (NEW/CACHED flag + 12-bit id) and a 3-bit CRC over those data bits.
38   * Ids must be in {@code 1..MAX_SERIALIZER_ID}, or {@link KryoCoreConstants#UNREGISTERED_ID}
39   * for frequency-gated non-registrations. Cached hits write only that header; new values also
40   * write the payload via {@link #writeNewEntry}.
41   *
42   * @see KryoCoreConstants#ENTRY_HEADER_NEW_FLAG
43   */
44  public abstract class SerializerBase<V> extends Serializer<V> {
45  
46      public enum BiMapType {
47          NONE,
48          DIRECT_MAP,
49          FREQUENCY_GATED,
50          /** Cache hits use {@code ==}, not {@code equals}/{@code hashCode}. */
51          IDENTITY
52      }
53  
54  
55      final int capacity;
56      final BidirectionalObjectToIdMap<V> bimap;
57  
58      public SerializerBase(int capacity) {
59  
60          this(BiMapType.DIRECT_MAP, capacity);
61          if(capacity < 1024) {
62              System.out.println("WARNING: capacity less than 1024");
63          }
64      }
65  
66      public SerializerBase(BiMapType biMapType, int capacity) {
67          this.capacity = capacity;
68  
69          switch (biMapType) {
70              case NONE:
71                  this.bimap = null;
72                  break;
73              case DIRECT_MAP:
74                  this.bimap = new BidirectionalObjectToIdMapDefault<>(capacity);
75                  break;
76              case FREQUENCY_GATED:
77                  this.bimap = new BidirectionalObjectToIdMapDefault(capacity); //FrequencyGatedBidirectionalObjectToIdMap<>(capacity);
78                  break;
79              case IDENTITY:
80                  this.bimap = new BidirectionalObjectToIdMapIdentity<>(capacity);
81                  break;
82              default:
83                  throw new IllegalArgumentException("Unsupported BiMapType: " + biMapType);
84          }
85          Log.debug(this.getClass().getSimpleName() + " bimap:"+biMapType+" capacity: " + capacity);
86      }
87  
88  
89      @Override
90      public void write(Kryo kryo, Output output, V value) {
91  
92          // no bimap, just write the value directly
93          if (bimap == null) {
94              writeNewEntry(kryo, output, value);
95              return;
96          }
97  
98          Integer existingId = this.bimap.getIdByValue(value);
99  
100         if (existingId == null) {
101             final int newId = this.bimap.insertNewEntryOnWrite(value);
102             writeEntryHeader(output, true, newId);
103             //Log.debug("SerializerBase.write writing new value [" + value + "] with id: " + newId);
104             writeNewEntry(kryo, output, value);
105         } else {
106             //Log.debug("SerializerBase.write writing existing entry [" + value + "] with id: " + existingId);
107             writeEntryHeader(output, false, existingId);
108         }
109 
110     }
111 
112     /**
113      * Method called to write new entries.
114      *
115      * @param kryo
116      * @param output
117      * @param value
118      */
119     abstract protected void writeNewEntry(Kryo kryo, Output output, V value);
120 
121     @Override
122     public V read(Kryo kryo, Input input, Class<? extends V> type) {
123 
124         if (bimap == null) {
125             return readNewEntry(kryo, input);
126         }
127 
128         int data13 = readEntryHeaderData(input);
129         boolean isNewEntry = (data13 & ENTRY_HEADER_NEW_FLAG) != 0;
130         int id = decodeHeaderId(data13);
131 
132         if (isNewEntry) {
133             V deserialized = readNewEntry(kryo, input);
134             if (id != UNREGISTERED_ID) {
135                 V existingVal = bimap.insertNewEntryOnRead(id, deserialized);
136                 if (existingVal != null) {
137                     Log.warn("SerializerBase.read returned non-null existingVal for value id: " + id);
138                 }
139             }
140             Log.debug("NEW entry for id: " + id + ", value: " + deserialized);
141             return deserialized;
142         } else {
143             V value = bimap.getValueById(id);
144             Log.debug("Cached entry for id: " + id + ", value: " + value);
145             return value;
146         }
147     }
148 
149     abstract protected V readNewEntry(Kryo kryo, Input input);
150 
151     /**
152      * Writes a 2-byte entry header: 13-bit data (NEW flag + id) and a 3-bit CRC over that data.
153      * {@link KryoCoreConstants#UNREGISTERED_ID} is stored as id 0 (valid only with NEW).
154      */
155     static void writeEntryHeader(Output output, boolean newEntry, int id) {
156         int idBits;
157         if (id == UNREGISTERED_ID) {
158             if (!newEntry) {
159                 throw new IllegalArgumentException("UNREGISTERED_ID is only valid for NEW_ENTRY");
160             }
161             idBits = 0;
162         } else {
163             if (id < 1 || id > MAX_SERIALIZER_ID) {
164                 throw new IllegalStateException(
165                         "Serializer id out of range: " + id + " (allowed 1.." + MAX_SERIALIZER_ID + ")");
166             }
167             idBits = id;
168         }
169         int data13 = (newEntry ? ENTRY_HEADER_NEW_FLAG : 0) | (idBits & ENTRY_HEADER_ID_MASK);
170         int crc = crc3(data13);
171         int packed = (data13 << ENTRY_HEADER_CRC_BITS) | crc;
172         output.writeShort(packed);
173     }
174 
175     /**
176      * Reads a 2-byte entry header, verifies the CRC, and returns the 13-bit data word.
177      *
178      * @throws KryoException if the CRC does not match
179      */
180     static int readEntryHeaderData(Input input) {
181         int packed = input.readShort() & 0xFFFF;
182         int data13 = (packed >>> ENTRY_HEADER_CRC_BITS) & ENTRY_HEADER_DATA_MASK;
183         int crc = packed & ENTRY_HEADER_CRC_MASK;
184         int expected = crc3(data13);
185         if (crc != expected) {
186             throw new KryoException(
187                     "SerializerBase entry header CRC mismatch: got " + crc + ", expected " + expected
188                             + " (data=0x" + Integer.toHexString(data13) + ")");
189         }
190         return data13;
191     }
192 
193     /**
194      * Decodes the id from a verified 13-bit data word.
195      * Id bits {@code 0} on a NEW entry mean {@link KryoCoreConstants#UNREGISTERED_ID}.
196      */
197     static int decodeHeaderId(int data13) {
198         int idBits = data13 & ENTRY_HEADER_ID_MASK;
199         boolean isNew = (data13 & ENTRY_HEADER_NEW_FLAG) != 0;
200         if (isNew && idBits == 0) {
201             return UNREGISTERED_ID;
202         }
203         return idBits;
204     }
205 
206     /**
207      * CRC-3 over the low {@link KryoCoreConstants#ENTRY_HEADER_DATA_BITS} of {@code data},
208      * polynomial {@link KryoCoreConstants#ENTRY_HEADER_CRC3_POLY} ({@code x^3 + x + 1}).
209      *
210      * <p>MSB-first residual: remainder of {@code (data << 3)} modulo the generator.
211      */
212     static int crc3(int data) {
213         int v = (data & ENTRY_HEADER_DATA_MASK) << ENTRY_HEADER_CRC_BITS;
214         for (int i = ENTRY_HEADER_DATA_BITS + ENTRY_HEADER_CRC_BITS - 1; i >= ENTRY_HEADER_CRC_BITS; i--) {
215             if (((v >> i) & 1) != 0) {
216                 v ^= ENTRY_HEADER_CRC3_POLY << (i - ENTRY_HEADER_CRC_BITS);
217             }
218         }
219         return v & ENTRY_HEADER_CRC_MASK;
220     }
221 }