How expansion works
Definitions
| Term | Definition |
|---|---|
| Expansion | Expansion is the process of generating code based on a Model. |
| Model | An abstract description of an ApplicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution.. The developer describes their desired ApplicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution. in a collection of Model Files. |
| ArtifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. | In the context of Expansion, an ArtifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. always refers to a file generated by ExpandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact.. |
| ExpanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. | An ExpanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. is a combination of mapping logic and a template that, when given an Element, generates a single ArtifactArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project.. |
| Element | An Element is a small part of the Model. ArtifactsArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project. are generated by iterating over each Element in the Model and applying all applicable ExpandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact.. |
| Feature | In the context of Expansion, a Feature is something that requires a condition to activate, and adds code to several ExpandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. to implement cross-cutting logic. |
| Composite | After the model is read, it is transformed and linked to form Composites. ExpandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. work on these Composites rather than on the raw model files. |
| Harvest | HarvestingHarvestingThe process of extracting and persisting custom code from anchors and ext directories back into source directories. collects the custom code from expanded artifactsArtifactA build or deployment result, such as a Docker container image or Java archive, produced by a software project., so it can be reinserted after the next expansion. |
Programs and modules
An NS Model is structured into Programs and Modules.
- Programs are the root of a Model. E.g. ApplicationApplicationThe overarching model container grouping all components, domain logic, and configurations for an enterprise solution..
- Modules are reusable parts of the Model. E.g. Component. A Module can be shared among multiple Programs.
Programs and modules have a type, defined in expansion-resources as data-resource. The type tells model loading and expansion where the model and expansion directories are, which technologies need to be chosen, and which layersLayerLogical separation of functionality within a single system/application, focused on code organization. can be expanded at that level. This is how the same framework expands an NS applicationNS Application (NSApplication). A pre-built software stack that provides common enterprise application functionality such as CRUD, search, authentication, and business process modeling out of the box., a project setup or a custom metamodel.
From model to expanded artifacts
The process of expanding from a model can be described in 4 steps. The first three load the model, the last one expands it.
During model loading, the expansion resourcesExpansion Resource (ExpansionResource). A reusable resource bundle containing expanders and features that provide specific application capabilities, defined in the expansion settings and added to the classpath during expansion. listed in the expansionSettings are fetched, the model files are read, and the model is converted to linked Composites. The model is also enriched: the technologies chosen for the program and its modules are added, which later decides which expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. apply.
Expansion phases
Expansion and harvest each run in a sequence of phases:
- For expansion, the phases are
initialize,before-expansion,expansion,after-expansion,overlayandafter-overlay. - For harvest, the phases are
initialize,before-harvest,harvestandafter-harvest.
ExpandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. and AdditionalExpansionSteps are attached to a specific phase and will be executed only during that phase.
For most expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact., this is the expansion phase.
Which expanders run
The expansion walks through the model: first the program, then each module, then each element inside them. For every element, the applicable expandersExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. are selected based on a number of constraints:
- Is the type of the current element the same as the element type listed on the expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact.?
- Is the current phase the correct phase for the expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact.?
- Does the layerLayerLogical separation of functionality within a single system/application, focused on code organization. type of the expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. occur in the layerLayerLogical separation of functionality within a single system/application, focused on code organization. types of the program or module?
- Does the technology of the expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. occur in the technologies chosen for the program or module?
- Is the isApplicable condition of the expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. met, and are its tags present on the element?
While processing an element, the expanderExpanderA unit of generation that combines a data tree instance (functional M1 model) with a template to generate an artifact. also receives an expansion context: information about the element's ancestors in the model, the source and expansion directories, and the layersLayerLogical separation of functionality within a single system/application, focused on code organization. that apply to it.
For the model loading steps, the expansion context and the ExpansionConfiguration in detail, see the Expanders reference.