Module Development
Mango provides a modular architecture that allows you to extend the platform with custom Java modules. A module can add new data sources, REST API endpoints, database tables, scheduled jobs, AngularJS frontend pages, and more. Modules are packaged as ZIP files and installed into Mango like any other plugin.
This tutorial series walks through building a complete custom module from scratch, using an "Energy Metering" example that stores device data in a custom database table and exposes it through REST API endpoints with an AngularJS frontend.
In This Section
-
Overview -- Introduction to custom module development, what you can build, and a roadmap of the tutorial series covering environment setup through frontend integration.
-
Setup -- Setting up your development environment with JDK, Maven, IntelliJ IDEA, and the required Mango repositories. Includes creating the project directory structure and Maven configuration.
-
Configuration -- Configuring the module with translation files, module properties, SQL table definitions for H2 and MySQL, the table definition Java class, and the database schema definition.
-
Creating Your First Endpoint -- Building the full endpoint stack: audit events, Value Objects (VO), Data Access Objects (DAO), services, REST models, model mappings, and the REST controller with GET and POST endpoints.
-
Testing -- Writing automated API tests using Mocha and the mango-module-tools test helper. Covers creating test fixtures, making REST requests, and running tests against a live Mango instance.
-
RQL Queries -- Adding Resource Query Language (RQL) support to your custom endpoint so clients can filter, sort, and paginate results.
-
Adding an AngularJS Frontend -- Creating an AngularJS frontend for your module with webpack bundling, page components, menu registration, and the module definition class.
Module Architecture
A typical Mango module follows this layered architecture:
| Layer | Class Pattern | Purpose |
|---|---|---|
| Value Object (VO) | DeviceVO | Java representation of your domain entity |
| Data Access Object (DAO) | DeviceDao | Database operations (CRUD, queries) |
| Service | DeviceService | Business logic, validation, permission checks |
| REST Model | DeviceModel | JSON serialization/deserialization |
| Model Mapping | DeviceModelMapping | Converts between VO and REST Model |
| REST Controller | DeviceRestController | HTTP endpoint definitions |
| Table Definition | DevicesTableDefinition | Database column definitions using jOOQ |
| Schema Definition | EnergyMonitoringSchemaDefinition | Database migration management |
Prerequisites
- JDK (latest stable version)
- Maven (latest stable version)
- IntelliJ IDEA (Community or Ultimate edition)
- A running Mango installation for testing
- Cloned copies of
ma-core-public,ma-dashboards, andma-modules-publicrepositories