Update Java guide, roadmap, and feature documentation with latest project status and improvements to sidebar navigation

ftomassetti · ftomassetti · commit 106d7addbd31 · 2025-11-13T17:03:43.000+01:00
diff --git a/website/docs/Guides-Java/getting-started.md b/website/docs/Guides-Java/getting-started.md
@@ -36,6 +36,12 @@ Add the following dependency to your `pom.xml`:
 </dependency>
 ```
 
+Or this to your `build.gradle.kts`:
+
+```
+implementation("io.lionweb.lionweb-java:lionweb-java-2024.1-core:${lionwebVersion}")
+```
+
 ## Usage Schema
 
 The typical usage consists in:
diff --git a/website/docs/Guides-Java/index.md b/website/docs/Guides-Java/index.md
@@ -21,8 +21,8 @@ LionWeb is a specification for model-based software engineering that provides:
 ## Features
 
 - Support for the definition nodes and languages
-- Serialization and deserialization in JSON, Protobuf, and Flatbuffers
-- Client-side implementation of the LionWeb bulk protocol, with support for delta coming soon
+- Serialization and deserialization in JSON and Protobuf
+- Client-side implementation of the LionWeb bulk protocol, with support for delta under development
 - Bidirectional conversion between LionWeb and EMF
 - Support for both 2023.1 and 2024.1 specifications
 
diff --git a/website/docs/Guides-Java/roadmap.md b/website/docs/Guides-Java/roadmap.md
@@ -6,8 +6,9 @@ sidebar_position: 3
 
 The project currently support the core specifications.
 
-We will work on implementing support for the delta protocol, as soon as it will be implemented in the LionWeb Repository.
+We released version 1.1 in the course of 2025, and we are steadily progressing on:
+- Implementing support for the Delta protocol
+- Solve any issue reported
+- Constantly optimize performance
 
-We will then proceed to review the project, performing some general maintenance and release version 1.0.
-
-Despite the version number being below 1.0, the project is mature, well tested, and used in production.
+The project is used in production and actively maintained.
diff --git a/website/docs/Introduction/features.md b/website/docs/Introduction/features.md
@@ -1,30 +1,73 @@
 ---
 title: Features
-sidebar_position: 32
+sidebar_position: 33
 ---
 
-# LionWeb Implementations
+# LionWeb Feature Matrix
+
+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.
+
+## Understanding the Symbols
+
+Throughout these tables, you'll see the following symbols:
+- ✅ **Fully Supported** - The feature is implemented and ready to use
+- 🏗️ **Under Construction** - The feature is currently being developed
+- ❓ **Status Unknown** - We need to verify the current status of this feature
+- ➖ **Not Applicable** - This feature doesn't apply to this implementation or integration
+
+## LionWeb Implementations
+
+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.
+
+The table below shows which features are available in each language implementation:
 
 | **Feature**                                         | **LW C#** | **LW Java** | **LW Kotlin** | **LW TypeScript** | **LW Python** |
 |-----------------------------------------------------|:---------:|:-----------:|:-------------:|:-----------------:|:-------------:|
 | M1 (model) de/serializer from/to LW JSON            |     ✅     |      ✅      |       ✅       |         ✅         |       ✅       |
 | M2 (language) de/serializer from/to LW JSON         |     ✅     |      ✅      |       ✅       |         ✅         |       ✅       |
+| M1 (model) de/serializer from/to LW Protobuf        |     ➖     |      ✅      |       ✅       |         ✅         |       ✅       |
+| M2 (language) de/serializer from/to LW Protobuf     |     ➖     |      ✅      |       ✅       |         ✅         |       ✅       |
 | Language agnostic (Reflective) API to CRUD LW nodes |     ✅     |      ✅      |       ✅       |         ✅         |       ✅       |
 | Language specific API to CRUD LW nodes              |     ✅     |      ✅      |       ✅       |         ✅         |       ✅       |
 | Bulk protocol Client                                |     ❓     |      ✅      |       ✅       |         ✅         |       ✅       |
-| Delta protocol Client                               |     ➖     |      🏗️      |       ➖       |         ➖         |       ➖       |
-
-
-# LionWeb Integrations
-
-| **Feature**                  | **MPS** | **EMF** |   **Freon**   | **Rascal** | **Modelix** | **LW Repository** |
-|------------------------------|:-------:|:-------:|:-------------:|:----------:|:-----------:|:-----------------:|
-| Depends on LW implementation | LW Java | LW Java | LW TypeScript |   LW Java  |      ❓      |   LW TypeScript   |
-| Export to LW M1 (model)      |    ✅    |    ✅    |       ✅       |      ✅     |      ✅      |         ➖         |
-| Export to LW M2 (language)   |    ✅    |    ✅    |       ✅       |      ❓     |      ❓      |         ➖         |
-| Import from LW M1 (model)    |    ✅    |    ✅    |       ✅       |      ✅     |      ✅      |         ➖         |
-| Import from LW M2 (language) |    ❓    |    ✅    |       ✅       |      ✅     |      ❓      |         ➖         |
-| Bulk protocol Server         |    ❓    |    ➖    |       ➖       |      ➖     |      ✅      |         ✅         |
-| Bulk protocol Client         |    ➖    |    ➖    |       ❓       |      ➖     |      ➖      |         ➖         |
-| Delta protocol Server        |    ➖    |    ➖    |       ➖       |      ➖     |      ➖      |         🏗️         |
-| Delta protocol Client        |    ➖    |    ➖    |       ➖       |      ➖     |      ➖      |         ➖         |
+| Delta protocol Client                               |     🏗     |      🏗️      |       ➖       |         🏗         |       ➖       |
+
+### Key Features Explained
+
+**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.
+
+**API Approaches**: Each implementation offers two complementary APIs:
+- **Reflective API**: Work with any LionWeb model dynamically without generated code
+- **Language-specific API**: Use strongly-typed, generated code for compile-time safety and better IDE support
+
+**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.
+
+## LionWeb Integrations
+
+| **Feature**                  | **MPS** | **EMF** |   **Freon**   | **Rascal** | **Modelix** | **LW Repository** | **Starlasu** |
+|------------------------------|:-------:|:-------:|:-------------:|:----------:|:-----------:|:-----------------:|:------------:|
+| Depends on LW implementation | LW Java | LW Java | LW TypeScript |   LW Java  |      ❓      |   LW TypeScript   | LW Java      |
+| Export to LW M1 (model)      |    ✅    |    ✅    |       ✅       |      ✅     |      ✅      |         ➖         |   ✅    |
+| Export to LW M2 (language)   |    ✅    |    ✅    |       ✅       |      ❓     |      ❓      |         ➖         |   ✅    |
+| Import from LW M1 (model)    |    ✅    |    ✅    |       ✅       |      ✅     |      ✅      |         ➖         |   ✅    |
+| Import from LW M2 (language) |    ❓    |    ✅    |       ✅       |      ✅     |      ❓      |         ➖         |   ✅    |
+| Bulk protocol Server         |    ❓    |    ➖    |       ➖       |      ➖     |      ✅      |         ✅         |   ➖    |
+| Bulk protocol Client         |    ➖    |    ➖    |       ❓       |      ➖     |      ➖      |         ➖         |   ➖    |
+| Delta protocol Server        |    ➖    |    ➖    |       ➖       |      ➖     |      ➖      |         🏗️         |   ➖    |
+| Delta protocol Client        |    ➖    |    ➖    |       ➖       |      ➖     |      ➖      |         ➖         |   ➖    |
+
+### Integration Highlights
+
+**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.
+
+**Freon**: A TypeScript-based language workbench with comprehensive LionWeb support for both models and languages.
+
+**Rascal**: A meta-programming language and toolkit with strong model import/export capabilities.
+
+**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.
+
+**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/).
+
+## Contributing
+
+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.
diff --git a/website/docs/Introduction/introduction-to-languages.md b/website/docs/Introduction/introduction-to-languages.md
@@ -1,6 +1,6 @@
 ---
 title: LionWeb Languages
-sidebar_position: 31
+sidebar_position: 32
 ---
 
 ## About LionWeb Languages
diff --git a/website/docs/Introduction/nodes.md b/website/docs/Introduction/nodes.md
@@ -1,6 +1,6 @@
 ---
 title: LionWeb Nodes
-sidebar_position: 30
+sidebar_position: 31
 ---
 
 # Overview of the LionWeb Model
diff --git a/website/docs/Introduction/why-use-lionweb.md b/website/docs/Introduction/why-use-lionweb.md
@@ -0,0 +1,29 @@
+---
+title: Why Use LionWeb?
+sidebar_position: 30
+---
+
+# LionWeb: When It Makes Sense to Use It
+
+## Interoperability Across Modeling Tools
+LionWeb is useful when multiple tools need to work with the same models. If each tool implements LionWeb support, they can interoperate at several levels:
+- exchanging models,
+- reusing existing LionWeb-compatible components.
+
+This removes the need for bespoke integrations. It’s especially relevant in domains with long toolchains and mixed vendors, like model-based systems engineering (MBSE). A practical example is enabling different SysML 2 tools to work on the same models using LionWeb.
+
+## Building Real-time Collaboration in Editors
+Because the data model and structure are standardized, and thanks to the _delta-protocol_ editors built for different purposes can work together. 
+
+This is particularly useful when different kinds of users want to use different editors or simply when multiple people are working on the same model at the same time.
+
+## Using LionWeb Server Capabilities
+LionWeb isn’t limited to file formats. The server provides features that keep expanding. For instance, upcoming support for _Derived Models_ will offer new capabilities.
+
+## Model Exchange Through Serialization
+You can use LionWeb purely as an exchange format. This is useful when constructing language-engineering pipelines. Each step of the pipeline can:
+1. read a model in LionWeb format,
+2. transform or analyze it,
+3. save the result back in LionWeb format.
+
+Subsequent steps—possibly implemented in different tools—can consume those files. Some tools might compute metrics, others generate dashboards, and others continue the transformation pipeline. This use-case is described in this article: [A Pipeline Approach to Language Migrations](https://www.infoq.com/articles/pipeline-language-migrations/).
