In this short entry I just wanted to lay out a few new diagrams that explain the lifecycle of ColdBox modules.  As always, all our documentation reflects these changes as well.  This might help some of you developers getting ready to win that ColdBox Modules contest and get some cash and beer!

Module Service

The beauty of ColdBox Modules is that you have an internal module service that you can tap to in order to dynamically interact with the ColdBox Modules. This service is available by talking to the main ColdBox controller and calling its getModuleService() method:

// get module service from handlers, plugins, layouts, interceptors or views.
ms = controller.getModuleService();

// You can also inject it via our autowire DSL
property name="moduleService" inject="coldbox:moduleService";

Module Lifecycle

However, before we start reviewing the module service methods let's review how modules get loaded in a ColdBox application. Below is a simple bullet point of what happens in your application when it starts up and you can also look at the diagram above:

1. ColdBox main application and configuration loads
2. ColdBox Cache, Logging and WireBox are created
3. Module Service calls on registerAllModules() to read all the modules in the modules locations (with include/excludes) and start registering their configurations one by one. If the module had parent settings, interception points, datasoures or webservices, these are registered here.
4. All main application interceptors are loaded and configured
5. ColdBox is marked as initialized
6. Module service calls on activateAllModules() so it begins activating only the registered modules one by one. This registers the module's SES URL Mappings, model objects, etc
7. afterConfigurationLoad interceptors are fired
8. ColdBox aspects such as i18n, javaloader, ColdSpring/LightWire factories are loaded
9. afterAspectsLoad interceptors are fired

The most common methods that you can use to control the modules in your application are the following:

• reloadAll() : Reload all modules in the application. This clears out all module settings, re-registers from disk, re-configures them and activates them
• reload(module) : Target a module reload by name
• unloadAll() : Unload all modules
• unload(module) : Target a module unload by name
• registerAllModules() : Registers all module configurations
• registerModule(module) : Target a module configuration registration
• activateAllModules() : Activate all registered modules
• activateModule(module) : Target activate a module that has been registered already
• getLoadedModules() : Get an array of loaded module names
• rebuildModuleRegistry() : Rescan all the module lcoations for newly installed modules and rebuild the registry so these modules can be registered and activated.
• registerAndActivateModule(module) : Register and Activate a new module

With these methods you can get creative and target the reloading, unloading or loading of specific modules. These methods really open the opportunity to build an abstraction API where you can install modules in your application on the fly and then register and activate them. You can also do the inverse and deactivate modules in a running application.

Module Registration

Below you can see a diagram of what happens when modules get registered:

Module Activation

Below you can see a diagram of what happens when modules get activated right after registration:

Module Unloading

Below you can see a diagram of what happens when modules get deactivated and unloaded

Loading New Modules

If you want to load a new module in your application that you have just installed you need to do a series of steps.

1. Drop the module in any of the module locations defined
2. Call rebuildModuleRegistry() on the module service to get all new modules scanned
3. Call registermodule(moduleName) to register the new module
4. Call activateModule(moduleName) to activate the new module

Or you can skip the last two steps with one method: registerAndActivateModule(moduleName)