001/* 002 * Logback: the reliable, generic, fast and flexible logging framework. 003 * Copyright (C) 1999-2026, QOS.ch. All rights reserved. 004 * 005 * This program and the accompanying materials are dual-licensed under 006 * either the terms of the Eclipse Public License v2.0 as published by 007 * the Eclipse Foundation 008 * 009 * or (per the licensee's choosing) 010 * 011 * under the terms of the GNU Lesser General Public License version 2.1 012 * as published by the Free Software Foundation. 013 */ 014package ch.qos.logback.core.kryo; 015 016import com.esotericsoftware.kryo.kryo5.Kryo; 017import com.esotericsoftware.kryo.kryo5.KryoException; 018import com.esotericsoftware.kryo.kryo5.Serializer; 019import com.esotericsoftware.kryo.kryo5.io.Input; 020import com.esotericsoftware.kryo.kryo5.io.Output; 021import com.esotericsoftware.kryo.kryo5.minlog.Log; 022 023import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_CRC3_POLY; 024import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_CRC_BITS; 025import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_CRC_MASK; 026import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_DATA_BITS; 027import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_DATA_MASK; 028import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_ID_MASK; 029import static ch.qos.logback.core.kryo.KryoCoreConstants.ENTRY_HEADER_NEW_FLAG; 030import static ch.qos.logback.core.kryo.KryoCoreConstants.MAX_SERIALIZER_ID; 031import static ch.qos.logback.core.kryo.KryoCoreConstants.UNREGISTERED_ID; 032 033/** 034 * Base Kryo serializer with optional value↔id caching. 035 * 036 * <p>When a bimap is configured, each value is introduced with a 2-byte header packing 037 * a 13-bit data word (NEW/CACHED flag + 12-bit id) and a 3-bit CRC over those data bits. 038 * Ids must be in {@code 1..MAX_SERIALIZER_ID}, or {@link KryoCoreConstants#UNREGISTERED_ID} 039 * for frequency-gated non-registrations. Cached hits write only that header; new values also 040 * write the payload via {@link #writeNewEntry}. 041 * 042 * @see KryoCoreConstants#ENTRY_HEADER_NEW_FLAG 043 */ 044public abstract class SerializerBase<V> extends Serializer<V> { 045 046 public enum BiMapType { 047 NONE, 048 DIRECT_MAP, 049 FREQUENCY_GATED, 050 /** Cache hits use {@code ==}, not {@code equals}/{@code hashCode}. */ 051 IDENTITY 052 } 053 054 055 final int capacity; 056 final BidirectionalObjectToIdMap<V> bimap; 057 058 public SerializerBase(int capacity) { 059 060 this(BiMapType.DIRECT_MAP, capacity); 061 if(capacity < 1024) { 062 System.out.println("WARNING: capacity less than 1024"); 063 } 064 } 065 066 public SerializerBase(BiMapType biMapType, int capacity) { 067 this.capacity = capacity; 068 069 switch (biMapType) { 070 case NONE: 071 this.bimap = null; 072 break; 073 case DIRECT_MAP: 074 this.bimap = new BidirectionalObjectToIdMapDefault<>(capacity); 075 break; 076 case FREQUENCY_GATED: 077 this.bimap = new BidirectionalObjectToIdMapDefault(capacity); //FrequencyGatedBidirectionalObjectToIdMap<>(capacity); 078 break; 079 case IDENTITY: 080 this.bimap = new BidirectionalObjectToIdMapIdentity<>(capacity); 081 break; 082 default: 083 throw new IllegalArgumentException("Unsupported BiMapType: " + biMapType); 084 } 085 Log.debug(this.getClass().getSimpleName() + " bimap:"+biMapType+" capacity: " + capacity); 086 } 087 088 089 @Override 090 public void write(Kryo kryo, Output output, V value) { 091 092 // no bimap, just write the value directly 093 if (bimap == null) { 094 writeNewEntry(kryo, output, value); 095 return; 096 } 097 098 Integer existingId = this.bimap.getIdByValue(value); 099 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}