Skip to content

Commit fffa7fb

Browse files
ftomassettiftomassetti
authored
Merge pull request #11 from LionWeb-io/refresh-use-cases
Adding some pages
2 parents e4ac260 + 66b7217 commit fffa7fb

File tree

11 files changed

+318
-26
lines changed

11 files changed

+318
-26
lines changed

‎website/docs/Guides-Java/comparison.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Nodes Comparison
3+
sidebar_position: 46
4+
---
5+
6+
# Nodes Comparison
7+
8+
The lionweb-java project provides comprehensive model comparison capabilities through the `io.lionweb.utils.ModelComparator` class.
9+
10+
The `ModelComparator` enables detailed comparison of models, nodes, and classifier instances to identify structural and semantic differences between them.
11+
12+
## Comparison Methods
13+
14+
The `ModelComparator` provides several overloaded `compare()` methods for different types of elements:
15+
16+
- **Node Comparison**: Compare two `Node` objects
17+
- **AnnotationInstance Comparison**: Compare two `AnnotationInstance` objects
18+
- **ClassifierInstance Comparison**: Compare two `ClassifierInstance` objects (polymorphic)
19+
20+
## Static Equivalence Checking
21+
22+
Convenience methods for quick equivalence checks:
23+
24+
- `areEquivalent(ClassifierInstance<?> a, ClassifierInstance<?> b)`: Check if two classifier instances are equivalent
25+
- `areEquivalent(List<A> as, List<B> bs)`: Check if two lists of classifier instances are equivalent
26+
27+
## ComparisonResult
28+
29+
The `ComparisonResult` class encapsulates the outcome of a comparison operation:
30+
31+
### Key Features
32+
33+
- **Difference Tracking**: Maintains a list of all detected differences
34+
- **Equivalence Check**: Provides `areEquivalent()` method that returns `true` when no differences exist
35+
- **Detailed Reporting**: Contains methods to mark specific types of differences
36+
37+
### Types of Differences Detected
38+
39+
1. **ID Differences**: Different node IDs
40+
2. **Concept Differences**: Different concept/classifier assignments
41+
3. **Property Value Differences**: Different values for properties
42+
4. **Containment Differences**: Different numbers or values of child nodes
43+
5. **Reference Differences**: Different reference targets or resolve information
44+
6. **Annotation Differences**: Different numbers or values of annotations
45+
7. **Incompatibility**: When instances cannot be compared (different types)
46+
47+
## Comparison Aspects
48+
49+
The `ModelComparator` performs deep comparison across multiple dimensions:
50+
51+
### 1. **Properties**
52+
Compares all property values defined by the classifier, identifying any discrepancies in property data.
53+
54+
### 2. **References**
55+
Compares reference values including:
56+
- Number of references
57+
- Referenced node IDs
58+
- Resolve information for each reference
59+
60+
### 3. **Containments**
61+
Compares child nodes including:
62+
- Number of children in each containment
63+
- Recursive comparison of child node structures
64+
65+
### 4. **Annotations**
66+
Compares annotations including:
67+
- Number of annotations
68+
- Annotation IDs and structures
69+
70+
### 5. **Structure**
71+
Validates structural consistency including:
72+
- Parent-child relationships
73+
- Concept/classifier assignments
74+
- Node hierarchy
75+
76+
## Use Cases
77+
78+
- **Testing**: Verify that model transformations produce expected results
79+
- **Validation**: Ensure model consistency across operations
80+
- **Debugging**: Identify unexpected changes in models
81+
- **Serialization/Deserialization**: Verify round-trip integrity
82+
- **Version Control**: Compare model versions to detect changes
83+
84+
## Context Information
85+
86+
All differences are reported with contextual information including:
87+
- Location in the model hierarchy
88+
- Node IDs involved
89+
- Specific feature or property names
90+
- Index positions for list elements

