Modules

Calyxo applications are composed of modules. Modules are independent units, you may think of them as subapplications. A module is a container for actions.

When handling a request the controller will have to perform three major steps:

  1. select a module
  2. select an action inside that module and invoke it
  3. dispatch the request to another action or resource

The way modules are selected, may vary. For example, the Calyxo Control component uses one servlet per module. That way, selecting the appropriate module is left to the servlet container. This approach guarantees a high degree of independence between modules. On the other hand, Struts uses a single servlet per application, which invokes the request processor for the appropriate module.

Current Module

Once a module has been selected, we call it the current module.

The current module then selects an action and executes it. We say, "the action is invoked by the request". An action's execution results in information on how to dispatch the request. The module then dispatches to another action (optionally within another module) or to an application resource (for example, a JSP page).

It is important to understand, that the current module exists only during the lifetime of the request, that selected the module. If you, for example, point your browser directly to a JSP page, there's no current module! If, on the other hand, an action dispatches to that page, the action's module will still be the current module within the page.

Module Context

A module is represented by its context. The module context provides access to module properties and services, like

  • the module name
  • the surrounding servlet context
  • module initialization parameters
  • module scope attributes
  • the context relative path for a given action (module relative path).
  • a class loader used to load user-defined classes

The interface de.odysseus.calyxo.base.ModuleContext defines the corresponding Java type.

As you can see, a module context provides its own attribute scope, just like the servlet context does. Only, it is private to that module. Calyxo stores all its configuration information inside module scopes to prevent name clashes between modules.

In a real application, an incoming request has to be mapped to its corresponding module. That is, a context relative path gets decomposed into a module part (identifying the module) and an action path (relative to the module), which is the controller's job. As mentioned above, a module context provides the inverse mapping, answering the question: how do I access a particular action within the module from outside?

Module Support

The de.odysseus.calyxo.base.ModuleSupport class knows about the current and all the other modules in the application. There's one instance of this class per application. The various static getInstance(...) methods are used to get a reference to it. Once you got that instance, you can use the various getModuleContext(...) methods to retrieve the current module context (or another module context by name).

Module Accessors

The base.module.* accessors provided by Calyxo Base enable for easy access to modules from within JSP pages, for example

${calyxo.base.module.name}
${calyxo.base.module.attribute['foo']}
${calyxo.base.module.path['/list']}

The last example may be used to build URLs pointing to an action. However, Calyxo also provides a <base:a> tag, that clones HTML's <a> tag, but replaces the href attribute with module and action attributes.