Giga map bitmap level2 legacy type mapping

docs/modules/storage/pages/addendum/tools.adoc

@@ -64,6 +64,7 @@ This is useful for:
 
 * Changing the number of storage channels
 * Moving storage from local disk to a cloud storage target or vice-versa
+* Converting 
 
 === Prerequisites
 
@@ -132,3 +133,21 @@ To move from local file system to a cloud storage target, configure the target `
 ====
 
 For more information see the https://github.com/eclipse-store/store/tree/main/storage/embedded-tools/storage-converter[readme file].
+
+
+=== Converting binary data
+
+To convert the binary representation of persisted objects BinaryConverter implementations can be specified by the implementations full class name.
+
+.To use the supplied the BinaryConverterBitmapLevel2 converter:
+[source, bash]
+----
+java -jar storage-embedded-tools-storage-converter-{maven-version}.jar src.ini dst.ini -c org.eclipse.store.storage.embedded.tools.storage.converter.BinaryConverterBitmapLevel2
+----
+
+If more than one BinaryConverter shall be applied the -c option, including the converters must be applied in quotation marks:
+[source, bash]
+----
+... "-c binaryConverter1, binaryConverter2"
+----
+

gigamap/gigamap/src/main/java/org/eclipse/store/gigamap/types/BinaryHandlerBitmapLevel2.java

@@ -17,6 +17,8 @@
 import org.eclipse.serializer.memory.XMemory;
 import org.eclipse.serializer.persistence.binary.types.AbstractBinaryHandlerCustom;
 import org.eclipse.serializer.persistence.binary.types.Binary;
+import org.eclipse.serializer.persistence.binary.types.BinaryLegacyTypeHandlerSupplier;
+import org.eclipse.serializer.persistence.types.PersistenceLegacyTypeHandler;
 import org.eclipse.serializer.persistence.types.PersistenceLoadHandler;
 import org.eclipse.serializer.persistence.types.PersistenceReferenceLoader;
 import org.eclipse.serializer.persistence.types.PersistenceStoreHandler;
@@ -29,8 +31,12 @@
  * It extends {@link AbstractBinaryHandlerCustom} to support binary-based I/O operations
  * specific to {@link BitmapLevel2}.
  */
-public class BinaryHandlerBitmapLevel2 extends AbstractBinaryHandlerCustom<BitmapLevel2>
-{
+public class BinaryHandlerBitmapLevel2 extends AbstractBinaryHandlerCustom<BitmapLevel2> implements BinaryLegacyTypeHandlerSupplier<BitmapLevel2> 
+{	
+	private static final int  BITMAP_LEVEL2_VERSION_SIZE = Integer.BYTES;
+	private static final long BITMAP_LIST_OFFSET = BITMAP_LEVEL2_VERSION_SIZE;
+	private static final int  BITMAP_LEVEL2_BINARY_VERSION = 2;
+
 	public static BinaryHandlerBitmapLevel2 New()
 	{
 		return new BinaryHandlerBitmapLevel2();
@@ -46,6 +52,7 @@ public static BinaryHandlerBitmapLevel2 New()
 		super(
 			BitmapLevel2.class,
 			CustomFields(
+				CustomField(int.class, "version"),
 				bytes("data")
 			)
 		);
@@ -59,12 +66,12 @@ public static BinaryHandlerBitmapLevel2 New()
 	@Override
 	public BitmapLevel2 create(final Binary data, final PersistenceLoadHandler handler)
 	{
-		final long contentLength = Binary.toBinaryListContentByteLength(data.getLoadItemAvailableContentLength());
+		final long contentLength = Binary.toBinaryListContentByteLength(data.getBinaryListTotalByteLength(BITMAP_LEVEL2_VERSION_SIZE));
 		final int  fullLength    = BitmapLevel2.getTotalLengthFromPersistentLength(XTypes.to_int(contentLength));
 
 		final long level2Address     = XMemory.allocate(fullLength);
 		final long persistentAddress = BitmapLevel2.toPersistentDataAddress(level2Address);
-		data.copyToAddress(0, persistentAddress, contentLength);
+		data.copyToAddress(Binary.toBinaryListElementsOffset(BITMAP_LIST_OFFSET), persistentAddress, contentLength);
 		BitmapLevel2.initializeFromData(level2Address, fullLength);
 
 		// required to prevent JVM crashes caused by misinterpreted off-heap data.
@@ -82,17 +89,18 @@ public void store(
 	)
 	{
 		// if the parent level3 segment decided to store a level2 segment, it must be stored in any case.
-			
+
 		instance.ensureCompressed();
 		final long persistentAddress = BitmapLevel2.toPersistentDataAddress(instance.level2Address);
 		final int  persistentLength  = BitmapLevel2.getPersistentLengthFromTotalLength(instance.totalLength());
 		data.storeEntityHeader(
-			Binary.toBinaryListTotalByteLength(persistentLength), 
-			this.typeId(), 
+				Binary.toBinaryListTotalByteLength(persistentLength) + BITMAP_LEVEL2_VERSION_SIZE,
+			this.typeId(),
 			objectId
 		);
-
-		data.copyFromAddress(0, persistentAddress, persistentLength);
+		data.store_int(BITMAP_LEVEL2_BINARY_VERSION);
+		data.storeListHeader(BITMAP_LIST_OFFSET, persistentLength, persistentLength);
+		data.copyFromAddress(Binary.toBinaryListElementsOffset(BITMAP_LIST_OFFSET), persistentAddress, persistentLength);
 	}
 
 	@Override
@@ -110,5 +118,11 @@ public void iterateLoadableReferences(final Binary data, final PersistenceRefere
 	{
 		// no-op
 	}
+
+	@Override
+	public PersistenceLegacyTypeHandler<Binary, BitmapLevel2> getLegacyTypeHandler()
+	{
+		return BinaryLegacyTypeHandlerBitmapLevel2.New();
+	}
 
 }

gigamap/gigamap/src/main/java/org/eclipse/store/gigamap/types/BinaryLegacyTypeHandlerBitmapLevel2.java

@@ -0,0 +1,92 @@
+package org.eclipse.store.gigamap.types;
+
+/*-
+ * #%L
+ * EclipseStore GigaMap
+ * %%
+ * Copyright (C) 2023 - 2025 MicroStream Software
+ * %%
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ * 
+ * SPDX-License-Identifier: EPL-2.0
+ * #L%
+ */
+
+import org.eclipse.serializer.memory.XMemory;
+import org.eclipse.serializer.persistence.binary.types.AbstractBinaryHandlerCustom;
+import org.eclipse.serializer.persistence.binary.types.Binary;
+import org.eclipse.serializer.persistence.binary.types.BinaryLegacyTypeHandler;
+import org.eclipse.serializer.persistence.types.PersistenceLoadHandler;
+import org.eclipse.serializer.persistence.types.PersistenceReferenceLoader;
+import org.eclipse.serializer.typing.XTypes;
+
+
+/**
+ * BinaryHandlerBitmapLevel2 is responsible for managing serialization, deserialization,
+ * and state updates for objects of type {@link BitmapLevel2} within a persistence framework.
+ * It extends {@link AbstractBinaryHandlerCustom} to support binary-based I/O operations
+ * specific to {@link BitmapLevel2}.
+ */
+public class BinaryLegacyTypeHandlerBitmapLevel2 extends BinaryLegacyTypeHandler.AbstractCustom<BitmapLevel2>
+{
+	public static BinaryLegacyTypeHandlerBitmapLevel2 New()
+	{
+		return new BinaryLegacyTypeHandlerBitmapLevel2();
+	}
+
+
+	///////////////////////////////////////////////////////////////////////////
+	// constructors //
+	/////////////////
+
+	BinaryLegacyTypeHandlerBitmapLevel2()
+	{
+		super(
+			BitmapLevel2.class,
+			CustomFields(
+				bytes("data")
+			)
+		);
+	}
+
+
+	///////////////////////////////////////////////////////////////////////////
+	// methods //
+	////////////
+
+	@Override
+	public BitmapLevel2 create(final Binary data, final PersistenceLoadHandler handler)
+	{
+		final long contentLength = Binary.toBinaryListContentByteLength(data.getLoadItemAvailableContentLength());
+		final int  fullLength    = BitmapLevel2.getTotalLengthFromPersistentLength(XTypes.to_int(contentLength));
+
+		final long level2Address     = XMemory.allocate(fullLength);
+		final long persistentAddress = BitmapLevel2.toPersistentDataAddress(level2Address);
+		data.copyToAddress(0, persistentAddress, contentLength);
+		BitmapLevel2.initializeFromData(level2Address, fullLength);
+
+		// required to prevent JVM crashes caused by misinterpreted off-heap data.
+		BitmapLevel2.validateLevel2SegmentType(level2Address);
+
+		return new BitmapLevel2(false, level2Address);
+	}
+
+	@Override
+	public void updateState(
+		final Binary                 data    ,
+		final BitmapLevel2           instance,
+		final PersistenceLoadHandler handler
+	)
+	{
+		// there are no references to be set, hence nothing to do here
+	}
+
+	@Override
+	public void iterateLoadableReferences(final Binary data, final PersistenceReferenceLoader iterator)
+	{
+		// no-op
+	}
+
+}

storage/embedded-tools/storage-converter/README.md

@@ -8,7 +8,7 @@ It is possible to define a different channel count for the target than the sourc
 
 ## Building the storage converter standalone jar
 
-To build the converter standalone jar using Maven you need to active the profile **converter-standalone**.
+To build the converter standalone jar using Maven you need to activate the profile **converter-standalone**.
 
 ```console
 mvn -Pconverter-standalone clean package
