Changes between Version 13 and Version 14 of PluginDevelopmentGuide


Ignore:
Timestamp:
12.04.2013 17:43:59 (7 years ago)
Author:
jri
Comment:

Migration directory structure

Legend:

Unmodified
Added
Removed
Modified
  • PluginDevelopmentGuide

    v13 v14  
    417417If no `plugin.properties` file is present, the default configuration values apply. 
    418418 
    419 === Writing migrations === 
     419=== The two kinds of migrations === 
    420420 
    421421As 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: 
    422422 
    423     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. 
     423    * 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. 
    424424 
    425425    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. 
    426426 
    427     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. 
    428  
    429 ==== Declarative migrations ==== 
     427    * 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. 
     428 
     429The developer can equip a plugin with an arbitrary number of both, declarative migrations and imperative migrations. 
     430 
     431=== Directory structure === 
     432 
     433In 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. 
     434 
     435A declarative migration must be named `migration<nr>.json` and must be located in the plugin's `src/main/resources/migrations/` directory. 
     436 
     437An imperative migration must be named `Migration<nr>.java` and must be located in the plugin's `src/main/java/<your plugin package>/migrations/` directory. 
     438 
     439Example: 
     440 
     441{{{ 
     442#!txt 
     443dm4-myplugin/ 
     444    src/ 
     445        main/ 
     446            java/ 
     447                org/ 
     448                    mydomain/ 
     449                        deepamehta4/ 
     450                            myplugin/ 
     451                                migrations/ 
     452                                    Migration2.java 
     453                                    Migration5.java 
     454            resources/ 
     455                migrations/ 
     456                    migration1.json 
     457                    migration3.json 
     458                    migration4.json 
     459                    migration6.json 
     460                plugin.properties 
     461}}} 
     462 
     463This 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. 
     464 
     465Important: 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. 
     466 
     467It 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. 
     468 
     469=== Writing a declarative migration === 
    430470 
    431471A 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: 
     
    501541As 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. 
    502542 
    503 ==== Imperative migrations ==== 
     543=== Writing an imperative migration ===