Sun Java System Portal Server 6 2004Q2 Migration Guide |
Appendix B
Sun ONE Portal Server 3.0 Data Migration Module Author's Guide
The data migration tools are designed to be expandable by using modules. The module can define a menu option, order items within the menu, and specify when it should run relative to other modules. The migration tools themselves are designed as a series of modules which makes them excellent examples of how to write modules.
This appendix contains the following sections:
What Makes a Module?The syntax for module file names is:
[0-9][0-9][descriptive_text][export,convert, or import]
Migration modules must meet certain criteria. In particular, they must:
- Exist under the installed migration directory /modules.
The migration tools are located in BaseDir/SUNWps/migration. The core migration tools search for modules in BaseDir/SUNWps/migration/modules in order to build the module list used by the migration executables. Each of the core module’s directories (cert, desktop, ldap, rules) contain all the files needed to support the module as well as the module executables. For better organization, you should create your own directory under the modules directory that contains all files needed to run your module, even though files located directly in the modules directory will be added.
- Have the digits 0-9 as the first two characters of the file name.
The first two digits of the module’s file name tell the core tools where in the menu this module belongs as well as the execution order of the module. A higher number will run later in the process. A lower number will run earlier. LDAP is priority 40, Desktop is 50, and certificate is 60. So the menu appears as:
1) LDAP Database
2) Desktop
3) Certificate Databases
4) All of the above
5) Exit
If, for example, you place a new module file 30customexport in BaseDir/SUNWps/migration/modules/custom, the export menu would appear as:
1) Custom menu text
2) LDAP Database
3) Desktop
4) Certificate Databases
5) All of the above
6) Exit
If the user selected All of the above, the custom module would be run first, LDAP second, Desktop third, and certificate last.
- Have a file name ending with export, convert, or import.
The last text of the filename must be one of these, otherwise the core tools will not recognize them. There can be other text between the priority number (described in the next bullet) and the suffix to give more meaning to the name. For example, 40ldapexport is the name of the LDAP export module.
- Be written in ksh.
The core tools, written in ksh, call the module files using the “.” function. This requires that the module be written in ksh. Other executables, however, can be run within the module file. The module has access to all variables defined within the core tools, including JAVA_HOME and PERL which allows Java and perl code to be run within the module. There are many examples of this within the LDAP and Desktop modules.
- Be executable.
The module file must be executable in order to be recognized as a module. Note that module files that return a non-zero exit code will cause the core tool to stop and print an error message. Module files that return zero will assume to have completed successfully.
- Return a single line of text or nothing when invoked with the --menu option.
The text returned represents the option that will be placed in the menu. If no text is returned, the module is considered “always-run” and will be executed regardless of the option the user selects. The menu option text must be localized by the module file prior to returning the value to the core tool.
Module ExampleThis section provides examples of the Desktop module located in BaseDir/SUNWps/migration/modules/desktop.
Desktop Module Files
Table B-1 shows the files comprising the Desktop module and their definitions. This two-column table shows the module name in the first column and its description in the second column.
Module Code Examples
This section provides code extracts from two Desktop Modules.
Note that the Desktop menu option localized the menu option prior to printing it.
Important Variables
Table B-2 shows variables that are considered important for use by modules. This two-column table shows the variable in the first column and its description in the second column.
All variables and functions in each of the core tools are available to the module files.
The following is an example of writing to $reportFile and $errorFile:
if [ ! -d $tempDesktop/exportData ]; then
print “`$GETTEXT ‘Error - Cannot find exported template data in’` $tempDesktop/exportData” | tee -a $errorFile $reportFile