@@ -22,7 +22,7 @@ mvn -Pconverter-standalone clean package
 To configure the input and output storage an [external configuration](https://docs.eclipsestore.io/manual/storage/configuration/index.html#external-configuration) file for each storage is required.
 
 ```console
-java -jar storage-embedded-tools-storage-converter-4.0.0-beta1.jar sourceCongig.xml targetConfig.xml
+java -jar storage-embedded-tools-storage-converter-4.0.0-SNAPSHOT.jar sourceConfig.ini targetConfig.ini
 ```
 
 ### StorageConverter.java
@@ -35,4 +35,18 @@ org.eclipse.store.storage.embedded.tools.storage.converter.StorageConverter.Stor
 
 which gives you some more control on the storage's configurations.
 
+### Converting binary data
 
+To convert the binary representation of persisted objects BinaryConverter implementations can be specified by the implementations full class name.
+
+using the BinaryConverterBitmapLevel2 converter:
+
+```console
+java -jar storage-embedded-tools-storage-converter-4.0.0-SNAPSHOT.jar src.ini dst.ini -c org.eclipse.store.storage.embedded.tools.storage.converter.BinaryConverterBitmapLevel2
+```
+
+If more than one BinaryConverter shall be applied the -c option, including the converters must be applied in quotation marks:
+
+```console
+... "-c binaryConverter1, binaryConverter2"
+```

storage/embedded-tools/storage-converter/src/main/java/module-info.java

@@ -16,4 +16,5 @@
 	exports org.eclipse.store.storage.embedded.tools.storage.converter;
 
 	requires transitive org.eclipse.store.storage.embedded.configuration;
+	requires org.eclipse.serializer.base;
 }

