Skip to content

Commit 2bd44ba

Browse files
JohannesRabauerJohannesRabauer
committed
Added Docs / Cleanup
1 parent 6e7773d commit 2bd44ba

File tree

7 files changed

+130
-22
lines changed

7 files changed

+130
-22
lines changed

‎docs/modules/ROOT/nav.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,8 @@
88
** xref:features/queries.adoc[Queries]
99
** xref:features/transactions.adoc[Transactions]
1010
** xref:features/versions.adoc[Versions]
11+
** xref:features/versioned-migration.adoc[Versioned Migration]
1112
** xref:features/rest-api.adoc[REST Interface]
1213
** xref:features/validation-constraints.adoc[Validation Constraints]
13-
* xref:migration.adoc[Migration from JPA]
14+
* xref:migration-from-jpa.adoc[Migration from JPA]
1415
* xref:known-issues.adoc[Known issues]

‎docs/modules/ROOT/pages/features/features.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,6 @@
55
* xref:features/queries.adoc[Queries]
66
* xref:features/transactions.adoc[Transactions]
77
* xref:features/versions.adoc[Versions]
8+
* xref:features/versioned-migration.adoc[Versioned Migration]
89
* xref:features/rest-api.adoc[REST Interface]
910
* xref:features/validation-constraints.adoc[Validation Constraints]

