Merge branch 'develop' into update-from-template-merged

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -14,9 +14,9 @@ body:
     attributes:
       label: "Checklist"
       options:
-        - label: "I am able to reproduce the bug with the [latest version](https://github.com/xdev-software/template-placeholder/releases/latest)"
+        - label: "I am able to reproduce the bug with the [latest version](https://github.com/xdev-software/micro-migration/releases/latest)"
           required: true
-        - label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/template-placeholder/issues) or [closed](https://github.com/xdev-software/template-placeholder/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
+        - label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/micro-migration/issues) or [closed](https://github.com/xdev-software/micro-migration/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
           required: true
         - label: "I have taken the time to fill in all the required details. I understand that the bug report will be dismissed otherwise."
           required: true

.github/ISSUE_TEMPLATE/enhancement.yml

@@ -12,7 +12,7 @@ body:
     attributes:
       label: "Checklist"
       options:
-        - label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/template-placeholder/issues) or [closed](https://github.com/xdev-software/template-placeholder/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
+        - label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/micro-migration/issues) or [closed](https://github.com/xdev-software/micro-migration/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
           required: true
         - label: "I have taken the time to fill in all the required details. I understand that the feature request will be dismissed otherwise."
           required: true

.github/ISSUE_TEMPLATE/question.yml

@@ -12,7 +12,7 @@ body:
     attributes:
       label: "Checklist"
       options:
-        - label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/template-placeholder/issues) or [closed](https://github.com/xdev-software/template-placeholder/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
+        - label: "I made sure that there are *no existing issues* - [open](https://github.com/xdev-software/micro-migration/issues) or [closed](https://github.com/xdev-software/micro-migration/issues?q=is%3Aissue+is%3Aclosed) - which I could contribute my information to."
           required: true
         - label: "I have taken the time to fill in all the required details. I understand that the question will be dismissed otherwise."
           required: true

CHANGELOG.md

@@ -0,0 +1,37 @@
+## 2.0.0
+_Major refactoring_
+* Consolidated all previous modules into a single one
+* Dropped support for MicroStream as EclipseStore is it's successor
+* Refactored and adjusted code accordingly
+* Slimed down dependencies
+* Minimal required Java version: 17
+
+## 1.0.0
+* Added support for EclipseStore v1
+* Updated plenty of libraries
+
+## 0.0.9
+* Added support for MicroStream v8
+
+## 0.0.8
+* Access to the native embedded manager is now possible in the scripts (see ``VersionAgnosticMigrationEmbeddedStorageManager#getNativeStorageManager``)
+
+## 0.0.7
+* A lot of refactoring of the module structure
+* A migration history is now available and automatically stored
+
+## 0.0.6
+* Tried a new release-action...again.
+
+## 0.0.5
+* Tried a new release-action.
+
+## 0.0.4
+* Fixed setup. 0.0.3 was not working with the release setup.
+
+## 0.0.3
+* Restructured the complete maven modules. Multiple MicroStream-Versions are now supported.
+* Added plenty of documentation
+
+## 0.0.2
+* Updated MicroStream from v4 to v5.

CONTRIBUTING.md

@@ -34,10 +34,10 @@ You should have the following things installed:
   * Ensure that the JDK/Java-Version is correct
 
 
-## Releasing [![Build](https://img.shields.io/github/actions/workflow/status/xdev-software/template-placeholder/release.yml?branch=master)](https://github.com/xdev-software/template-placeholder/actions/workflows/release.yml)
+## Releasing [![Build](https://img.shields.io/github/actions/workflow/status/xdev-software/micro-migration/release.yml?branch=master)](https://github.com/xdev-software/micro-migration/actions/workflows/release.yml)
 
 Before releasing:
-* Consider doing a [test-deployment](https://github.com/xdev-software/template-placeholder/actions/workflows/test-deploy.yml?query=branch%3Adevelop) before actually releasing.
+* Consider doing a [test-deployment](https://github.com/xdev-software/micro-migration/actions/workflows/test-deploy.yml?query=branch%3Adevelop) before actually releasing.
 * Check the [changelog](CHANGELOG.md)
 
 If the ``develop`` is ready for release, create a pull request to the ``master``-Branch and merge the changes

README.md

@@ -1,12 +1,120 @@
-[![Latest version](https://img.shields.io/maven-central/v/software.xdev/template-placeholder?logo=apache%20maven)](https://mvnrepository.com/artifact/software.xdev/template-placeholder)
-[![Build](https://img.shields.io/github/actions/workflow/status/xdev-software/template-placeholder/check-build.yml?branch=develop)](https://github.com/xdev-software/template-placeholder/actions/workflows/check-build.yml?query=branch%3Adevelop)
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=xdev-software_template-placeholder&metric=alert_status)](https://sonarcloud.io/dashboard?id=xdev-software_template-placeholder)
+[![Latest version](https://img.shields.io/maven-central/v/software.xdev/micro-migration?logo=apache%20maven)](https://mvnrepository.com/artifact/software.xdev/micro-migration)
+[![Build](https://img.shields.io/github/actions/workflow/status/xdev-software/micro-migration/check-build.yml?branch=develop)](https://github.com/xdev-software/micro-migration/actions/workflows/check-build.yml?query=branch%3Adevelop)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=xdev-software_micro-migration&metric=alert_status)](https://sonarcloud.io/dashboard?id=xdev-software_micro-migration)
 
-# template-placeholder
+# <img src="assets/Logo.png" width="400" alt="XDEV MicroMigration Logo">
+Tiny java library to migrate [EclipseStore](https://github.com/eclipse-store/store) datastores. 
+Applies migration scripts on the datastores to keep them up to date.
 
+## Intro
+When you think about default database setup, you probably imagine something like this:
+
+![Imaginative system layout](./assets/MigrationSequence_1.png "Imaginative system layout")
+
+Yet in reality most workflows involve different systems like test systems and production systems. 
+In code this workflow is represented with version-control systems and different branches.
+
+![Code workflow](./assets/MigrationSequence_2.png "Code workflow")
+
+For this code workflow to behave correctly, for each system a separate datastore is needed.
+To keep these datastores to represent the correspondend data for the code is a hassle.
+
+![Code workflow with datastore](./assets/MigrationSequence_3.png "Code workflow with datastore")
+
+That's why migration frameworks like [Flyway](https://flywaydb.org) and [Liquibase](https://www.liquibase.org/) exist.
+Unfortunately both these frameworks are designed to support any type of SQL databases but no NoSQL databases like [EclipseStore](https://eclipsestore.io/). This led to the creation of this library.
+
+This library delivers an easy concept to keep your EclipseStore datastore versioned with migration scripts written in plain java.
+It's easy to create code, that automatically brings a datastore with an older version to the version, suited to the current code.
+
+![Migrate datastore to new version](./assets/MigrationSequence_4.png "Migrate datastore to new version")
+
+## Approaches
+There are two possible usages with the Micro migration library:
+
+The **first**, easier approach is to use the `MigrationEmbeddedStorageManager`.
+It can be used on a brand new datastore or introduced later, after a EclipseStore datastore is already in use.
+Only the storage manager (`MigrationEmbeddedStorageManager`) knows about the versioning. 
+The rest of application does not know about the version and can have no regards about it.
+
+### MigrationEmbeddedStorageManager
+Extensive examples can be found in its own [own module](./micro-migration-demo).
+A simple example where scripts need to be registered in the `ExplicitMigrater`:
+
+```java
+public static void main(String[] args){
+	ExplicitMigrater migrater = new ExplicitMigrater(new UpdateToV1_0());
+	MigrationEmbeddedStorageManager storageManager = MigrationEmbeddedStorage.start(migrater);
+	// Do some business logic
+	storageManager.shutdown();
+}
+```
+
+The update scripts can look like this:
+
+```java
+public class UpdateToV1_0 implements MigrationScript<Object>
+{
+	@Override
+	public MigrationVersion getTargetVersion(){
+		return new MigrationVersion(1);
+	}
+
+	@Override
+	public void migrate(Context<String, EmbeddedStorageManager> context){
+		// Logic of the update
+		context.getStorageManager().setRoot("Update 1.0");
+	}
+}
+```
+
+### MigrationManager
+Although the approach with the `MigrationEmbeddedStorageManager` is pretty easy to handle, it is intrusive in the way, that it replaces the root entry point of the EclipseStore datastore and inserts its own `VersionedRoot` as root. Some users might find this too entrusive.
+
+That's why a second approach can be used, where the `MigrationManager` is used. This class is also used internally by the `MigrationEmbeddedStorageManager`. 
+
+```java
+public static void main(String[] args){
+	ExplicitMigrater migrater = new ExplicitMigrater(new UpdateToV1_0());
+	EmbeddedStorageManager storageManager = EmbeddedStorage.start();
+		VersionedObject<Object> versionedRoot =(VersionedObject<Object>)storageManager.root();
+		new MigrationManager(versionedRoot, migrater, storageManager).migrate(versionedBranch);
+	// Do some business logic
+	storageManager.shutdown();
+}
+```
+
+## Migrater
+### ExplicitMigrater
+Scripts for the migrations must be registered in a `MicroMigrater`. 
+The simplest way for this is to use the `ExplicitMigrater` and just put the scripts in the constructor.
+A downside of this method is that you need to register all scripts (new or old) manually in the constructor.
+
+```java
+final ExplicitMigrater migrater = new ExplicitMigrater(
+	new UpdateToV1_0(),
+	new UpdateToV1_1()
+);
+```
+
+### ReflectiveMigrater
+For a more convenient usage the `ReflectiveMigrater` was built. 
+You simply instanciate a object of this class with the package name of your `MicroMigrationScript`s.
+The `ReflectiveMigrater` will search for any implementations of `MicroMigrationScript` in the given package.
+This way scripts can simply be placed in the same package and on startup of the application all scripts are loaded in.
+
+```java
+final ReflectiveMigrater migrater = new ReflectiveMigrater("software.xdev.micromigration.examples.reflective.scripts");
+```
 
 ## Installation
-[Installation guide for the latest release](https://github.com/xdev-software/template-placeholder/releases/latest#Installation)
+[Installation guide for the latest release](https://github.com/xdev-software/micro-migration/releases/latest#Installation)
+
+### Compatibility
+| Eclipse Store version | micro-migration version |
+| --- | --- |
+| [EclipseStore](https://github.com/eclipse-store/store) 1+ | ``2+`` |
+| [MicroStream](https://github.com/microstream-one/microstream) 5-8<br/>EclipseStore 1.1 | ``1.x`` |
 
 ## Support
 If you need support as soon as possible and you can't wait for any pull request, feel free to use [our support](https://xdev.software/en/services/support).
@@ -15,4 +123,4 @@ If you need support as soon as possible and you can't wait for any pull request,
 See the [contributing guide](./CONTRIBUTING.md) for detailed instructions on how to get started with our project.
 
 ## Dependencies and Licenses
-View the [license of the current project](LICENSE) or the [summary including all dependencies](https://xdev-software.github.io/template-placeholder/dependencies)
+View the [license of the current project](LICENSE) or the [summary including all dependencies](https://xdev-software.github.io/micro-migration/dependencies)

SECURITY.md

@@ -2,4 +2,4 @@
 
 ## Reporting a Vulnerability
 
-Please report a security vulnerability [on GitHub Security Advisories](https://github.com/xdev-software/template-placeholder/security/advisories/new).
+Please report a security vulnerability [on GitHub Security Advisories](https://github.com/xdev-software/micro-migration/security/advisories/new).

assets/MigrationSequence.drawio

@@ -0,0 +1 @@
+<mxfile modified="2020-12-26T15:46:51.284Z" host="app.diagrams.net" agent="5.0 (Windows)" etag="FPBT0h_c40Cmh-uRLp35" version="14.1.2" type="onedrive"><diagram id="l8hXMBHkgcEJcSW0mbfh" name="Page-1">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</diagram></mxfile>

micro-migration-demo/README.md

@@ -0,0 +1,21 @@
+# micro-migration-examples
+Examples for the MicroMigration-Library
+
+Currently contains four major examples:
+## Example with `ExplicitMigrater`
+In the package `software.xdev.micromigration.examples.explicit` there is a simple example with explicitly listed upgrade scripts.
+This is the most straight forward approach to use migration scripts.
+
+## Example with `ReflectiveMigrater`
+In package `software.xdev.micromigration.examples.reflective` a migrater which finds it's scripts through reflection is used.
+So here all `MicroMigrationScript`s in the defined  `software.xdev.micromigration.examples.reflective.scripts` package are used.
+
+## Practical examples
+The package `software.xdev.micromigration.examples.practical.embedded` contains examples
+that are just a bit more complex than the other examples and should allow an insight about the usage in a 
+practical environment.
+
+There is one example implemented with the `MigrationEmbeddedStorageManager` and another with the
+plain `MigrationManager`, so it is clear what the difference between these two approaches is.
+In both implementations the first update migrates from version 0 to 1 and converts an "old" `BusinessBranch`
+to a newer one. The second update only adds more `Customer`s to the existing `BusinessBranch`.