The first step in understanding the Niagara architecture is to grasp the concept of modules. Modules are the unit of deployment and versioning in the Niagara architecture. A module is a set of related module files having the same module name.
A module file:
Additionally, a module file has a module part name that is used by other module files to declare dependencies against it. The module part name is usually a concatenation of the module name and runtime profile (e.g. control-rt), but in a few cases is set explicitly in the module file’s manifest.
A runtime profile is used in the following ways:
Runtime profiles describe what a module file’s contents are used for, and if the contents include Java classes, which Java Runtime profiles can load them. The table below uses the module files that comprise the control module as an example:
Runtime Profile | Example Module Name | Built with JRE Version | Notes |
---|---|---|---|
rt |
control-rt |
Java 8 Compact 3 | Data model and communication: Fox, Box and Web Servlets |
ux |
control-ux |
Java 8 Compact 3 | BajaUX,HTML5,CSS,JavaScript code providing web-based user interaction |
wb |
control-wb |
Java 8 SE | Java code supporting old Workbench-based user interaction - views, field editors, etc. These JARs inject AWT dependencies at runtime if AWT is supported on the platform. They are a special case where a single jar file contains code that is compiled against Java SE but executes in a compact3 environment. Special care must be taken by developers to avoid using classes that may not be present. |
se |
control-se |
Java 8 SE | Anything that has a direct dependence upon Java SE code - database technologies, AWT, Swing, etc. |
doc |
control-doc |
N/A | Documentation. Includes no class files or other runnable content. |
Versions are specified as a series of whole numbers separated by periods, for example “1.0.34.179”. Two versions can be compared resulting in equality, less than, or greater than. This comparison is made by comparing the version numbers from left to right. If two versions are equal, except one contains more numbers, then the longer version is considered greater than the shorter version. For example:
2.0 > 1.0 2.0 > 1.8 2.0.45 > 2.0.43 1.0.24.2 > 1.0.24
Every module declares a “vendor” name and “vendorVersion”. The vendor name is a case insensitive identifier for the company who developed the module and the vendorVersion identifies the vendor’s specific version of that module.
Tridium’s vendorVersions are formatted as “major.minor.iteration.build[.patch]”:
So the vendorVersion “4.1.22.16” represents a module of iteration 22 and build 16 in Niagara release 4.1. The vendorVersion “4.1.22.16.2” is the second patch of iteration 22 and build 16 in Niagara release 4.1.
All module JAR files must include a manifest file in “meta-inf/module.xml”. The best way to examine the contents of this file is to take an example:
<?xml version="1.0" encoding="UTF-8"?>
<module
name = "control"
runtimeProfile = "rt"
vendor = "Tridium"
vendorVersion = "4.0.22.16"
description = "Niagara Control Module"
preferredSymbol = "c"
>
<moduleParts>
<modulePart name="control-wb" runtimeProfile="wb"/>
<modulePart name="control-doc" runtimeProfile="doc"/>
</moduleParts>
<dependencies>
<dependency name="baja" vendor="Tridium" vendorVersion="4.0"/>
<dependency name="bql-rt" vendor="Tridium" vendorVersion="4.0"/>
<dependency name="gx" vendor="Tridium" vendorVersion="4.0"/>
</dependencies>
<dirs>
<dir name="javax/baja/control"/>
<dir name="javax/baja/control/enum"/>
<dir name="javax/baja/control/ext"/>
<dir name="javax/baja/control/trigger"/>
<dir name="javax/baja/control/util"/>
</dirs>
<defs>
<def name="control.foo" value="something"/>
</defs>
<types>
<type name="FooBar" class="javax.baja.control.BFooBar"/>
</types>
<lexicons brand="*">
<lexicon module="bajaui" resource="fr/bajaui_fr.lexicon" language="fr"/>
</lexicons>
</module>
Looking at the root module
element the following attributes are required:
Additionally, the root module
element may have an optional modulePartName attribute which provides the module part name for the file. If omitted, the module part name will be a concatenation of the module name and the runtime profile, for example “control-rt”.
If the module is composed of more than one module file, then the manifest for the file with the lowest runtimeProfile (rt being lowest, doc being highest) must identify the other module files by including a moduleParts
element. That element contains one or more modulePart sub-elements, each of which has a mandatory runtimeProfile attribute and a mandatory name attribute which specifies the module part name (not the module name or file name!) for a sibling module file.
All modules must include a dirs
element, which contains a dir
subelement for each of the module’s content directories. Each dir
has a name attribute which contains a system-home relative file path for a directory in the module.
All module files include zero or one dependencies
element. This element contains zero or more dependency
elements which enumerate the module’s dependencies. Dependencies must be resolved by the framework before the module can be successfully used. Each dependency has one required attribute. The name attribute specifies the module part name (not the file name or module name!) for the dependent module file. The vendorVersion attribute specifies the lowest vendorVersion of the dependent module file required. It is assumed that higher versions of a module are backward compatible, thus any version greater than the one specified in a dependency is considered usable. The vendor attribute may be specified without the vendorVersion attribute, but not vice versa. Module files having the doc
runtimeProfile may have no dependencies, nor can other module files specify dependencies on them. Additionally, dependencies toward other module files are limited as described in the table below:
Target Module File's Runtime Profile | ||||||
---|---|---|---|---|---|---|
rt |
ux |
wb |
se |
doc |
||
Declaring Module File's Runtime Profile | rt |
Yes | No | No | No | No |
ux |
Yes | Yes | No | No | No | |
wb |
Yes | Yes | Yes | No | No | |
se |
Yes | Yes | Yes | Yes | No | |
doc |
No | No | No | No | No |
Modules can declare zero or more def
elements which store String name/value pairs. The defs from all modules are collapsed into a global def database by the registry.
Modules which contain concrete Niagara BObjects
also include a types
element. This element includes zero or more type
elements. Each type
element defines a mapping between a Baja type name and a Java class name. This definition is specified in the two required attributes type and class.
Modules can declare zero or one lexicons
element, which contains zero or more lexicon
elements. The lexicon has an optional brand
attribute which filters lexicon file usage based on brand. The value of this attribute may contain “*” (string) or “?” (single character) wildcards. Each lexicon will associate a resource file containing lexicon properties with a specific module. Typically modules containing lexicons will not contain other elements, but it is possible to include lexicon files in any module. Lexicon information is loaded into a global lexicon database by the registry. This data is used by the lexicon system to apply locale-specific elements (text, icons, etc.) as needed.
Copyright © 2000-2019 Tridium Inc. All rights reserved.