‎website/docs/Guides-Java/getting-started.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,12 @@ Add the following dependency to your `pom.xml`:
3636
</dependency>
3737
```
3838

39+
Or this to your `build.gradle.kts`:
40+
41+
```
42+
implementation("io.lionweb.lionweb-java:lionweb-java-2024.1-core:${lionwebVersion}")
43+
```
44+
3945
## Usage Schema
4046

4147
The typical usage consists in:

‎website/docs/Guides-Java/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,8 @@ LionWeb is a specification for model-based software engineering that provides:
2121
## Features
2222

2323
- Support for the definition nodes and languages
24-
- Serialization and deserialization in JSON, Protobuf, and Flatbuffers
25-
- Client-side implementation of the LionWeb bulk protocol, with support for delta coming soon
24+
- Serialization and deserialization in JSON and Protobuf
25+
- Client-side implementation of the LionWeb bulk protocol, with support for delta under development
2626
- Bidirectional conversion between LionWeb and EMF
2727
- Support for both 2023.1 and 2024.1 specifications
2828

‎website/docs/Guides-Java/roadmap.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,9 @@ sidebar_position: 3
66

77
The project currently support the core specifications.
88

9-
We will work on implementing support for the delta protocol, as soon as it will be implemented in the LionWeb Repository.
9+
We released version 1.1 in the course of 2025, and we are steadily progressing on:
10+
- Implementing support for the Delta protocol
11+
- Solve any issue reported
12+
- Constantly optimize performance
1013

11-
We will then proceed to review the project, performing some general maintenance and release version 1.0.
12-
13-
Despite the version number being below 1.0, the project is mature, well tested, and used in production.
14+
The project is used in production and actively maintained.

‎website/docs/Guides-Java/validating.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Validation
3+
sidebar_position: 45
4+
---
5+
6+
# Validation
7+
8+
The lionweb-java project includes a comprehensive validation framework located in the `io.lionweb.utils` package. Here's an overview of all validation-related features:
9+
10+
## Introduction
11+
12+
### **ValidationResult**
13+
Represents the outcome of validation operations, containing information about any issues found during validation.
14+
15+
### **Issue**
16+
Represents individual validation problems or concerns detected during the validation process.
17+
18+
Each issue has an _Issue Severity_. The severity levels are error, warning, and info.
19+
20+
## Specific Validators
21+
22+
### **ChunkValidator**
23+
Validates `SerializationChunks` of data, ensuring they meet structural and semantic requirements.
24+
25+
### **NodeTreeValidator**
26+
Validates the structure and integrity of node trees within the model hierarchy.
27+
28+
### **PartitionChunkValidator**
29+
Specialized validator for validating `SerializationChunks` supposed to contain a single partition.
30+
31+
### **LanguageValidator**
32+
Validates language definitions, checking that language structures conform to expected patterns and rules.
33+
34+
## Validation Utilities
35+
36+
Notable mention for **CommonChecks**: it provides a collection of common validation checks that can be reused across different validation scenarios.

‎website/docs/Introduction/annotations.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Annotations
3+
sidebar_position: 34
4+
---
5+
6+
# Annotations
7+
8+
Annotations provide a generic mechanism for extending languages without modifying them. They are useful for:
9+
10+
- cross-cutting concerns that apply across many languages or many kinds of nodes.
11+
- extending a language we do not own
12+
13+
An annotation definition can be reused with instances of different languages, even if the original language designer never anticipated that extension. This is a key aspect that provides extensibility.
14+
15+
## Generic and Reusable Extensions
16+
A common example for using annotation is adding comments. You can define a comment annotation once and apply it to any node of any language. Tools that understand this annotation can use it; tools that don’t need it are free to ignore it. This enables optional, non-intrusive extensions.
17+
18+
This example shows also how annotations are sort of metadata: they are relevant to some users and can be ignored by others. Let's imagine a node with a comment:
19+
20+
- A process generating documentation for a partition may benefit from the comment.
21+
- At the same time a process executing the partition may ignore the annotation containing the comment, as it is irrelevant for it
22+
23+
Annotations may also be constrained. For instance, you could define a “synonym” annotation that applies only to nodes that provide a name (i.e., implementing the interface `INamed`, part of _LionCore Builtins_). The annotation system supports this level of restriction.
24+
25+
Of course we may also have annotations restricted to specific concepts. Let's imagine we are using a valuable language provided by someone else. We may want to add an extra field to a a certain concept, however we may not control the language and we may not change freely if other tools we use rely on the language being defined in a certain way. We can still add an annotation that, let's say, can be applied to instances of the concept `Car` and could specify a `Color` field. We may then have an editor that is aware of such annotation and can display the node using the color specified in the annotation.
26+
27+
## How Annotations Relate to Nodes
28+
Annotations behave much like ordinary nodes:
29+
- both are classifier instances,
30+
- both carry structured data.
31+
32+
The difference is in their attachment:
33+
- regular nodes participate in containment trees,
34+
- annotations are not children of the nodes they describe,
35+
- instead, they act as metadata associated with nodes.
36+
37+
This avoids mixing cross-cutting information with the primary structure of the model.
38+
39+
Note also that annotations can be attached to nodes but not to other annotations.
40+
41+
Annotations may contain nodes.

‎website/docs/Introduction/features.md‎

Lines changed: 61 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,73 @@
11
---
22
title: Features
3-
sidebar_position: 32
3+
sidebar_position: 35
44
---
55

6-
# LionWeb Implementations
6+
# LionWeb Feature Matrix
7+
8+
This page provides a comprehensive overview of the features available across different LionWeb implementations and integrations. Whether you're looking to serialize models, work with language definitions, or connect to a repository server, this matrix will help you choose the right implementation for your needs.
9+
10+
## Understanding the Symbols
11+
12+
Throughout these tables, you'll see the following symbols:
13+
- ✅ **Fully Supported** - The feature is implemented and ready to use
14+
- 🏗️ **Under Construction** - The feature is currently being developed
15+
- ❓ **Status Unknown** - We need to verify the current status of this feature
16+
- ➖ **Not Applicable** - This feature doesn't apply to this implementation or integration
17+
18+
## LionWeb Implementations
19+
20+
LionWeb implementations are available in five programming languages, each providing core functionality for working with LionWeb models and languages. These libraries form the foundation for building language workbenches, model transformations, and other language engineering tools.
21+
22+
The table below shows which features are available in each language implementation:
723

824
| **Feature** | **LW C#** | **LW Java** | **LW Kotlin** | **LW TypeScript** | **LW Python** |
925
|-----------------------------------------------------|:---------:|:-----------:|:-------------:|:-----------------:|:-------------:|
1026
| M1 (model) de/serializer from/to LW JSON | ✅ | ✅ | ✅ | ✅ | ✅ |
1127
| M2 (language) de/serializer from/to LW JSON | ✅ | ✅ | ✅ | ✅ | ✅ |
28+
| M1 (model) de/serializer from/to LW Protobuf | ➖ | ✅ | ✅ | ✅ | ✅ |
29+
| M2 (language) de/serializer from/to LW Protobuf | ➖ | ✅ | ✅ | ✅ | ✅ |
1230
| Language agnostic (Reflective) API to CRUD LW nodes | ✅ | ✅ | ✅ | ✅ | ✅ |
1331
| Language specific API to CRUD LW nodes | ✅ | ✅ | ✅ | ✅ | ✅ |
1432
| Bulk protocol Client | ❓ | ✅ | ✅ | ✅ | ✅ |
15-
| Delta protocol Client | ➖ | 🏗️ | ➖ | ➖ | ➖ |
16-
17-
18-
# LionWeb Integrations
19-
20-
| **Feature** | **MPS** | **EMF** | **Freon** | **Rascal** | **Modelix** | **LW Repository** |
21-
|------------------------------|:-------:|:-------:|:-------------:|:----------:|:-----------:|:-----------------:|
22-
| Depends on LW implementation | LW Java | LW Java | LW TypeScript | LW Java | ❓ | LW TypeScript |
23-
| Export to LW M1 (model) | ✅ | ✅ | ✅ | ✅ | ✅ | ➖ |
24-
| Export to LW M2 (language) | ✅ | ✅ | ✅ | ❓ | ❓ | ➖ |
25-
| Import from LW M1 (model) | ✅ | ✅ | ✅ | ✅ | ✅ | ➖ |
26-
| Import from LW M2 (language) | ❓ | ✅ | ✅ | ✅ | ❓ | ➖ |
27-
| Bulk protocol Server | ❓ | ➖ | ➖ | ➖ | ✅ | ✅ |
28-
| Bulk protocol Client | ➖ | ➖ | ❓ | ➖ | ➖ | ➖ |
29-
| Delta protocol Server | ➖ | ➖ | ➖ | ➖ | ➖ | 🏗️ |
30-
| Delta protocol Client | ➖ | ➖ | ➖ | ➖ | ➖ | ➖ |
33+
| Delta protocol Client | 🏗 | 🏗️ | ➖ | 🏗 | ➖ |
34+
35+
### Key Features Explained
36+
37+
**M1 and M2 Serialization**: All implementations support both model (M1) and language (M2) serialization to and from LionWeb JSON format and [Protobuf](https://protobuf.dev/) format, enabling seamless data exchange between different tools and platforms.
38+
39+
**API Approaches**: Each implementation offers two complementary APIs:
40+
- **Reflective API**: Work with any LionWeb model dynamically without generated code
41+
- **Language-specific API**: Use strongly-typed, generated code for compile-time safety and better IDE support
42+
43+
**Protocol Support**: The Bulk protocol allows efficient retrieval and storage of large model partitions. The Delta protocol, currently under development for C#, Typescript, and Java, will enable incremental synchronization of model changes.
44+
45+
## LionWeb Integrations
46+
47+
| **Feature** | **MPS** | **EMF** | **Freon** | **Rascal** | **Modelix** | **LW Repository** | **Starlasu** |
48+
|------------------------------|:-------:|:-------:|:-------------:|:----------:|:-----------:|:-----------------:|:------------:|
49+
| Depends on LW implementation | LW Java | LW Java | LW TypeScript | LW Java | ❓ | LW TypeScript | LW Java |
50+
| Export to LW M1 (model) | ✅ | ✅ | ✅ | ✅ | ✅ | ➖ | ✅ |
51+
| Export to LW M2 (language) | ✅ | ✅ | ✅ | ❓ | ❓ | ➖ | ✅ |
52+
| Import from LW M1 (model) | ✅ | ✅ | ✅ | ✅ | ✅ | ➖ | ✅ |
53+
| Import from LW M2 (language) | ❓ | ✅ | ✅ | ✅ | ❓ | ➖ | ✅ |
54+
| Bulk protocol Server | ❓ | ➖ | ➖ | ➖ | ✅ | ✅ | ➖ |
55+
| Bulk protocol Client | ➖ | ➖ | ❓ | ➖ | ➖ | ➖ | ➖ |
56+
| Delta protocol Server | ➖ | ➖ | ➖ | ➖ | ➖ | 🏗️ | ➖ |
57+
| Delta protocol Client | ➖ | ➖ | ➖ | ➖ | ➖ | ➖ | ➖ |
58+
59+
### Integration Highlights
60+
61+
**MPS and EMF**: The most mature integrations, supporting both model and language import/export. These make it possible to exchange data between JetBrains MPS and Eclipse Modeling Framework projects.
62+
63+
**Freon**: A TypeScript-based language workbench with comprehensive LionWeb support for both models and languages.
64+
65+
**Rascal**: A meta-programming language and toolkit with strong model import/export capabilities.
66+
67+
**Modelix and LW Repository**: These act as server-side repositories, implementing the Bulk protocol to store and serve LionWeb models. The LW Repository is actively developing Delta protocol support for real-time collaborative editing scenarios.
68+
69+
**Starlasu**: This is a family of frameworks for processing textual languages (such as SQL, RPG, COBOL, and many others). More at [Starlasu](https://starlasu.strumenta.com/).
70+
71+
## Contributing
72+
73+
Notice something missing or incorrect? The LionWeb project is community-driven, and we welcome contributions. If you've implemented a feature or know the status of one marked with ❓, please let us know or submit a pull request to update this documentation.

‎website/docs/Introduction/introduction-to-languages.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: LionWeb Languages
3-
sidebar_position: 31
3+
sidebar_position: 32
44
---
55

66
## About LionWeb Languages

‎website/docs/Introduction/nodes.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: LionWeb Nodes
3-
sidebar_position: 30
3+
sidebar_position: 31
44
---
55

66
# Overview of the LionWeb Model

‎website/docs/Introduction/where-do-my-nodes-live.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: Where LionWeb Nodes and Languages Live?
3+
sidebar_position: 33
4+
---
5+
6+
# Where LionWeb Nodes and Languages Live?
7+
8+
## In-Memory Only
9+
Nodes can exist purely in memory. This is typical for short-lived operations:
10+
- a batch process creates some nodes,
11+
- performs analysis or transformation,
12+
- produces an artifact (e.g., a report),
13+
- discards the nodes when the operation ends.
14+
15+
In this scenario, nodes are regular in-memory objects created through any LionWeb library, without persistence.
16+
17+
## Persistent Repository
18+
The most common setup is to store nodes in a persistent repository.
19+
A repository:
20+
- keeps nodes and partitions over time,
21+
- offers services for accessing, querying, and modifying data,
22+
- acts as the authoritative storage for tools that rely on shared models.
23+
24+
This is the scenario most LionWeb-based systems eventually adopt.
25+
26+
## Files on Disk (JSON or Protobuf)
27+
Nodes can also be persisted as files:
28+
- JSON is supported by all LionWeb libraries.
29+
- Protobuf is supported by most libraries.
30+
31+
You can:
32+
- store each partition in its own file, or
33+
- use the archive format (a ZIP container holding multiple encoded partitions).
34+
35+
The archive format is currently available in the Java and Python implementations.
36+
It groups multiple partitions and languages into a single compressed file containing protobuf-encoded data.
37+
38+
## Storing Languages
39+
Languages are nodes too. All storage mechanisms described above apply to languages the same way they apply to regular nodes.
40+
41+
Some considerations:
42+
- A specialized editor might embed a language definition directly.
43+
- A language might be shipped as a file alongside the tool.
44+
- A language may also be constructed programmatically when the editor starts.
45+
46+
These choices depend on how dynamic the language needs to be and how the tool is distributed.

0 commit comments

Comments
 (0)