Running the code generator

You use the code generator to generate the API services and related code needed to implement the recommended partitions.

Before you begin

Ensure to meet the system requirements and the following code generator requirements.

The code generator must have access to:
- The cardinal directory created under the mono2micro-output directory (see Running the AI engine to analyze collected data). This directory contains partition information files and other files that the code generator uses, including a configuration file with two customizable parameters.
- The source code of the monolith application. Ensure that the application source code is the exact same that was used to generate the binary file during code analysis or the one used when running the code analyzer during source code analysis. The code generator copies relevant portions from the monolith to generate the refactored code.
The user running the code generator must have read and write access to the wanted output directory.

Also, customize the code generation process as needed. The app.config.txt file in the cardinal directory has two customizable parameters.

ApplicationName: The name of the refactored application. The value is used as the prefix for the generated code, URL and annotations.
CardinalOutPath: The location in the source code tree where utility class code is generated.

Procedure

Run the code generator to generate refactoring code for the recommended partitions.

Examine the cardinal directory.
An example that uses the Daytrader application is shown. The cardinal directory is copied from the mono2micro-output directory that was created earlier (see Running the AI engine to analyze collected data), while for this example the daytrader7-source directory is cloned from https://github.com/WASdev/sample.daytrader7.git.
```
transform-input
    ├── cardinal
    │   ├── app_config.txt
    │   ├── cardinal_graph.json
    │   ├── class_run.json
    │   ├── partition.txt
    │   ├── refTable.json
    │   └── symTable.json
    └── daytrader7-source
```
Run the code generator command.
```
mono2micro transform -s <src-dir-path> -p <partition-info-dir-path>
```
In this command, <src-dir-path> is the path name for the application source code directory and <partition-info-dir-path> is the path name for the cardinal directory that is created by the AI engine.

To get more information about the command and its options, run the mono2micro transform --help command.
Considerations:
- The user running the code generator has read and write access to the <src-dir-path> directory, because the code generator will create reports and source code in subdirectories under the <src-dir-path> directory.
- Using the figure where the monolith directory is named daytrader7-source, and if the cardinal directory that the AI engine generated are both located in the <dir-path> path, you run the code generator with the following command:
```
mono2micro transform -s <dir-path>/daytrader7-source -p <dir-path>/cardinal
```
Monitor the progress of the run.

Depending on the number of partitions and the size of the monolith, the time to complete the code generator task varies.

Running the code generator produces a large amount of informational messages. In most instances, the messages do not need any special attention. However, for possible configuration issues and for general understanding, redirecting the messages to a file for closer scrutiny is prudent.

If the code generator completes successfully, a cardinal-codegen directory is created within the <partition-info-dir-path> directory that contains various reports. For each partition, the code generator creates a directory containing the bulk of the code needed for its realization as a potential microservice. The code generator announces its completion and the creation of a reports directory.

Results

A successful completion of the code generator results in a directory structure similar to the following Daytrader directory structure.

transform-input
    ├── cardinal
    │   ├── app_config.txt
    │   ├── cardinal-codegen
    │   │   ├── Cardinal-Utility-report.txt
    │   │   ├── Cardinal-partition0-report.txt
    │   │   ├── Cardinal-partition1-report.txt
    │   │   ├── Cardinal-partition2-report.txt
    │   │   ├── Cardinal-partition3-report.txt
    │   │   ├── Cardinal-partition4-report.txt
    │   │   ├── CardinalFileSummary.json
    │   │   ├── CardinalFileSummary.txt
    │   │   └── CardinalSings.json
    │   ├── cardinal_graph.json
    │   ├── class_run.json
    │   ├── instrumenter-config.json
    │   ├── partition.txt
    │   ├── refTable.json
    │   └── symTable.json
    ├── daytrader7-source
    ├── daytrader7-source-Utility
    ├── daytrader7-source-partition0
    ├── daytrader7-source-partition1
    ├── daytrader7-source-partition2
    ├── daytrader7-source-partition3
    └── daytrader7-source-partition4

In this example, the daytrader-source-Utility partition contains Java monolithic application classes identified as potential utility classes. You can treat this partition as any other partition along with the IBM Mono2Micro generated code, or you can package these application classes as a utility .jar file with all other partitions that depend on the classes.

The highlighted directories are created by the code generator. The cardinal-codegen directory contains various reports, and various partitions are written in the xxx-partition_n directories, where xxx is the ApplicationName value and n is the partition number. For the example, the partitions are named daytrader7-source-partition_n (where 0 <= n <= 4). For more information, see Creating custom views.

Each of these xxx-partition_n directories contains the appropriate portions of the source code that is taken from the monolith under consideration. The output includes, but is not limited to, transformational wrappers, API services, code for distributed object management, and garbage collection. All of the code movement and generation is done automatically by the code generation component of Mono2Micro. At present the code generator only considers .java source files; it does not copy or generate any configuration or deployment information from the monolith. For actual deployment of the partitions as microservices, you must provide the appropriate configuration information.

The contents of the generated inner cardinal-codegen folder are various reports. The Cardinal-partition_n-report.txt (where 0 <= n <= 4) files are the Java invocation analysis reports for individual partitions in text form, as shown in figure for the partition_3 partition. You can specify the html option while running the code generator to generate a consolidated HTML version of the report. For more information, see Cardinal-Report.

Sample Cardinal-partition_1-report.txt report

The code generation component of Mono2Micro generates the CardinalFileSummary.txt file, which details all of the steps taken for generating the code. You use the report for debugging, for a deeper understanding of the code generation process, and for looking at the generated code. The report is for reference use only and is not used by any component of Mono2Micro.

For each partition, there are five categories of reports in the CardinalFileSummary.txt report. An abbreviated sample report is shown in the next figure.

Sample abbreviated CardinalFileSummary.txt report

The five categories of reports are:

Proxy: A report that contains stub classes for each partition that needs to access objects which are not local and belong to other partitions.
Service: A report that contains the APIs created for the objects of the partitions which are accessed from outside the partition.
Original: A report that contains the original intact Java files from monolith. These files are only accessed locally within the partition.
Dummy: A report that contains the files picked up during static source code analysis which are not used in runtime. Cardinal Exceptions are added to these files to ensure that appropriate runtime exceptions are generated if they are run. This category of report also informs the developers about potential dependencies on these files.
Helper: A report that contains generated code that handles such functions as serialization and exceptions for the recommended partitions and their corresponding interfaces.

The report also has a global category:

Copied: A report that contains classes that have no programming logic but are needed for compiling the partitions, such as interfaces and abstract classes.

The final report under the cardinal-codegen directory is CardinalSings.json. This file is intended for use by developers. This report lists the following content:

Lists the locations where code needs to be altered or where detailed inspection is necessary to implement partitions as potential microservices.
Lists action items for developers, keyed as CARDINAL_TODO_T<number>, which either must be addressed, or which are of the WARN variety. These warnings advise that developers to inspect and update code as necessary. Tasks are grouped into class and file levels. The following report shows the WARN TODOs while refactoring the sample Daytrader application. Detailed self-explanatory comments are provided by the code generator for each CARDINAL_TODO_T<number> task.