‎docs/modules/ROOT/pages/features/versioned-migration.adoc

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
= Versioned Migration
2+
3+
To keep the data in the store up-to-date, {product-name} utilizes https://github.com/xdev-software/micro-migration[XDEV's Micro-Migration].
4+
This means the user can use versioning for the stored data and only apply changes for certain versions of data.
5+
This can be very useful specifically with build-pipelines. https://github.com/xdev-software/micro-migration#intro[More info at Micro-Migration...]
6+
7+
== Implementation
8+
9+
This can be easily achieved by either of these 3 methods:
10+
11+
=== 1. Reflective Scripts
12+
13+
Simply implement a new component with a specific pattern of naming, that extends the ``ReflectiveDataMigrationScript``.
14+
15+
[source,java,title="https://github.com/xdev-software/spring-data-eclipse-store/blob/develop/spring-data-eclipse-store-demo/src/main/java/software/xdev/spring/data/eclipse/store/demo/complex/migration/v1_0_0_Init.java[Reflective example from complex demo]"]
16+
----
17+
package software.xdev.spring.data.eclipse.store.demo.complex.migration;
18+
19+
import org.springframework.beans.factory.annotation.Autowired;
20+
import org.springframework.stereotype.Component;
21+
//...
22+
import software.xdev.spring.data.eclipse.store.repository.root.data.version.ReflectiveDataMigrationScript;
23+
24+
@Component
25+
public class v1_0_0_Init extends ReflectiveDataMigrationScript
26+
{
27+
private final OwnerService service;
28+
29+
@Autowired
30+
public v1_0_0_Init(final OwnerService service)
31+
{
32+
this.service = service;
33+
}
34+
35+
@Override
36+
public void migrate(final Context<VersionedRoot, MigrationEmbeddedStorageManager> context)
37+
{
38+
this.service.createNewOwnerAndVisit("Mick", "Fleetwood", "Isabella");
39+
}
40+
}
41+
----
42+
43+
Here the version number on which the data is updated on execution is derived from the class name.
44+
45+
The ``MigrationVersion`` is stored in the root object in the data store.
46+
Therefore, the storage always knows on which version the current data is and the ``DataMigrater`` will only execute the newer scripts.
47+
48+
The scripts are automatically registered by declaring them as ``@Component``s.
49+
That means that they can be anywhere as long as they are discovered by Spring as a component.
50+
51+
=== 2. Custom Scripts
52+
53+
Implementing a script without special naming is possible by implementing the
54+
``DataMigrationScript``.
55+
56+
[source,java,title="https://github.com/xdev-software/spring-data-eclipse-store/blob/develop/spring-data-eclipse-store-demo/src/main/java/software/xdev/spring/data/eclipse/store/demo/complex/migration/CustomNameScript.java[Custom script example from complex demo]"]
57+
----
58+
package software.xdev.spring.data.eclipse.store.demo.complex.migration;
59+
60+
import org.springframework.beans.factory.annotation.Autowired;
61+
import org.springframework.stereotype.Component;
62+
//...
63+
import software.xdev.spring.data.eclipse.store.repository.root.data.version.DataMigrationScript;
64+
65+
@Component
66+
public class CustomNameScriptAddOwner implements DataMigrationScript
67+
{
68+
private final OwnerService service;
69+
70+
public CustomNameScriptAddOwner(@Autowired final OwnerService service)
71+
{
72+
this.service = service;
73+
}
74+
75+
@Override
76+
public MigrationVersion getTargetVersion()
77+
{
78+
return new MigrationVersion(1, 1, 0);
79+
}
80+
81+
@Override
82+
public void migrate(final Context<VersionedRoot, MigrationEmbeddedStorageManager> context)
83+
{
84+
this.service.createNewOwnerAndVisit("John", "McVie", "Ivan");
85+
}
86+
}
87+
----
88+
89+
The version number must be returned explicitly in the ``#getTargetVersion``-method.
90+
91+
=== 3. Custom Migrater
92+
93+
If more customization is needed it is also possible to replace the ``DataMigrater`` completely and implement your own ``MicroMigrater``.
94+
This should only be used if necessary since it adds a lot of complexity to the code.
95+
96+
[source,java,title="https://github.com/xdev-software/spring-data-eclipse-store/blob/develop/spring-data-eclipse-store/src/test/java/software/xdev/spring/data/eclipse/store/integration/isolated/tests/data/migration/with/migrater/CustomMigrater.java[Custom migrater from tests]"]
97+
----
98+
package software.xdev.spring.data.eclipse.store.integration.isolated.tests.data.migration.with.migrater;
99+
100+
import org.springframework.beans.factory.annotation.Autowired;
101+
import org.springframework.stereotype.Component;
102+
import software.xdev.micromigration.migrater.ExplicitMigrater;
103+
import software.xdev.micromigration.migrater.MicroMigrater;
104+
//...
105+
106+
@Component
107+
public class CustomMigrater implements MicroMigrater
108+
{
109+
private final ExplicitMigrater explicitMigrater;
110+
111+
@Autowired
112+
public CustomMigrater(final PersistedEntityRepository repository)
113+
{
114+
this.explicitMigrater = new ExplicitMigrater(new v1_0_0_Init(repository));
115+
}
116+
----

‎docs/modules/ROOT/pages/migration.adoc renamed to ‎docs/modules/ROOT/pages/migration-from-jpa.adoc

File renamed without changes.

‎spring-data-eclipse-store-demo/src/main/java/software/xdev/spring/data/eclipse/store/demo/complex/migration/CustomNameScriptAddOwner.java renamed to ‎spring-data-eclipse-store-demo/src/main/java/software/xdev/spring/data/eclipse/store/demo/complex/migration/CustomNameScript.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,11 @@
3434
* In contrast to {@link v1_0_0_Init} the version of this script is defined in the method {@link #getTargetVersion()}.
3535
*/
3636
@Component
37-
public class CustomNameScriptAddOwner implements DataMigrationScript
37+
public class CustomNameScript implements DataMigrationScript
3838
{
3939
private final OwnerService service;
4040

41-
public CustomNameScriptAddOwner(@Autowired final OwnerService service)
41+
public CustomNameScript(@Autowired final OwnerService service)
4242
{
4343
this.service = service;
4444
}

‎spring-data-eclipse-store-demo/src/main/java/software/xdev/spring/data/eclipse/store/demo/complex/migration/v1_0_0_Init.java

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
* {@link software.xdev.spring.data.eclipse.store.repository.root.data.version.DataMigrater} through dependency
3131
* injection.
3232
* <p>
33-
* In contrast to {@link CustomNameScriptAddOwner} the version of this script is defined by
33+
* In contrast to {@link CustomNameScript} the version of this script is defined by
3434
* <b>the name of the class defines the version</b>.
3535
*/
3636
@SuppressWarnings("CheckStyle")
@@ -39,7 +39,8 @@ public class v1_0_0_Init extends ReflectiveDataMigrationScript
3939
{
4040
private final OwnerService service;
4141

42-
public v1_0_0_Init(@Autowired final OwnerService service)
42+
@Autowired
43+
public v1_0_0_Init(final OwnerService service)
4344
{
4445
this.service = service;
4546
}

‎spring-data-eclipse-store/src/test/java/software/xdev/spring/data/eclipse/store/integration/isolated/tests/data/migration/with/migrater/CustomMigrater.java

Lines changed: 6 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -32,28 +32,18 @@
3232
@Component
3333
public class CustomMigrater implements MicroMigrater
3434
{
35-
private ExplicitMigrater explicitMigrater;
36-
final PersistedEntityRepository repository;
35+
private final ExplicitMigrater explicitMigrater;
3736

3837
@Autowired
3938
public CustomMigrater(final PersistedEntityRepository repository)
4039
{
41-
this.repository = repository;
42-
}
43-
44-
private ExplicitMigrater ensureExplicitMigrater()
45-
{
46-
if(this.explicitMigrater == null)
47-
{
48-
this.explicitMigrater = new ExplicitMigrater(new v1_0_0_Init(this.repository));
49-
}
50-
return this.explicitMigrater;
40+
this.explicitMigrater = new ExplicitMigrater(new v1_0_0_Init(repository));
5141
}
5242

5343
@Override
5444
public TreeSet<? extends VersionAgnosticMigrationScript<?, ?>> getSortedScripts()
5545
{
56-
return this.ensureExplicitMigrater().getSortedScripts();
46+
return this.explicitMigrater.getSortedScripts();
5747
}
5848

5949
@Override
@@ -62,7 +52,7 @@ private ExplicitMigrater ensureExplicitMigrater()
6252
final E storageManager,
6353
final Object root)
6454
{
65-
return this.ensureExplicitMigrater().migrateToNewest(fromVersion, storageManager, root);
55+
return this.explicitMigrater.migrateToNewest(fromVersion, storageManager, root);
6656
}
6757

6858
@Override
@@ -72,15 +62,14 @@ private ExplicitMigrater ensureExplicitMigrater()
7262
final E storageManager,
7363
final Object objectToMigrate)
7464
{
75-
return this.ensureExplicitMigrater()
76-
.migrateToVersion(fromVersion, targetVersion, storageManager, objectToMigrate);
65+
return this.explicitMigrater.migrateToVersion(fromVersion, targetVersion, storageManager, objectToMigrate);
7766
}
7867

7968
@Override
8069
public void registerNotificationConsumer(
8170
final Consumer<ScriptExecutionNotificationWithScriptReference> notificationConsumer
8271
)
8372
{
84-
this.ensureExplicitMigrater().registerNotificationConsumer(notificationConsumer);
73+
this.explicitMigrater.registerNotificationConsumer(notificationConsumer);
8574
}
8675
}

0 commit comments

Comments
 (0)