Baja API

What a Niagara Module Actually Contains

A Niagara module is not one jar. It is a set of jars named module-part.jar, and the part suffix is not cosmetic: it is a runtime profile that declares where the code may run and what it is allowed to depend on. A part can depend only on parts with an equal or more restricted profile, so a class placed in the wrong jar either fails to resolve at build time or produces a module that installs fine on a workstation and is simply not there on the controller.

module.xml carries the module name, vendor, vendor version and the dependency list, each dependency with a minimum vendor version. Those minimums are a real decision rather than boilerplate: set too high and the module refuses to install on stations that would have run it, set too low and it installs onto one missing an API it calls. module.palette is separate and easy to forget. It defines what Workbench shows when the palette is opened, and if it is missing or misnamed the module works normally while the palette looks empty.

• module-rt.jar: station-side code, the part that runs on a controller as well as on a Supervisor. The most restricted profile, and the right default for anything that has to run unattended.
• module-ux.jar: browser-facing code, HTML and JavaScript served to a client. Available from a station with no Workbench present.
• module-wb.jar: Workbench views, tools and wizards. Present only where Workbench is installed, so nothing station-side may depend on it.
• module-se.jar: code that needs a full Java SE runtime rather than the reduced one on a controller.
• module-doc.jar: documentation built for bajadoc. Nothing executable ships in it.

Slots, Flags and What Breaks at the Next Module Version

Slots declared in source are frozen: compiled into the type, present on every instance, addressed by name. Slots added at runtime are dynamic, stored per instance and written into the saved station database along with the component. Which kind a property is decides what happens to an existing site when a new version of the module loads.

Rename or remove a frozen property and the values already saved under the old name no longer match a declared slot. There is no exception to catch. The component comes back up on its declared defaults, so a station restarts running the module's defaults instead of the values an engineer set two years ago. Adding frozen slots is safe, since the saved config simply has nothing for them; changing a slot's type is the same problem as removing it. When a name has to change, keep the old slot, hide it, and migrate its value once the component reaches steady state.

A property that does not persist at all is usually either flagged transient, which excludes it from the saved config by design, or is being mutated in place instead of through its setter, so nothing marks the component dirty and the station saves the old value over the new one.

Flags are part of a slot's contract too, and permission flags are the ones most often misread. An action's permission requirement is enforced against the context that invokes it. Server-side code invoking with no context is not a user, so it passes checks a Workbench operator would fail. Logic that genuinely has to be restricted needs to check deliberately rather than assume the flag covers every caller.

Diagnosing a Module That Is Not Behaving

Symptoms are misleading here because several unrelated failures look identical from a wiresheet. Work from the outside in: did the module load, did the type get created, is the value in front of you current, and is the station keeping up. Answering in that order is what stops an afternoon spent rewriting code that turns out to have a trust store problem.

The failure that gets misread most often is a value that is plausible but old. A proxy point updates while something is subscribed to it. With nothing subscribed there is nothing polling, and a view that someone closed leaves the last reading sitting in place. Server-side code that reads a point without subscribing or leasing it first gets the same stale number, and from the outside it is indistinguishable from a driver that quietly stopped working.

• Application Director output, which names the module when a load, a start or a signature check fails.
• The spy pages, reached with a spy: ORD, for engine cycle timing, subscription counts and thread state.
• The log setup page under spy, which raises one module's logger level at runtime with no restart, instead of turning logging up everywhere and then reading the flood.
• The device's poll rate and tuning policy alongside the point itself, which separates "this point is not being polled" from "this value genuinely is not changing".

Why a Module Fails to Load

A module that never loads fails before any of its own code runs. The loader reads the manifest, resolves every declared dependency against what is installed on that host, and verifies the module signature; a class inside the jar is initialized only after all of that passes. That is why a dependency or trust problem presents as a module that is simply absent, with no stack trace pointing anywhere near your logic, rather than as an exception at the point of use.

Signing is a trust question, not a syntax one. A module signed with a certificate that chains to a CA already in the platform's system trust store installs without comment. A self-signed certificate has to be approved into the user trust store on each host that will run the module, which is a per-controller, per-Supervisor step somebody has to perform, and perform again when a controller is replaced.

The other common cause is a platform difference a workstation build cannot see. Controllers run a reduced Java runtime, so desktop-only APIs such as AWT and Swing, and third-party libraries that pull them in transitively, compile cleanly against a workstation JDK and then throw NoClassDefFoundError on the controller. The same shape of failure comes from station code referencing a class that lives in a wb part: it resolves in Workbench and does not exist on the controller at all. Testing on the target hardware rather than only against a Supervisor is what catches both.

When a Module Is More Than the Job Needs

A Baja module is a build, a signing step and a version commitment for the life of the station. Several requests that arrive described as module work are already covered by something that ships.

If the requirement is a nightly push of history data into a database, the RDBMS drivers already do scheduled history export and import, with the mapping done in Workbench and no jar to maintain. If it is a few hundred lines of glue that will keep changing as the site changes, a Program object compiles Java inside the station and can be edited by whoever maintains the site, with no rebuild and no signing, where the license includes it. If the equipment speaks BACnet/IP or Modbus TCP and only the register map is unusual, the stock driver plus a point map is quicker to build and far easier to hand over than a driver stack.

What pushes the work back to Baja is specific: state that has to survive a restart and be visible on a slot sheet, behavior that other components bind to as typed slots, and failure paths that have to be handled in code rather than logged and forgotten. Program objects also give you no palette entry, and they are edited in the station, which is fine until the same logic is needed on twelve of them.