Tools

Storage Migrator

The Storage Migrator is a utility for migrating MicroStream projects to EclipseStore. It is based on OpenRewrite and can migrate source code (package names from one.microstream to org.eclipse.store / org.eclipse.serializer) and type dictionary files of existing storages.

The migrator is executed via Maven on the command line in your MicroStream project folder. The parameters eclipseStoreVersion and typeDictionaryRelativePath control what is migrated:

  • Source code migration is only done when eclipseStoreVersion is set.

  • Type dictionary migration is only done when typeDictionaryRelativePath is set.

Migrate Source Code and Type Dictionary

mvn org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.activeRecipes=org.eclipse.store.storage.embedded.tools.storage.migrator.ConvertProject \
  -Drewrite.recipeArtifactCoordinates=org.eclipse.store:storage-embedded-tools-storage-migrator:4.0.1 \
  -DeclipseStoreVersion=4.0.1 \
  -Drewrite.plainTextMasks=**/*.ptd \
  -DtypeDictionaryRelativeFilePath=src/main/resources/PersistenceTypeDictionary.ptd

Migrate Source Code Only

mvn org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.activeRecipes=org.eclipse.store.storage.embedded.tools.storage.migrator.ConvertProject \
  -Drewrite.recipeArtifactCoordinates=org.eclipse.store:storage-embedded-tools-storage-migrator:4.0.1 \
  -DeclipseStoreVersion=4.0.1

Migrate Type Dictionary Only

Copy the type dictionary file (PersistenceTypeDictionary.ptd from the root of your storage folder) into your project, then run:

mvn org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.activeRecipes=org.eclipse.store.storage.embedded.tools.storage.migrator.ConvertProject \
  -Drewrite.recipeArtifactCoordinates=org.eclipse.store:storage-embedded-tools-storage-migrator:4.0.1 \
  -Drewrite.plainTextMasks=**/*.ptd \
  -DtypeDictionaryRelativeFilePath=src/main/resources/PersistenceTypeDictionary.ptd

After migration, the storage can be opened with EclipseStore.

Standalone JAR

The standalone JAR is not built by default. To build it locally, activate the migrator-standalone Maven profile in the EclipseStore repository:

mvn -Pmigrator-standalone clean package -pl storage/embedded-tools/storage-migrator -am

This produces a fat JAR with all dependencies included:

storage/embedded-tools/storage-migrator/target/storage-embedded-tools-storage-migrator-<version>-jar-with-dependencies.jar

You can then use this JAR as the recipe artifact coordinate in the migration commands above, or publish it to your local Maven repository:

mvn -Pmigrator-standalone install -pl storage/embedded-tools/storage-migrator -am

  • Always create a backup of your code and storage before running the migrator

  • The migration is a one-way operation and cannot be undone

  • The type dictionary migration only updates metadata — your actual data remains unchanged

For more information see the readme file.

Storage Converter

The Storage Converter copies a storage from one storage target to another. 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

Add the storage converter dependency:

pom.xml
<dependencies>
	<dependency>
		<groupId>org.eclipse.store</groupId>
		<artifactId>storage-embedded-tools-storage-converter</artifactId>
		<version>4.0.1</version>
	</dependency>
</dependencies>

Standalone JAR

Build the standalone JAR by activating the converter-standalone Maven profile:

mvn -Pconverter-standalone clean package

Then run it with an external configuration file for each storage:

java -jar storage-embedded-tools-storage-converter-<version>-standalone.jar sourceConfig.xml targetConfig.xml

Java API

For more control, use the StorageConverter class directly with two StorageConfiguration instances:

StorageConfiguration source = StorageConfiguration.Builder()
	.setStorageFileProvider(
		StorageLiveFileProvider.New(
			NioFileSystem.New().ensureDirectoryPath("path", "to", "source", "storage")
		)
	)
	.createConfiguration();

StorageConfiguration target = StorageConfiguration.Builder()
	.setStorageFileProvider(
		StorageLiveFileProvider.New(
			NioFileSystem.New().ensureDirectoryPath("path", "to", "target", "storage")
		)
	)
	.setChannelCountProvider(StorageChannelCountProvider.New(4))
	.createConfiguration();

new StorageConverter(source, target).start();

To move from local file system to a cloud storage target, configure the target StorageConfiguration with the desired storage target. See Storage Targets for the available options.

  • The source storage must not be in use (not started) during the conversion

  • Always verify the target storage after conversion by starting it and validating your data

  • The converter creates a new independent copy — the source storage is not modified

For more information see the 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:
java -jar storage-embedded-tools-storage-converter-<version>-standalone.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:

... "-c binaryConverter1, binaryConverter2"