Hosting Multiple Modules in One Package

By default, the apimodule and msgmodule project templates host a single module in the generated zip package. Additional modules can be added to a project.

Background

This topic covers how to add additional message or API modules to an existing package.

If your architecture requires multiple related modules, it is often more convenient to host them in a single project and deploy them as one zipped package. A package can contain a combination of message modules and API modules.

Prerequisites

• Java 8 or higher

• Maven

• The completed ShoppingCart API module

• The completed FlightTracker MSG module.

Procedure

1. Add classes for the new module

Tip

Instead of manually creating classes as described in this step, you can create a temporary API or message module project and then move the generated classes into your existing project.

A. Add message module classes

If adding a message module to an existing package, determine which classes must be defined. At a minimum, a message module consists of the following:

• A state class for storing data in your message module. This is often a simple POJO object with an ID property and other relevant state properties.

• A message handler class that derives from MessageProcessor. This object implements message processing logic and factory methods for module infrastructure.

• One or more message classes to be sent to the message processor by clients.

See Creating a Message Module Project for details on the classes required by message modules.

B. Add API module classes

If adding an API module to an existing packaged, determines which classes must be defined. At a minimum, an API module consists of the following:

• A state class for storing data in your API module. This is often a simple POJO object with an ID property and other relevant state properties.

• An API processor class that derives from ApiProcessor and implements endpoints for the API module’s methods.

See Creating an API Module Project for details on the classes required by API modules.

2. Register the processor in Main

In your existing module’s Main.java class, modify the implementation to the ModulePackage using either addMessageModule() or AddApiModule().

public static void main(String[] args) {
    // instantiate the module package
    ModulePackage modulePackage = new ModulePackage();
    // define the ApiModuleOptions
    ApiModuleOptions<ShoppingCart> apiModuleOptions = new ApiModuleOptionsBuilder<ShoppingCart>(ShoppingCart.class).build();
    // add the API module to the package
    ApiModule<ShoppingCart> apiModule = modulePackage.addApiModule("ShoppingCart", new ShoppingCartApiProcessor(), apiModuleOptions);
    // define the MsgModuleOptions
    MsgModuleOptions<Flight> msgModuleOptions = new MsgModuleOptionsBuilder<Flight>(Flight.class).build();
    // add the MSG module to the package
    modulePackage.addMsgModule("FlightTracker", new FlightMessageProcessor(), msgModuleOptions);
    // add parallel operations
    apiModule.addForEachOperation("removeEmpty", new ShoppingCartForEachApiProcessor(), new ParallelOperationOptionsBuilder<ShoppingCart, Void>(ShoppingCart.class).build());
    apiModule.addReduceOperation("getTotalValue", new GetTotalValue(), new ParallelOperationOptionsBuilder<ShoppingCart, Double>(ShoppingCart.class).build());
    try {
        // wait for events
        modulePackage.waitForEvents();
    } catch (ModuleRegistrationException e) {
        throw new RuntimeException(e);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

3. Add the module to scaleoutPackage.json

The scaleoutPackage.json file is a manifest used by the ScaleOut service to identify modules in the zipped package. Add the new module to the modules section of the JSON file.

{
    "cmdLineParams": "com.mycompany.Main",
    "modules": [
        {
            "moduleName": "FlightTracker",
            "runtime": "java",
            "moduleType": "msg"
        },
        {
            "moduleName": "ShoppingCart",
            "runtime": "java",
            "moduleType": "api"
        }
    ]
}

Set the “moduleType” to “msg” if adding a message module. Set it to “api” if adding an API module.

See Java Module Project Structure Overview for further details on the scaleoutPackage.json and automatic packaging for Maven and Gradle projects.