Merge pull request #15 from MiriamGaus/main

Udpdate Readme, dependancies and the test/example structure

Author: SundermannC

.gitignore

@@ -160,3 +160,9 @@ buildNumber.properties
 .classpath
 
 # End of https://www.toptal.com/developers/gitignore/api/maven,intellij,java
+
+# local changes
+/src/main/java/uvl
+/.vscode
+/src/main/java/de/vill/main/modified_files/*
+!/src/main/java/de/vill/main/modified_files/.gitkeep

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "src/test/resources"]
+	path = src/test/resources
+	url = https://github.com/Universal-Variability-Language/uvl-models

README.md

@@ -1,98 +1,156 @@
-# UVL - Universal Variability Language Java Metamodel
-This is a small default library used to manipulate UVL metamodels in JAVA
+# UVL - Universal Variability Language Java Feature Model Metamodel
 
-## The Language
+This is a small default library used to manipulate UVL metamodels in JAVA. It uses the [UVL-Grammar](https://github.com/Universal-Variability-Language/) to parse the a given metamodel. If parsed the model can be modified in JAVA. It is possible to also convert the models to different levels.
 
-On a high level, each feature model in UVL consists of five optional separated elements:
+**How to use UVL** can be found in this paper
+[![DOI](https://img.shields.io/badge/DOI-10.1016%2Fj.jss.2024.112326-blue)](https://doi.org/10.1016/j.jss.2024.112326)
 
-1. **A list of used language levels**
-The model can use different concepts which are part of language levels. These levels can either be enumerated with the `include` keyword or be implicit.
-2. **A namespace which can be used for references in other models**
-3. **A list of imports that can be used to reference external feature models**
-The models are referenced by their file name and can be given an alias using a Java import like syntax.
-External models in subdirectories can be referenced like this: subdir.filename as fn
-4. **The tree hierarchy consisting of: features, group types, and attributes whose relations are specified using nesting (indentation)**
-Groups may have an arbitrary number of features as child nodes. A feature can also have a feature cardinality.
-Attributes consist of a key-value pair whose key is always a string and its value may be a boolean, number, string, a list attributes, a vector, or a constraint. If the value is a constraint the key must be `constraint`. If the value is a list of constraints the key must be `constraints`
-5. **Cross-tree constraints**
-Cross-tree constraints may be arbitrary propositional formulas with the following symbols: => (implies), <=> (iff), & (and), | (or), ! (not), or brackets. Through the usage of language levels cross-tree constraints can also contain equations (<,>,==) which consist of expressions (+,-,*,/) with numbers or numerical feature attributes as literals and aggregate functions (avg, sum).
+## ✨ Key Features
 
-The following snippet shows a simplified server architecture in UVL. We provide more examples (e.g., to show the composition mechanism) in [https://github.com/Universal-Variability-Language/uvl-models/tree/main/Feature_Models](https://github.com/Universal-Variability-Language/uvl-models/tree/main/Feature_Models).
+- full support of UVL-Syntax (namespaces, feature hierarchies and constraints)
+- convert between different language levels
+- direct access to feature model components like features, groups and attributes
 
+## ⚙️ Setup
+
+To clone this repository **with all submodules**, use:
+
+```bash
+git clone --recurse-submodules https://github.com/Universal-Variability-Language/java-fm-metamodel.git
 ```
-namespace Server
-
-features
-  Server {abstract}
-    mandatory
-      FileSystem
-        or // with cardinality: [1..*]
-          NTFS
-          APFS
-          EXT4
-      OperatingSystem {abstract}
-        alternative
-          Windows
-          macOS
-          Debian
-    optional
-      Logging	{
-      default,
-      log_level "warn" // Feature Attribute
-    }
-
-constraints
-  Windows => NTFS
-  macOS => APFS
+
+If you have already cloned the repository **without** submodules, you can initialize and update them afterwards with:
+
+```bash
+git submodule update --init --recursive
 ```
 
-In this snippet, we can recognize the following elements:
-* The feature `Server` is abstract (i.e., corresponds to no implementation artifact.
-* Each `Server` requires a `FileSystem`and an `OperatingSystem` denoted by the *mandatory* group
-* The `Server` may have `Logging` denoted by the *optional* group
-* A `FileSystem` requires at least one type of `NTFS`, `APFS`, and `Ext4` denoted by the *or* group
-* An `OperatingSystem` has exactly one type of `Windows`, `macOS`, and `Debian`denoted by the *alternative* group
-* `Logging` has the feature attribute `log_level` attached which is set to "warn"
-* `Windows` requires `NTFS` denoted by the first cross-tree constraint
-* `macOS`requires `APFS`
+This ensures that all required submodules (e.g., test resources) are available and the project will build and test correctly
+
+## 💡 Usage
+
+### 📦 Getting Started
 
-## Building a jar
+First, **clone this repository** to your local machine as explained in `⚙️ Setup`.
+To use the Java-fm-metamodel, make sure you are in the project directory before running any further commands. Build the project with [Maven](https://maven.apache.org/):
 
-The library is a maven project and can therefore be build with maven. To update the generated parser classes and create a jar with all necessary dependencies, use:
+```bash
+mvn clean compile
 ```
-mvn clean compile assembly:single
+
+This will compile all sources and ensure all dependencies (including submodules) are available.  
+Now you can execute code for manipulating UVL feature models as shown in the `Examples` below
+
+### 🧩 Using as a Maven Dependency
+
+You can also use the Java-fm-metamodel as a dependency in your own Maven project.  
+Add the following to your `pom.xml`:
+
+```xml
+<dependency>
+  <groupId>io.github.universal-variability-language</groupId>
+  <artifactId>fm-metamodel</artifactId>
+  <version>1.1</version>
+</dependency>
 ```
 
-The `target/uvl-parser-1.0-SNAPSHOT-jar-with-dependencies.jar` includes all dependencies.
+Make sure that the version matches the latest release.
 
-## Usage from Java
-The class `de.vill.main.UVLModelFactory` exposes the static method `parse(String)` which will return an instance of a `de.vill.model.FeatureModel` class. If there is something wrong, a `de.vill.exception.ParseError` is thrown. The parser tries to parse the whole model, even if there are errors. If there are multiple errors, a `de.vill.exception.ParseErrorList` is returned which contains all errors that occurred.
-A model can be printed with the `toString()` method of the `de.vill.model.FeatureModel` object.
-The following snippet shows a minimal example to read and write UVL models using the jar. More usage examples that also show how to use the acquired UVLModel object can be found in [src/main/java/de/vill/main/Example.java](https://github.com/Universal-Variability-Language/uvl-parser2.0/blob/main/src/main/java/de/vill/main/Example.java)
+---
+
+Now you can use the classes from this library in your own Java code!
+
+## Examples
+
+Some usage examples that show how to use the acquired UVLModel object can be found in [src/main/java/de/vill/main/Example.java](https://github.com/Universal-Variability-Language/java-fm-metamodel/blob/main/src/main/java/de/vill/main/Example.java)
+
+### Parsing
 
 ```Java
-// Read
+// First option:
+UVLModelFactory uvlModelFactory = new UVLModelFactory();
+FeatureModel featureModel = uvlModelFactory.parse(Paths.get("path/to/your/file.uvl"));
+
+// Second option:
 Path filePath = Paths.get(pathAsString);
 String content = new String(Files.readAllBytes(filePath));
 UVLModelFactory uvlModelFactory = new UVLModelFactory();
 FeatureModel featureModel = uvlModelFactory.parse(content);
+```
+
+The class `de.vill.main.UVLModelFactory` exposes the static method `parse(String)` which will return an instance of a `de.vill.model.FeatureModel` class. If there is something wrong, a `de.vill.exception.ParseError` is thrown. The parser tries to parse the whole model, even if there are errors. If there are multiple errors, a `de.vill.exception.ParseErrorList` is returned which contains all errors that occurred.
 
+### Modifying
 
+```Java
+Feature feature = featureModel.getFeatureMap().get(featureName);
+if (feature != null) {
+  Attribute<?> attribute = feature.getAttributes().get(attributeName);
+  if (attribute != null) {
+    System.out.println("Name of the feature" + feature.getFeatureName());
+    System.out.println("Name of the attribute" + attribute.getName());
+  }
+}
+
+// Conversion
+ConvertTypeLevel converter = new ConvertTypeLevel();
+converter.convertFeatureModel(featureModel, convertedModel);
+```
+
+### Writing into a file
+
+```Java
 // Write
 String uvlModel = featureModel.toString();
 Path filePath = Paths.get(featureModel.getNamespace() + ".uvl");
 Files.write(filePath, uvlModel.getBytes());
-``` 
+```
+
+A model can be printed with the `toString()` method of the `de.vill.model.FeatureModel` object.
+
+## 🧪 Running Tests
+
+The Java-fm-metamodel can be tested by running:
+
+```bash
+mvn test
+```
+
+## 📖 Citation
+
+If you use UVL in your research, please cite:
+
+```bibtex
+@article{UVL2024,
+  title     = {UVL: Feature modelling with the Universal Variability Language},
+  journal   = {Journal of Systems and Software},
+  volume    = {225},
+  pages     = {112326},
+  year      = {2025},
+  issn      = {0164-1212},
+  doi       = {https://doi.org/10.1016/j.jss.2024.112326},
+  url       = {https://www.sciencedirect.com/science/article/pii/S0164121224003704},
+  author    = {David Benavides and Chico Sundermann and Kevin Feichtinger and José A. Galindo and Rick Rabiser and Thomas Thüm},
+  keywords  = {Feature model, Software product lines, Variability}
+}
+```
 
 ## Links
+
 UVL models:
-* https://github.com/Universal-Variability-Language/uvl-models
+
+- https://github.com/Universal-Variability-Language/uvl-models
+
+UVL parser:
+
+- https://github.com/Universal-Variability-Language/uvl-parser
 
 Other parsers:
-* https://github.com/Universal-Variability-Language/uvl-parser *deprecated, Initial UVL Parser, based on Clojure and instaparse* **UVL-Parser**
-* https://github.com/diverso-lab/uvl-diverso/ *Under development, Antlr4 Parser* **Diverso Lab**
 
-Usage of UVL:
-* https://github.com/FeatureIDE/FeatureIDE *Feature modelling tool* 
+- https://github.com/Universal-Variability-Language/uvl-parser _deprecated, Initial UVL Parser, based on Clojure and instaparse_ **UVL-Parser**
+- https://github.com/diverso-lab/uvl-diverso/ _Under development, Antlr4 Parser_ **Diverso Lab**
 
+Usage of UVL:
 
+- https://github.com/FeatureIDE/FeatureIDE _Feature modelling tool_
+- https://github.com/SECPS/TraVarT _Transformation Tool for Variability Artifacts_

pom.xml

@@ -49,7 +49,7 @@
         <developerConnection>scm:git:git@github.com:Universal-Variability-Language/java-fm-metamodel.git</developerConnection>
         <url>https://github.com/Universal-Variability-Language/java-fm-metamodel</url>
       <tag>HEAD</tag>
-  </scm>
+    </scm>
 
     <distributionManagement>
         <snapshotRepository>
@@ -63,9 +63,9 @@
     </distributionManagement>
 
     <properties>
-        <antlr4.version>4.13.1</antlr4.version>
-        <maven.compiler.source>11</maven.compiler.source>
-        <maven.compiler.target>11</maven.compiler.target>
+        <antlr4.version>4.13.2</antlr4.version>
+        <maven.compiler.source>21</maven.compiler.source>
+        <maven.compiler.target>21</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
     </properties>
@@ -74,7 +74,7 @@
         <dependency>
             <groupId>org.antlr</groupId>
             <artifactId>antlr4-runtime</artifactId>
-            <version>4.13.1</version>
+            <version>${antlr4.version}</version>
         </dependency>
         <dependency>
             <groupId>io.github.universal-variability-language</groupId>
@@ -84,13 +84,13 @@
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter</artifactId>
-            <version>5.8.2</version>
+            <version>5.13.1</version>
             <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>com.google.guava</groupId>
             <artifactId>guava</artifactId>
-            <version>31.0.1-jre</version>
+            <version>33.4.8-jre</version>
         </dependency>
     </dependencies>
 
@@ -99,7 +99,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>
-                <version>2.22.0</version>
+                <version>3.5.3</version>
             </plugin>
             <plugin>
                 <artifactId>maven-assembly-plugin</artifactId>
@@ -117,7 +117,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.8.1</version>
+                <version>3.14.0</version>
                 <configuration>
                     <source>${maven.compiler.source}</source>
                     <target>${maven.compiler.target}</target>
@@ -127,7 +127,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-gpg-plugin</artifactId>
-                <version>1.5</version>
+                <version>3.2.7</version>
                 <executions>
                     <execution>
                         <id>sign-artifacts</id>
@@ -142,7 +142,7 @@
             <plugin>
                 <groupId>org.sonatype.plugins</groupId>
                 <artifactId>nexus-staging-maven-plugin</artifactId>
-                <version>1.6.7</version>
+                <version>1.7.0</version>
                 <extensions>true</extensions>
                 <configuration>
                     <serverId>ossrh</serverId>
@@ -154,7 +154,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-source-plugin</artifactId>
-                <version>3.2.1</version>
+                <version>3.3.1</version>
                 <executions>
                     <execution>
                         <id>attach-sources</id>
@@ -167,7 +167,7 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
-                <version>3.2.0</version>
+                <version>3.11.2</version>
                 <executions>
                     <execution>
                         <id>attach-javadocs</id>
@@ -180,4 +180,4 @@
         </plugins>
     </build>
 
-</project>
+</project>

src/main/java/de/vill/conversion/ConvertAggregateFunction.java

@@ -56,7 +56,6 @@ private void searchAggregateFunctionInExpression(Expression expression) {
 
     private void replaceAggregateFunctionInExpression(Expression parentExpression, AggregateFunctionExpression aggregateFunctionExpression) {
         Feature rootFeature;
-        Expression aggregateFunctionReplacement;
         if (aggregateFunctionExpression.getRootFeature() == null) {
             rootFeature = rootFeatureModel.getRootFeature();
         } else {
@@ -74,7 +73,6 @@ private void replaceAggregateFunctionInExpression(Expression parentExpression, A
 
     private void replaceAggregateFunctionInExpressionConstraint(ExpressionConstraint parentExpression, AggregateFunctionExpression aggregateFunctionExpression) {
         Feature rootFeature;
-        Expression aggregateFunctionReplacement;
         if (aggregateFunctionExpression.getRootFeature() == null) {
             rootFeature = rootFeatureModel.getRootFeature();
         } else {
@@ -155,7 +153,6 @@ private void removeAggregateFunctionFromAttributes(Feature feature) {
             }
         }
         if (attributeConstraintList != null && attributeConstraintList.getValue() instanceof List<?>) {
-            List<Object> newConstraintList = new LinkedList<>();
             for (Object constraint : (List<?>) attributeConstraintList.getValue()) {
                 if (constraint instanceof Constraint) {
                     searchAggregateFunctionInConstraint((Constraint) constraint);

src/main/java/de/vill/conversion/ConvertSMTLevel.java

@@ -3,8 +3,6 @@
 import com.google.common.collect.Sets;
 import de.vill.model.*;
 import de.vill.model.constraint.*;
-import de.vill.model.expression.AggregateFunctionExpression;
-import de.vill.model.expression.BinaryExpression;
 import de.vill.model.expression.Expression;
 import de.vill.model.expression.LiteralExpression;