Enhance Java aspect tooling documentation with extended validator usage and programmatic access details

Author: Yauhenikapl

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/pages/error-codes.adoc

@@ -232,50 +232,28 @@ Each error includes contextual information to help locate and resolve the issue:
 | **Shape** | The SHACL shape that detected the violation
 |===
 
-[[accessing-error-information]]
-== Accessing Error Information
-
-=== Programmatic Access
-
-When using the Java API, errors are available through the `Violation` interface:
-
-[source,java]
-----
-List<Violation> violations = validator.validateModel(aspectModel);
-for (Violation violation : violations) {
-    String errorCode = violation.errorCode();
-    String message = violation.message();
-    EvaluationContext context = violation.context();
-    List<Fix> fixes = violation.fixes();
-}
-----
-
-[[error-resolution]]
-== Error Resolution Guide
-
-
-
 [[troubleshooting]]
 == Troubleshooting
 
 === Common Issues
 
-**Error Not Listed**: If you encounter an error code not documented here, check:
-- ESMF SDK version compatibility
-- Update to the latest documentation
-- Report missing documentation via GitHub issues
+* **Error Not Listed**: If you encounter an error code not documented here, check:
+** ESMF SDK version compatibility;
+** Update to the latest documentation;
+** Report missing documentation via GitHub issues.
 
-**Inconsistent Error Messages**: Ensure you're using compatible versions of:
-- ESMF SDK
-- SAMM specification
-- Validation tools
+* **Inconsistent Error Messages**: Ensure you're using compatible versions of:
+** ESMF SDK;
+** SAMM specification;
+** Validation tools.
 
-**Performance Issues**: For large models with many errors:
-- Process errors in batches
-- Use streaming validation where available
-- Consider model restructuring
+* **Performance Issues**: For large models with many errors:
+** Process errors in batches;
+** Use streaming validation where available;
+** Consider model restructuring.
 
 === Getting Help
 
 For additional support:
-- ESMF SDK GitHub Issues: https://github.com/eclipse-esmf/esmf-sdk/issues
+
+* **ESMF SDK GitHub Issues**: https://github.com/eclipse-esmf/esmf-sdk/issues

documentation/developer-guide/modules/tooling-guide/pages/java-aspect-tooling.adoc

@@ -346,10 +346,20 @@ different structure can implement the `Violation.Visitor` Interface with a suita
 type `(String` used as an example here) and use the visitor to handle the different types of
 Violations in a type-safe way.
 
+The `AspectModelValidator` also provides the `loadModel(Supplier<AspectModel>)` method that can be used in
+conjunction with `() -> new AspectModeLoader().load(...)` to have exceptions that might be created during the
+Aspect Model loading process, for example due to model resolution failures or syntax errors in the input
+files, be turned into a `List<Violation>` that can be passed to the aforementioned violation formatters. This
+allows for custom structured handling of problems that occur during model loading.
+
+To include the model validator, use the following dependencies:
+
+include::esmf-developer-guide:ROOT:partial$esmf-aspect-model-validator-artifact.adoc[]
+
 === Custom Error Formatting
 
-In order to access validation violations in a type-safe way, implement the interface 
-`org.eclipse.esmf.aspectmodel.shacl.violation.Violation.Visitor`. This allows you to handle each 
+In order to access validation violations in a type-safe way, implement the interface
+`org.eclipse.esmf.aspectmodel.shacl.violation.Violation.Visitor`. This allows you to handle each
 violation type specifically and format error messages according to your application's requirements.
 
 ++++
@@ -369,25 +379,39 @@ include::example$CustomViolationFormatter.java[tags=imports]
 include::example$CustomViolationFormatter.java[tags=custom-formatter]
 ----
 
+=== Programmatic Access
+
+When using the Java API, errors are available through the `Violation` interface:
+
+[source,java]
+++++
+<details>
+<summary>Show used imports</summary>
+++++
+[source,java,indent=0,subs="+macros,+quotes"]
+----
+include::example$ValidateAspectModel.java[tags=imports]
+----
+++++
+</details>
+++++
+
+[source,java,indent=0,subs="+macros,+quotes"]
+----
+include::example$ValidateAspectModel.java[tags=violations]
+----
+
+
 === Error Aggregation
 
-For applications that need to process multiple violations efficiently, you can group errors by type 
+For applications that need to process multiple violations efficiently, you can group errors by type
 for batch processing:
 
 [source,java,indent=0,subs="+macros,+quotes"]
 ----
 include::example$CustomViolationFormatter.java[tags=error-aggregation]
 ----
 
-The `AspectModelValidator` also provides the `loadModel(Supplier<AspectModel>)` method that can be used in
-conjunction with `() -> new AspectModeLoader().load(...)` to have exceptions that might be created during the
-Aspect Model loading process, for example due to model resolution failures or syntax errors in the input
-files, be turned into a `List<Violation>` that can be passed to the aforementioned violation formatters. This
-allows for custom structured handling of problems that occur during model loading.
-
-To include the model validator, use the following dependencies:
-
-include::esmf-developer-guide:ROOT:partial$esmf-aspect-model-validator-artifact.adoc[]
 
 [[generating-documentation]]
 == Generating Documentation for Aspect Models