storage/embedded-tools/storage-converter/src/main/java/org/eclipse/store/storage/embedded/tools/storage/converter/BinaryConverter.java

@@ -0,0 +1,60 @@
+package org.eclipse.store.storage.embedded.tools.storage.converter;
+
+/*-
+ * #%L
+ * EclipseStore Storage Embedded Tools Storage Converter
+ * %%
+ * Copyright (C) 2023 - 2026 MicroStream Software
+ * %%
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ * 
+ * SPDX-License-Identifier: EPL-2.0
+ * #L%
+ */
+
+import java.nio.ByteBuffer;
+
+import org.eclipse.serializer.persistence.types.PersistenceTypeDefinition;
+import org.eclipse.serializer.persistence.types.PersistenceTypeDescription;
+
+/**
+ * The Binary Converter converters the input binary data to a new binary format.
+ */
+public interface BinaryConverter
+{
+	/**
+	 * Convert the input binary data.
+	 * 
+	 * @param bufferIn binary input data.
+	 * @return ByteBuffer containing the converted binary data.
+	 */
+	ByteBuffer convert(ByteBuffer bufferIn);
+
+	/**
+	 * Returns a new typeDefinition if the converted
+	 * binary data requires an update of the type definition.
+	 * The new TypeDefinition will be added to the output
+	 * storage type-dictionary.
+	 * 
+	 * @return a PersistenceTypeDefinition
+	 */
+	public PersistenceTypeDefinition getTypeDefinition();
+
+	/**
+	 * Returns true if the handler requires the type dictionary to be updated.
+	 * 
+	 * @return true if the converter updates type dictionary.
+	 */
+	boolean requiresTypeDictionaryUpdate();
+
+	/**
+	 * Returns true if the converter can process
+	 * the provided type.
+	 * 
+	 * @param e PersistenceTypeDescription to check if the type can be processed by the converter.
+	 * @return true if converter is can process the types' data.
+	 */
+	boolean matches(PersistenceTypeDescription e);
+}