Changes between Version 13 and Version 14 of PluginDevelopmentGuide

Timestamp:

12.04.2013 17:43:59 (12 years ago)

Author:

jri

Comment:

Migration directory structure

PluginDevelopmentGuide

@@ -417 +417 @@
 If no `plugin.properties` file is present, the default configuration values apply.
 
-=== Writing migrations ===
+=== The two kinds of migrations ===
 
 As you've already learned, migrations serve different (but related) purposes: some just //create// new type definitions and others //modify// existing type definitions and/or transform existing database content. To support the developer with these different tasks DeepaMehta offers two kinds of migrations:
 
-    Declarative migration:: a declarative migration is a JSON file that declares 4 kinds of things: topic types, association types, topics, associations. Use a declarative migration to let DeepaMehta create new types and instances in the database. Use a declarative migration to let your plugin setup the initial type definitions.
+    * A **Declarative Migration** is a JSON file that declares 4 kinds of things: topic types, association types, topics, associations. Use a declarative migration to let DeepaMehta create new types and instances in the database. Use a declarative migration to let your plugin setup the initial type definitions.
 
     With a declarative migration you can only create new things. You can't modify existing things. All you do with a declarative migration you could achieve with an imperative migration as well, but as long as you just want create new things, it is more convenient to do it declaratively.
 
-    Imperative migration:: an imperative migration is a Java class that has access to the //DeepaMehta Core Service//. Thus, you can perform arbitrary database operations like creation, retrieval, update, deletion. Use an imperative migration when (a later version of) your plugin needs to modify existing type definitions and/or transform existing database content.
-
-==== Declarative migrations ====
+    * An **Imperative Migration** is a Java class that has access to the //DeepaMehta Core Service//. Thus, you can perform arbitrary database operations like creation, retrieval, update, deletion. Use an imperative migration when (a later version of) your plugin needs to modify existing type definitions and/or transform existing database content.
+
+The developer can equip a plugin with an arbitrary number of both, declarative migrations and imperative migrations.
+
+=== Directory structure ===
+
+In order to let DeepaMehta find the plugin's migration files, you must adhere to a fixed directory structure and file names. Each migration file must contain its number, so DeepaMehta can run them consecutively.
+
+A declarative migration must be named `migration<nr>.json` and must be located in the plugin's `src/main/resources/migrations/` directory.
+
+An imperative migration must be named `Migration<nr>.java` and must be located in the plugin's `src/main/java/<your plugin package>/migrations/` directory.
+
+Example:
+
+{{{
+#!txt
+dm4-myplugin/
+    src/
+        main/
+            java/
+                org/
+                    mydomain/
+                        deepamehta4/
+                            myplugin/
+                                migrations/
+                                    Migration2.java
+                                    Migration5.java
+            resources/
+                migrations/
+                    migration1.json
+                    migration3.json
+                    migration4.json
+                    migration6.json
+                plugin.properties
+}}}
+
+This example plugin would have set `requiredPluginMigrationNr` to 6 (configured in `plugin.properties`), so 6 migrations are involved. 4 are declarative and 2 are imperative here.
+
+Important: for each number between 1 and `requiredPluginMigrationNr` exactly one migration file must exist. That is //either// a declarative migration file //or// an imperative migration file.
+
+It would be invalid if for a given number a) no migration file exists, or b) two migration files exist (one declarative and one imperative). In these cases the DeepaMehta migration machinery throws an error and the plugin is not activated.
+
+=== Writing a declarative migration ===
 
 A declarative migration is a JSON file with exactly one JSON Object in it. In a declarative migration you can define 4 things: topic types, association types, topics, associations. The general format is:
@@ -501 +541 @@
 As you see, this migration defines 3 topic types (and no other things): the 2 simple types //Title// and //Text//, and the composite type //Note//. A Note is composed of a Title and a Text.
 
-==== Imperative migrations ====
+=== Writing an imperative migration ===