Developer info - OndraZizka/jboss-migration GitHub Wiki

MigrationApp - console UI
MigrationEngine - the main worker class
MigrationContext - keeps all the info created and needed during the lifecycle.

this.recognizeSourceServer(); // Puts ServerInfo to the context.
     // Includes serverInfo.compareHashes();
this.unzipDeployments();

this.loadSourceServerConfig();
// Ask all the migrators to create the actions to be performed.
this.prepareActions();
this.preValidateActions();
this.backupActions();
try {
    this.performActions();
    this.postValidateActions();
}
catch {
    this.rollbackPerformedActions();
}

• Configuration

•    GlobalConfiguration - source and target server
  

  •        AS5Config
    

  •        AS7Config
    

•    List<ModuleSpecificProperty> - configurations of specific migrators.
  

Each logical area of configuration is covered by one or more Migrators.
Migrator implements IMigrator, and is called during each lifecycle phase.
During the loadAS5Data(), it creates data objects containing AS 5 configuration info. Currently, all of them extend MigrationData. It will likely become an interface. More, these objects may implement use mix-ins like Origin.Wise and HasProperties, which are used for user interface - console UI and XML/HTML reports. During prepareActions(), it creates MigrationAction's. By that step, Migrator's involvement ends.

See How to Implement a new Migrator.

On the AS 7 side, the migration is a series of actions, like, creating a resource in AS 7, copying/merging a file, creating an AS 7 module.

After the actions are created, they are treated regardles what migrator they came from. (However, that info is kept for reporting/debugging purposes.)

Currently, the actions available are:

[[CopyFileAction]]
[[ModuleCreationAction]]
[[CliCommandAction]]
[[CreateDirectoryAction]]
[[MergeFileAction]]
[[ManualAction]]

Actions are supposed to stay low-level, and new ones should be only created if the goal is not achievable using the existing ones. The new ones must be discussed.

Migrators may declare dependency relationships between actions.
For example, to implement IfExists == OVERWRITE, removal of pre-existing resource is needed (none of mgmt API ops follow any overwrite concept). This operation would be a dependency of the action re-creating the resource.
Then, right before perform() (actually, at the begining of), the actions are sorted as per these dependencies.
Implementations of Migrators should declare these dependencies.

Actions may be in a state which reflects the lifecycle stages. It's a mechanism to check consistency of both actions and MigrationEngine implementations. In case some action would break, you might see:

RuntimeException: Action not in expected states DONE ROLLED_BACK, but in BACKED_UP:
Create an AS 7 module 'jdbcdrivers.createdDriver1' from .jar testdata/as5configs/02_EAP-520-prod/common/lib/hsqldb.jar, deps: javax.api javax.transaction.api  javax.servlet.api
at org.jboss.loom.actions.AbstractStatefulAction.checkState(AbstractStatefulAction.java:63)
....

The states are:

• INITIAL - after created.
• BACKED_UP - after backup().
  • DONE - after perform().
  • ROLLED_BACK - after rollback(), should that happen.
• FINISHED - after cleanupBackup().

is special: It's purpose is to inform the user about parts of the configuration which are not automated - either not implemented yet, or too complex, or not migratable (N/A in AS 7+). See it's addWarning( String ) and List<String> getWarnings() methods.

is specific - during it's perform(), it doesn't really send the Cli command to the server; rather it queues it in a CLI batch in the context. + The batch is executed at the end of the performActions() lifecycle phase.

This action also as an "IfExists" strategy - an option what to do if the given DMR resource already exists:

public enum IfExists {
    FAIL, WARN, SKIP, MERGE, OVERWRITE, ASK;
}

MERGE and ASK are not implemented yet.

ASK is intended for future interactive handling (asking the user).

MigrationContext is available during whole lifecycle, and contains:

• Migrators configurations
• Data objects with AS 5 config info
• Actions created by Migrators and to be performed
• AS 7 CLI batch
• AS 7 CLI connection - opened before prepareActions()
• Info about deployments
  • Original path
  • Unzipped-to dir

During the recognizeSourceServer() phase, files in the source server are compared against the CRC32 hash list distributed with the application. This happens if the IServerType implementation also implements HasHashes. If it does, the ServerType is expected to be able to provide a Map<Path, Long> paths-to-hashes map.

For example, JBossAS5ServerType has it's lists as resources in /fileHashes/as5/*-crc32.txt.

92ae740a bin/twiddle.bat
2ea973a9 bin/password_tool.sh
0a6de6b8 bin/run.conf.bat
e2c84e29 bin/jboss_init_hpux.sh

Deviations from the hashes are reported at an early stage of the application.

10:00:55,256  INFO MigrationEngine:215 - Commencing migration.
10:00:55,257 DEBUG MigrationEngine:521 - ======== recognizeSourceServer() ========
10:00:55,259 DEBUG ServerRecognizer:30 -     Trying JBossAS5ServerType
10:00:55,267  INFO MigrationEngine:526 - Source server recognized as JBoss EAP 5.2.0 in testdata/as5configs/02_EAP-520-prod
10:00:55,413  INFO MigrationEngine:531 - Hash comparison against distribution files: 200 match, 1 mism,     1090 miss, 2 empty
10:00:55,414  INFO MigrationEngine:551 -     MISMATCH: testdata/as5configs/02_EAP-520-prod/common/lib/hsqldb.jar
10:00:55,414  INFO MigrationEngine:553 - This is a test run, MISSING and EMPTY files aren't printed.

The results are also in the Context available to the Migrators.