Merge branch 'main' into feature/695-extend-code-generator-setters

Author: andreas-schilling

core/esmf-aspect-model-aas-generator/src/main/java/org/eclipse/esmf/aspectmodel/aas/AspectModelAasVisitor.java

@@ -285,6 +285,10 @@ private Optional<SubmodelElement> mapText( final Property property, final Contex
       final SubmodelElement element = context.getPropertyResult();
       element.setSupplementalSemanticIds( updateGlobalReferenceWithSeeReferences( element, property ) );
 
+      if ( !property.getPayloadName().isEmpty() ) {
+         element.setIdShort( property.getPayloadName() );
+      }
+
       recursiveProperty.remove( property );
 
       return Optional.of( element );

core/esmf-aspect-model-aas-generator/src/test/java/org/eclipse/esmf/aspectmodel/aas/AspectModelAasGeneratorTest.java

@@ -360,7 +360,7 @@ void testGenerateAasxFromAspectModelWithEnumeration() throws DeserializationExce
    @EnumSource( value = TestAspect.class )
    // anonymous enumeration in test has no urn for enum values but is required for Concept
    // Description referencing
-   public void testGeneration( final TestAspect testAspect ) throws DeserializationException {
+   void testGeneration( final TestAspect testAspect ) throws DeserializationException {
       final String aasXmlString = aspectToAasXml( testAspect );
       final byte[] aasXmlInput = aasXmlString.getBytes();
 
@@ -424,6 +424,15 @@ void testGeneratedAasxFromAspectModelSemanticIdsAreGlobalReferences() throws Des
       assertThat( property.getSemanticId().getKeys().get( 0 ).getType() ).isEqualTo( KeyTypes.GLOBAL_REFERENCE );
    }
 
+   @Test
+   void testAspectWithPayloadName() throws DeserializationException {
+      final Environment environment = getAssetAdministrationShellFromAspect( TestAspect.ASPECT_WITH_PROPERTY_WITH_PAYLOAD_NAME );
+
+      final Property property = (Property) environment.getSubmodels().get( 0 ).getSubmodelElements().get( 0 );
+      assertThat( environment.getSubmodels().get( 0 ).getSubmodelElements() ).hasSize( 1 );
+      assertThat( environment.getSubmodels().get( 0 ).getSubmodelElements().get( 0 ).getIdShort() ).isEqualTo( property.getIdShort() );
+   }
+
    private void checkDataSpecificationIec61360( final Set<String> semanticIds, final Environment env ) {
       semanticIds.forEach( semanticId -> getDataSpecificationIec61360( semanticId, env ) );
    }

core/esmf-aspect-model-validator/src/main/java/org/eclipse/esmf/aspectmodel/validation/services/DetailedViolationFormatter.java

@@ -141,6 +141,9 @@ private String formatViolation( final Violation violation, final Supplier<String
             builder.append( String.format( "  - %s%n", fix.description() ) );
          }
       }
+      // Add documentation link
+      builder.append( " documentation: https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/error-codes.html"
+            + violation.errorCode().toLowerCase().replace( "_", "-" ) );
       builder.append( indent( additionalAttributesSupplier.get(), 2 ) );
       if ( violation.context() != null ) {
          builder.append( String.format( "  caused-by-shape:%n" ) );

core/esmf-aspect-model-validator/src/main/java/org/eclipse/esmf/aspectmodel/validation/services/ViolationFormatter.java

@@ -42,6 +42,9 @@ public class ViolationFormatter implements Function<List<Violation>, String>, Vi
    protected final String additionalHints;
    protected final RustLikeFormatter formatter;
 
+   private static final String ERROR_CODES_DOC_LINK = "https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/error-codes.html";
+   private static final String ERROR_CODES_DOC_STRING = "For more information, see: documentation: " + ERROR_CODES_DOC_LINK;
+
    public ViolationFormatter( final String additionalHints ) {
       this( new PlainTextFormatter(), additionalHints );
    }
@@ -84,11 +87,17 @@ public String apply( final List<Violation> violations ) {
          final List<Violation> elementViolations = entry.getValue();
          builder.append( String.format( "> %s :%n", textFormatter.formatName( elementName ) ) );
          for ( final Violation violation : elementViolations ) {
+            // Include error code in the violation message
+            final String errorCode = violation.errorCode();
+            final String enhancedMessage = String.format( "[%s] %s", errorCode, violation.message() );
             builder.append( indent( violation.accept( this ), 2 ) ).append( System.lineSeparator() );
             for ( final Fix possibleFix : violation.fixes() ) {
                builder.append( "  > Possible fix: " )
                      .append( possibleFix.description() );
             }
+            // Add documentation link
+            builder.append( String.format( ERROR_CODES_DOC_STRING + "#%s%n",
+                  errorCode.toLowerCase().replace( "_", "-" ) ) );
             builder.append( System.lineSeparator() );
          }
          builder.append( System.lineSeparator() );
@@ -98,10 +107,20 @@ public String apply( final List<Violation> violations ) {
          if ( violation instanceof final ProcessingViolation processingViolation ) {
             builder.append( processingViolation.accept( this ) );
          } else if ( violation.violationSpecificMessage() == null || violation.violationSpecificMessage().equals( violation.message() ) ) {
-            builder.append( String.format( "> %s%n", violation.message() ) );
+            final String errorCode = violation.errorCode();
+            final String enhancedMessage = String.format( "[%s] %s", errorCode, violation.message() );
+            builder.append( String.format( "> %s%n", enhancedMessage ) );
+            // Add documentation link for context-free violations
+            builder.append( ERROR_CODES_DOC_STRING
+                  + errorCode.toLowerCase().replace( "_", "-" ) );
          } else {
-            builder.append( String.format( "> %s: %n", violation.message() ) );
+            final String errorCode = violation.errorCode();
+            final String enhancedMessage = String.format( "[%s] %s", errorCode, violation.message() );
+            builder.append( String.format( "> %s: %n", enhancedMessage ) );
             builder.append( indent( violation.accept( this ), 2 ) ).append( System.lineSeparator() );
+            // Add documentation link
+            builder.append( ERROR_CODES_DOC_STRING
+                  + errorCode.toLowerCase().replace( "_", "-" ) );
          }
          builder.append( System.lineSeparator() );
       }
@@ -111,7 +130,9 @@ public String apply( final List<Violation> violations ) {
 
    @Override
    public String visit( final Violation violation ) {
-      return formatter.constructDetailedMessage( violation.highlight(), violation.message(), violation.context().element().getModel() );
+      final String errorCode = violation.errorCode();
+      final String enhancedMessage = String.format( "[%s] %s", errorCode, violation.message() );
+      return formatter.constructDetailedMessage( violation.highlight(), enhancedMessage, violation.context().element().getModel() );
    }
 
    @Override

documentation/developer-guide/modules/tooling-guide/examples/CustomViolationFormatter.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025 Robert Bosch Manufacturing Solutions GmbH
+ *
+ * See the AUTHORS file(s) distributed with this work for additional
+ * information regarding authorship.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+package examples;
+
+// tag::imports[]
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import org.eclipse.esmf.aspectmodel.shacl.violation.DatatypeViolation;
+import org.eclipse.esmf.aspectmodel.shacl.violation.MaxCountViolation;
+import org.eclipse.esmf.aspectmodel.shacl.violation.Violation;
+// end::imports[]
+
+public class CustomViolationFormatter implements Violation.Visitor<String> {
+
+   // tag::custom-formatter[]
+   // Implement other visitor methods for different violation types
+   @Override
+   public String visit(Violation violation) {
+      // Generic fallback for unhandled violation types
+      return String.format("Validation error: %s", violation.message());
+   }
+   // end::custom-formatter[]
+
+   // tag::error-aggregation[]
+   public void aggregateErrors(List<Violation> violations) {
+       // Group violations by error code for batch processing
+       Map<String, List<Violation>> errorsByCode = violations.stream()
+           .collect(Collectors.groupingBy(Violation::errorCode));
+
+       // Handle each error type separately
+       List<Violation> dataTypeErrors = errorsByCode.get("ERR_TYPE");
+       List<Violation> cardinalityErrors = errorsByCode.get("ERR_MAX_COUNT");
+       
+       // Process each error type with specific handling logic
+       if (dataTypeErrors != null && !dataTypeErrors.isEmpty()) {
+           System.out.println("Found " + dataTypeErrors.size() + " data type errors");
+           // Handle data type errors...
+       }
+       
+       if (cardinalityErrors != null && !cardinalityErrors.isEmpty()) {
+           System.out.println("Found " + cardinalityErrors.size() + " cardinality errors");
+           // Handle cardinality errors...
+       }
+   }
+   // end::error-aggregation[]
+}

documentation/developer-guide/modules/tooling-guide/examples/ValidateAspectModel.java

@@ -18,6 +18,8 @@
 import java.util.List;
 
 import org.eclipse.esmf.aspectmodel.loader.AspectModelLoader;
+import org.eclipse.esmf.aspectmodel.shacl.fix.Fix;
+import org.eclipse.esmf.aspectmodel.shacl.violation.EvaluationContext;
 import org.eclipse.esmf.aspectmodel.shacl.violation.Violation;
 import org.eclipse.esmf.aspectmodel.validation.services.AspectModelValidator;
 import org.eclipse.esmf.aspectmodel.validation.services.DetailedViolationFormatter;
@@ -38,11 +40,20 @@ public void validate() {
                   new File( "aspect-models/org.eclipse.esmf.examples.movement/1.0.0/Movement.ttl" ) );
       // tag::validate[]
 
+      // tag::violations[]
       final List<Violation> violations = new AspectModelValidator().validateModel( aspectModel );
       if ( violations.isEmpty() ) {
          // Aspect Model is valid!
          return;
+      } else {
+         for (Violation violation : violations) {
+            String errorCode = violation.errorCode();
+            String message = violation.message();
+            EvaluationContext context = violation.context();
+            List<Fix> fixes = violation.fixes();
+         }
       }
+      // end::violations[]
 
       final String validationReport = new ViolationFormatter().apply( violations ); // <1>
       final String detailedReport = new DetailedViolationFormatter().apply( violations );

documentation/developer-guide/modules/tooling-guide/nav.adoc

@@ -1,4 +1,6 @@
 * xref:samm-cli.adoc[SAMM CLI]
 * xref:java-aspect-tooling.adoc[Java APIs for Aspect Models]
 * xref:maven-plugin.adoc[Maven Plugin]
+* xref:error-codes.adoc[Error Codes and Validation Results]
+* xref:best-practices.adoc[Best Practices]
 * xref:bamm-migration.adoc[Migration from BAMM]

documentation/developer-guide/modules/tooling-guide/pages/best-practices.adoc

@@ -0,0 +1,27 @@
+:page-partial:
+
+[[best-practices]]
+= Best Practices
+
+This guide provides best practices for developing Aspect Models and handling validation errors effectively.
+
+[[analyzing-modeling-errors]]
+== Analyzing Modeling Errors
+
+When working with ESMF SDK validation results, follow these practices to efficiently identify and resolve modeling issues.
+
+=== Model Development
+
+1. **Validate Early**: Run validation frequently during model development
+2. **Use Detailed Output**: Enable detailed error reporting for comprehensive feedback
+3. **Address Errors Systematically**: Start with meta-violations before fixing constraint violations
+4. **Test Edge Cases**: Verify models with boundary values and optional properties
+
+=== Error Handling
+
+1. **Programmatic Handling**: Use the visitor pattern for type-safe error handling
+2. **User-Friendly Messages**: Transform technical errors into user-friendly guidance
+3. **Logging**: Log error codes and context for troubleshooting
+4. **Documentation**: Link to error code documentation in error messages where appropriate
+
+