From 7465cd0c17664d17c2352b08ad5f014134c5e8c2 Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Mon, 29 Dec 2025 02:08:39 -0500 Subject: [PATCH 1/3] feat(schemagen): add complete Javadoc coverage Add Javadoc documentation to all public/protected methods and create package-info.java files for all packages in the schemagen module. - Document 35 source files with method-level Javadoc - Add 7 package-info.java files with package descriptions - Achieves 0 Checkstyle MissingJavadocMethod violations --- PRDs/20251229-javadoc-coverage/PRD.md | 133 +++++++++++++ .../implementation-plan.md | 180 ++++++++++++++++++ .../schemagen/AbstractGenerationState.java | 58 ++++++ .../schemagen/FlagInstanceFilter.java | 30 +++ .../schemagen/IGenerationState.java | 54 ++++++ .../metaschema/schemagen/IInlineStrategy.java | 32 ++++ .../schemagen/ISchemaGenerator.java | 41 ++++ .../metaschema/schemagen/ModuleIndex.java | 136 +++++++++++++ .../schemagen/SchemaGenerationException.java | 31 +++ .../datatype/AbstractDatatypeManager.java | 13 ++ .../schemagen/datatype/IDatatypeManager.java | 15 ++ .../schemagen/datatype/package-info.java | 9 +- .../schemagen/json/JsonSchemaGenerator.java | 20 ++ .../json/impl/IJsonGenerationState.java | 40 ++++ .../json/impl/JsonGenerationState.java | 57 ++++++ .../schemagen/json/impl/JsonSchemaHelper.java | 141 ++++++++++++++ .../schemagen/json/impl/package-info.java | 8 + .../schemagen/json/package-info.java | 8 +- .../metaschema/schemagen/package-info.java | 20 +- .../schemagen/xml/XmlDatatypeManager.java | 16 ++ .../schemagen/xml/XmlSchemaGenerator.java | 40 ++++ .../xml/impl/AbstractDatatypeContent.java | 15 ++ .../xml/impl/AbstractXmlDatatypeProvider.java | 26 +++ .../AbstractXmlMarkupDatatypeProvider.java | 11 ++ .../xml/impl/CompositeDatatypeProvider.java | 17 ++ .../xml/impl/DocumentationGenerator.java | 60 ++++++ .../schemagen/xml/impl/IDatatypeProvider.java | 25 +++ .../xml/impl/JDom2DatatypeContent.java | 21 ++ .../xml/impl/JDom2XmlSchemaLoader.java | 47 +++++ .../xml/impl/XmlGenerationState.java | 175 +++++++++++++++++ .../XmlProseCompositDatatypeProvider.java | 12 ++ .../schemagen/xml/impl/package-info.java | 8 + .../schematype/AbstractXmlComplexType.java | 35 ++++ .../schematype/AbstractXmlSimpleType.java | 19 ++ .../xml/impl/schematype/AbstractXmlType.java | 12 ++ .../xml/impl/schematype/IXmlComplexType.java | 13 ++ .../xml/impl/schematype/IXmlSimpleType.java | 12 ++ .../XmlComplexTypeAssemblyDefinition.java | 81 ++++++++ .../XmlComplexTypeFieldDefinition.java | 17 ++ .../XmlSimpleTypeDataTypeReference.java | 16 ++ .../XmlSimpleTypeDataTypeRestriction.java | 36 ++++ .../impl/schematype/XmlSimpleTypeUnion.java | 22 +++ .../xml/impl/schematype/package-info.java | 7 +- .../schemagen/xml/package-info.java | 7 +- 44 files changed, 1769 insertions(+), 7 deletions(-) create mode 100644 PRDs/20251229-javadoc-coverage/PRD.md create mode 100644 PRDs/20251229-javadoc-coverage/implementation-plan.md diff --git a/PRDs/20251229-javadoc-coverage/PRD.md b/PRDs/20251229-javadoc-coverage/PRD.md new file mode 100644 index 000000000..8e414a22e --- /dev/null +++ b/PRDs/20251229-javadoc-coverage/PRD.md @@ -0,0 +1,133 @@ +# PRD: Full Javadoc Coverage + +## Document Information + +| Field | Value | +|-------|-------| +| **PRD ID** | JAVADOC-COVERAGE | +| **Status** | Approved | +| **Author** | David Waltermire | +| **Created** | 2025-12-29 | +| **Last Updated** | 2025-12-29 | + +--- + +## 1. Overview + +### 1.1 Problem Statement + +The metaschema-java project has a goal of full Javadoc coverage for all public and protected members. Currently, there are significant gaps in Javadoc coverage across multiple modules, resulting in: +- 337 `MissingJavadocMethod` Checkstyle warnings +- ~185 Javadoc "no comment" warnings + +These gaps affect code maintainability, API usability, and generated documentation quality. + +### 1.2 Goals + +1. Achieve 100% Javadoc coverage on all public/protected methods +2. Add package-level documentation where missing +3. Ensure all Javadoc follows the project's style guide +4. Eliminate all Javadoc-related Checkstyle warnings + +### 1.3 Non-Goals + +- Modifying generated code (binding classes, ANTLR output) +- Adding Javadoc to test classes +- Adding Javadoc to private methods +- Changing code behavior or structure + +### 1.4 Success Metrics + +| Metric | Current | Target | +|--------|---------|--------| +| MissingJavadocMethod warnings | 337 | 0 | +| Javadoc "no comment" warnings | ~185 | 0 | +| Build with `-PCI -Prelease` | Pass with warnings | Pass without Javadoc warnings | + +--- + +## 2. Issue Breakdown by Module + +### 2.1 schemagen Module + +| Metric | Count | +|--------|-------| +| Files affected | 36 | +| MissingJavadocMethod | 154 | + +This module is the most isolated and a good starting point. + +### 2.2 databind Module + +| Metric | Count | +|--------|-------| +| Files affected | 64 | +| MissingJavadocMethod | 176 | +| Package-info warnings | ~99 | + +This is the largest module with the most issues. + +### 2.3 metaschema-maven-plugin Module + +| Metric | Count | +|--------|-------| +| MissingJavadocMethod | 7 | + +Small number of issues, can be combined with another PR. + +--- + +## 3. Implementation Strategy + +### 3.1 PR Approach + +Given the volume of changes (100+ files), split into module-focused PRs: + +| PR | Module | Est. Files | Est. Methods | +|----|--------|-----------|--------------| +| 1 | schemagen | 36 | 154 | +| 2 | databind | 64 | 176 | +| 3 | maven-plugin | ~5 | 7 | + +### 3.2 Javadoc Guidelines + +Follow the project's [Javadoc style guide](../../docs/javadoc-style-guide.md): + +1. **First sentence**: Brief summary ending with period +2. **@param tags**: Document all parameters +3. **@return tags**: Document non-void return values +4. **@throws tags**: Document declared exceptions +5. **@Override methods**: Use `{@inheritDoc}` only if adding implementation notes + +### 3.3 Package Documentation + +For missing package-info.java documentation: +- Add brief package description +- Document package purpose and key classes +- Cross-reference related packages + +--- + +## 4. Verification + +After each PR, run: + +```bash +mvn clean install -PCI -Prelease +``` + +Verify: +- All tests pass +- No new Javadoc warnings for the module +- Checkstyle passes without Javadoc violations + +--- + +## 5. Exclusions + +The following are excluded from Javadoc requirements: + +1. **Generated code**: `target/generated-sources/`, binding classes +2. **Test classes**: All files in `src/test/` +3. **@Override methods**: Unless adding implementation notes +4. **Private members**: Only public/protected require Javadoc diff --git a/PRDs/20251229-javadoc-coverage/implementation-plan.md b/PRDs/20251229-javadoc-coverage/implementation-plan.md new file mode 100644 index 000000000..fae09eb31 --- /dev/null +++ b/PRDs/20251229-javadoc-coverage/implementation-plan.md @@ -0,0 +1,180 @@ +# Implementation Plan: Full Javadoc Coverage + +This document details the implementation for achieving full Javadoc coverage. + +--- + +## Prerequisites + +- Build the project: `mvn install -DskipTests` +- Review [Javadoc style guide](../../docs/javadoc-style-guide.md) + +--- + +## Phase 1: schemagen Module + +### PR 1: Add Javadoc to schemagen Module + +| Attribute | Value | +|-----------|-------| +| **Files Changed** | ~35 | +| **Methods to Document** | 154 | +| **Risk Level** | Low | +| **Dependencies** | None | +| **Target Branch** | develop | +| **Status** | Pending | + +#### Files to Modify + +| Package | Files | +|---------|-------| +| `schemagen` | `AbstractGenerationState.java`, `FlagInstanceFilter.java`, `IGenerationState.java`, `IInlineStrategy.java`, `ISchemaGenerator.java`, `ModuleIndex.java`, `SchemaGenerationException.java` | +| `schemagen.datatype` | `AbstractDatatypeManager.java`, `IDatatypeManager.java` | +| `schemagen.json` | `JsonSchemaGenerator.java` | +| `schemagen.json.impl` | `IJsonGenerationState.java`, `JsonGenerationState.java`, `JsonSchemaHelper.java` | +| `schemagen.xml` | `XmlDatatypeManager.java`, `XmlSchemaGenerator.java` | +| `schemagen.xml.impl` | `AbstractDatatypeContent.java`, `AbstractXmlDatatypeProvider.java`, `AbstractXmlMarkupDatatypeProvider.java`, `CompositeDatatypeProvider.java`, `DocumentationGenerator.java`, `IDatatypeProvider.java`, `JDom2DatatypeContent.java`, `JDom2XmlSchemaLoader.java`, `XmlGenerationState.java`, `XmlProseCompositDatatypeProvider.java` | +| `schemagen.xml.impl.schematype` | `AbstractXmlComplexType.java`, `AbstractXmlSimpleType.java`, `AbstractXmlType.java`, `IXmlComplexType.java`, `IXmlSimpleType.java`, `XmlComplexTypeAssemblyDefinition.java`, `XmlComplexTypeFieldDefinition.java`, `XmlSimpleTypeDataTypeReference.java`, `XmlSimpleTypeDataTypeRestriction.java`, `XmlSimpleTypeUnion.java` | + +#### Implementation Approach + +1. Start with interfaces (define the API contract) +2. Move to abstract classes (document template methods) +3. Finish with concrete implementations + +#### Acceptance Criteria + +- [ ] All public/protected methods have Javadoc +- [ ] All @param tags document parameters +- [ ] All @return tags document return values +- [ ] All @throws tags document exceptions +- [ ] Checkstyle passes: `mvn -pl schemagen checkstyle:check` +- [ ] Build succeeds: `mvn -pl schemagen install` +- [ ] Full build passes: `mvn clean install -PCI -Prelease` + +--- + +## Phase 2: databind Module + +### PR 2: Add Javadoc to databind Module (Part 1 - Core) + +| Attribute | Value | +|-----------|-------| +| **Files Changed** | ~30 | +| **Risk Level** | Low | +| **Dependencies** | None | +| **Target Branch** | develop | +| **Status** | Pending | + +#### Packages to Address + +- `databind` (root package) +- `databind.codegen` +- `databind.codegen.impl` +- `databind.codegen.typeinfo` +- `databind.codegen.typeinfo.def` + +### PR 3: Add Javadoc to databind Module (Part 2 - IO) + +| Attribute | Value | +|-----------|-------| +| **Files Changed** | ~15 | +| **Risk Level** | Low | +| **Dependencies** | PR 2 | +| **Target Branch** | develop | +| **Status** | Pending | + +#### Packages to Address + +- `databind.io` +- `databind.io.json` +- `databind.io.xml` + +### PR 4: Add Javadoc to databind Module (Part 3 - Model) + +| Attribute | Value | +|-----------|-------| +| **Files Changed** | ~20 | +| **Risk Level** | Low | +| **Dependencies** | PR 3 | +| **Target Branch** | develop | +| **Status** | Pending | + +#### Packages to Address + +- `databind.model` +- `databind.model.annotations` +- `databind.model.impl` +- `databind.model.info` +- `databind.model.metaschema` +- `databind.model.metaschema.impl` +- `databind.metapath.function` + +--- + +## Phase 3: Maven Plugin + +### PR 5: Add Javadoc to metaschema-maven-plugin + +| Attribute | Value | +|-----------|-------| +| **Files Changed** | ~5 | +| **Methods to Document** | 7 | +| **Risk Level** | Low | +| **Dependencies** | None | +| **Target Branch** | develop | +| **Status** | Pending | + +#### Acceptance Criteria + +- [ ] All public/protected methods have Javadoc +- [ ] Checkstyle passes: `mvn -pl metaschema-maven-plugin checkstyle:check` +- [ ] Build succeeds: `mvn clean install -PCI -Prelease` + +--- + +## Verification Commands + +```bash +# Check specific module +mvn -pl checkstyle:check + +# Run Javadoc to find issues +mvn -pl javadoc:javadoc + +# Full CI build +mvn clean install -PCI -Prelease + +# Count remaining warnings +grep -c "MissingJavadocMethod" build-output.txt +``` + +--- + +## PR Summary Table + +| PR | Module | Est. Files | Status | +|----|--------|-----------|--------| +| 1 | schemagen | 35 | Pending | +| 2 | databind (core) | 30 | Pending | +| 3 | databind (io) | 15 | Pending | +| 4 | databind (model) | 20 | Pending | +| 5 | maven-plugin | 5 | Pending | + +**Total PRs**: 5 +**Total Files Changed**: ~105 + +--- + +## Notes + +### Generated Code Exclusions + +The following are generated and excluded from Javadoc requirements: +- `databind/.../config/binding/` - Bootstrap bindings +- `databind/.../model/metaschema/binding/` - Bootstrap bindings +- `target/generated-sources/` - All generated code + +### Package-info Files + +Some package-info.java files have "no comment" warnings but are in generated packages. Only source package-info files need documentation. diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/AbstractGenerationState.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/AbstractGenerationState.java index 21309911c..238ffd8ec 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/AbstractGenerationState.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/AbstractGenerationState.java @@ -24,6 +24,18 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Provides a common base implementation for schema generation state management. + *

+ * This abstract class maintains the context required during schema generation, + * including the module being processed, the output writer, datatype management, + * and inlining strategy. + * + * @param + * the type of writer used for schema output + * @param + * the type of datatype manager used for type name resolution + */ public abstract class AbstractGenerationState implements IGenerationState { @NonNull @@ -38,6 +50,18 @@ public abstract class AbstractGenerationState values; + /** + * Construct a new allowed value collection. + * + * @param closed + * {@code true} if only the specified values are allowed, {@code false} + * if other values are also permitted + * @param values + * the list of allowed values + */ public AllowedValueCollection(boolean closed, @NonNull List values) { this.closed = closed; this.values = CollectionUtil.unmodifiableList(new ArrayList<>(values)); } + /** + * Determine if the allowed value set is closed. + * + * @return {@code true} if only the specified values are allowed, {@code false} + * if other values are also permitted + */ public boolean isClosed() { return closed; } + /** + * Get the list of allowed values. + * + * @return an unmodifiable list of allowed values + */ @NonNull public List getValues() { return values; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/FlagInstanceFilter.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/FlagInstanceFilter.java index 2ac53b7a3..a2a9aeca9 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/FlagInstanceFilter.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/FlagInstanceFilter.java @@ -14,11 +14,27 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A utility class for filtering flag instances during schema generation. + *

+ * This class provides methods to exclude specific flag instances (such as JSON + * key flags or JSON value key flags) from collections before processing. + */ public final class FlagInstanceFilter { private FlagInstanceFilter() { // disable construction } + /** + * Filters flag instances by excluding the specified JSON key flag. + * + * @param flags + * the collection of flag instances to filter + * @param jsonKeyFlag + * the flag instance used as a JSON key to exclude, or {@code null} if + * no filtering is needed + * @return a collection containing all flags except the JSON key flag + */ @NonNull public static Collection filterFlags( @NonNull Collection flags, @@ -32,6 +48,20 @@ public static Collection filterFlags( return applyFilter(flags, filter); } + /** + * Filters flag instances by excluding both the JSON key flag and JSON value key + * flag. + * + * @param flags + * the collection of flag instances to filter + * @param jsonKeyFlag + * the flag instance used as a JSON key to exclude, or {@code null} if + * no JSON key filtering is needed + * @param jsonValueKeyFlag + * the flag instance used as a JSON value key to exclude, or + * {@code null} if no JSON value key filtering is needed + * @return a collection containing all flags except the excluded ones + */ @NonNull public static Collection filterFlags( @NonNull Collection flags, diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/IGenerationState.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/IGenerationState.java index 7fb83de70..33345e81a 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/IGenerationState.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/IGenerationState.java @@ -16,25 +16,79 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Represents the state information used during schema generation. + * + * @param + * the type of writer used for schema output + */ public interface IGenerationState { + /** + * Get the Metaschema module being processed for schema generation. + * + * @return the module + */ @NonNull IModule getModule(); + /** + * Get the writer used for schema output. + * + * @return the writer instance + */ @NonNull WRITER getWriter(); + /** + * Get the collection of root assembly definitions exported by the module. + * + * @return the root assembly definitions + */ @NonNull default Collection getRootDefinitions() { return getModule().getExportedRootAssemblyDefinitions(); } + /** + * Determine if the provided definition should be inlined in the generated + * schema. + * + * @param definition + * the definition to check + * @return {@code true} if the definition should be inlined, {@code false} + * otherwise + */ boolean isInline(@NonNull IDefinition definition); + /** + * Flush any buffered content to the underlying writer. + * + * @throws IOException + * if an I/O error occurs while flushing + */ void flushWriter() throws IOException; + /** + * Generate a type name for the provided definition with an optional suffix. + * + * @param definition + * the definition to generate a type name for + * @param suffix + * an optional suffix to append to the type name, or {@code null} if no + * suffix is needed + * @return the generated type name + */ @NonNull String getTypeNameForDefinition(@NonNull IDefinition definition, @Nullable String suffix); + /** + * Convert a text string to camel case by splitting on punctuation and + * capitalizing each segment. + * + * @param text + * the text to convert + * @return the camel case representation of the text + */ @NonNull static CharSequence toCamelCase(String text) { StringBuilder builder = new StringBuilder(); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/IInlineStrategy.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/IInlineStrategy.java index 81c35d9d3..f105c7415 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/IInlineStrategy.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/IInlineStrategy.java @@ -10,8 +10,15 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A strategy for determining whether a definition should be inlined in the + * generated schema or referenced as a separate type definition. + */ @FunctionalInterface public interface IInlineStrategy { + /** + * A strategy that never inlines any definition. + */ @NonNull IInlineStrategy NONE_INLINE = new IInlineStrategy() { @Override @@ -22,6 +29,10 @@ public boolean isInline( } }; + /** + * A strategy that inlines definitions based on their + * {@link IDefinition#isInline()} property. + */ @NonNull IInlineStrategy DEFINED_AS_INLINE = new IInlineStrategy() { @Override @@ -32,9 +43,19 @@ public boolean isInline( } }; + /** + * A strategy that inlines definitions unless they are used in a choice group. + */ @NonNull IInlineStrategy CHOICE_NOT_INLINE = new ChoiceNotInlineStrategy(); + /** + * Create a new inline strategy based on the provided configuration. + * + * @param configuration + * the schema generation configuration + * @return the appropriate inline strategy based on the configuration settings + */ @NonNull static IInlineStrategy newInlineStrategy(@NonNull IConfiguration> configuration) { IInlineStrategy retval; @@ -50,6 +71,17 @@ static IInlineStrategy newInlineStrategy(@NonNull IConfiguration> configuration); + /** + * Generate a schema for the provided module and write it to the specified file + * path. + * + * @param module + * the Metaschema module to generate the schema for + * @param destination + * the file path to write the schema to + * @param asFormat + * the schema format to generate + * @param configuration + * the schema generation configuration + * @throws IOException + * if an I/O error occurs while writing the schema + */ static void generateSchema( @NonNull IModule module, @NonNull Path destination, @@ -60,6 +78,24 @@ static void generateSchema( } } + /** + * Generate a schema for the provided module and write it to the specified + * writer. + *

+ * The writer is not closed by this method, as the caller is responsible for + * managing its lifecycle. + * + * @param module + * the Metaschema module to generate the schema for + * @param writer + * the writer to output the schema to + * @param asFormat + * the schema format to generate + * @param configuration + * the schema generation configuration + * @throws IOException + * if an I/O error occurs while writing the schema + */ static void generateSchema( @NonNull IModule module, @NonNull Writer writer, @@ -93,6 +129,11 @@ enum SchemaFormat { this.schemaGenerator = schemaGenerator; } + /** + * Get the schema generator implementation for this format. + * + * @return the schema generator + */ @NonNull public ISchemaGenerator getSchemaGenerator() { return schemaGenerator; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/ModuleIndex.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/ModuleIndex.java index 2ac4d9437..66fcb18cb 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/ModuleIndex.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/ModuleIndex.java @@ -29,11 +29,28 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Indexes definitions from a Metaschema module for use in schema generation. + *

+ * This class maintains an ordered index of all definitions that are reachable + * from root assembly definitions, tracking their reference counts, inline + * status, and other usage patterns relevant to schema generation. + */ public class ModuleIndex { // needs to be ordered @SuppressWarnings("PMD.UseConcurrentHashMap") private final Map index = new LinkedHashMap<>(); + /** + * Creates an index of all definitions reachable from the module's root assembly + * definitions. + * + * @param module + * the Metaschema module to index + * @param inlineStrategy + * the strategy for determining which definitions should be inlined + * @return a new module index containing entries for all reachable definitions + */ @NonNull public static ModuleIndex indexDefinitions(@NonNull IModule module, @NonNull IInlineStrategy inlineStrategy) { Collection definitions = module.getExportedRootAssemblyDefinitions(); @@ -53,10 +70,28 @@ public static ModuleIndex indexDefinitions(@NonNull IModule module, @NonNull IIn return index; } + /** + * Checks if an entry exists in this index for the specified definition. + * + * @param definition + * the definition to check + * @return {@code true} if an entry exists for the definition, {@code false} + * otherwise + */ public boolean hasEntry(@NonNull IDefinition definition) { return index.containsKey(definition); } + /** + * Retrieves or creates the entry for the specified definition. + *

+ * If no entry exists for the definition, a new entry is created and added to + * the index. + * + * @param definition + * the definition to get an entry for + * @return the existing or newly created entry for the definition + */ @NonNull public DefinitionEntry getEntry(@NonNull IDefinition definition) { return ObjectUtils.notNull(index.computeIfAbsent( @@ -64,6 +99,12 @@ public DefinitionEntry getEntry(@NonNull IDefinition definition) { k -> new ModuleIndex.DefinitionEntry(ObjectUtils.notNull(k)))); } + /** + * Retrieves all definition entries in this index. + * + * @return an unmodifiable collection of all definition entries, in insertion + * order + */ @NonNull public Collection getDefinitions() { return ObjectUtils.notNull(index.values()); @@ -173,6 +214,12 @@ private static boolean isChoiceSibling(@NonNull INamedInstance instance) { } } + /** + * Represents an entry in the module index for a single definition. + *

+ * Each entry tracks usage information about a definition including its + * references, inline status, and how it is used within choice groups. + */ public static class DefinitionEntry { @NonNull private final IDefinition definition; @@ -182,71 +229,154 @@ public static class DefinitionEntry { private final AtomicBoolean usedAsChoice = new AtomicBoolean(); // false private final AtomicBoolean choiceSibling = new AtomicBoolean(); // false + /** + * Constructs a new definition entry for the specified definition. + * + * @param definition + * the definition this entry represents + */ public DefinitionEntry(@NonNull IDefinition definition) { this.definition = definition; } + /** + * Retrieves the definition associated with this entry. + * + * @return the definition + */ @NonNull public IDefinition getDefinition() { return definition; } + /** + * Checks if this definition is a root assembly definition. + * + * @return {@code true} if the definition is a root assembly, {@code false} + * otherwise + */ public boolean isRoot() { return definition instanceof IAssemblyDefinition && ((IAssemblyDefinition) definition).isRoot(); } + /** + * Checks if this definition is referenced by any instance or is a root + * definition. + * + * @return {@code true} if the definition has references or is a root, + * {@code false} otherwise + */ public boolean isReferenced() { return !references.isEmpty() || isRoot(); } + /** + * Retrieves all instances that reference this definition. + * + * @return a set of referencing instances + */ public Set getReferences() { return references; } + /** + * Adds a reference to this definition from the specified instance. + * + * @param reference + * the instance referencing this definition + * @return {@code true} if the reference was added, {@code false} if it already + * existed + */ public boolean addReference(@NonNull INamedInstance reference) { return references.add(reference); } + /** + * Marks this definition as having been visited during indexing. + */ public void markVisited() { visited.compareAndSet(false, true); } + /** + * Checks if this definition has been visited during indexing. + * + * @return {@code true} if the definition was visited, {@code false} otherwise + */ public boolean isVisited() { return visited.get(); } + /** + * Marks this definition as being inlined in the generated schema. + */ public void markInline() { inline.compareAndSet(false, true); } + /** + * Checks if this definition should be inlined in the generated schema. + * + * @return {@code true} if the definition is inlined, {@code false} otherwise + */ public boolean isInline() { return inline.get(); } + /** + * Marks this definition as being used within a choice group. + */ public void markUsedAsChoice() { usedAsChoice.compareAndSet(false, true); } + /** + * Checks if this definition is used within a choice group. + * + * @return {@code true} if the definition is used as a choice, {@code false} + * otherwise + */ public boolean isUsedAsChoice() { return usedAsChoice.get(); } + /** + * Marks this definition as having sibling elements in a choice group. + */ public void markAsChoiceSibling() { choiceSibling.compareAndSet(false, true); } + /** + * Checks if this definition has sibling elements in a choice group. + * + * @return {@code true} if the definition is a choice sibling, {@code false} + * otherwise + */ public boolean isChoiceSibling() { return choiceSibling.get(); } + /** + * Checks if any reference to this definition uses a JSON key flag. + * + * @return {@code true} if any reference has a JSON key, {@code false} otherwise + */ public boolean isUsedAsJsonKey() { return references.stream() .anyMatch(ref -> ref instanceof INamedModelInstance && ((INamedModelInstance) ref).hasJsonKey()); } + /** + * Checks if this definition is used without a JSON key flag or is a flag + * definition. + * + * @return {@code true} if the definition is a flag or has any references + * without a JSON key, {@code false} otherwise + */ public boolean isUsedWithoutJsonKey() { return definition instanceof IFlagDefinition || references.isEmpty() @@ -255,6 +385,12 @@ public boolean isUsedWithoutJsonKey() { && !((INamedModelInstance) ref).hasJsonKey()); } + /** + * Checks if this definition is a member of a choice group. + * + * @return {@code true} if any reference is a grouped model instance, + * {@code false} otherwise + */ public boolean isChoiceGroupMember() { return references.stream() .anyMatch(INamedModelInstanceGrouped.class::isInstance); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/SchemaGenerationException.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/SchemaGenerationException.java index eed5e4a60..03a0982f2 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/SchemaGenerationException.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/SchemaGenerationException.java @@ -7,6 +7,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Indicates an unrecoverable error occurred during schema generation. + *

+ * This exception is thrown when the schema generator encounters a condition + * that prevents it from completing the schema generation process. + */ public class SchemaGenerationException extends IllegalStateException { @@ -15,18 +21,43 @@ public class SchemaGenerationException */ private static final long serialVersionUID = 1L; + /** + * Constructs a new schema generation exception with no detail message. + */ public SchemaGenerationException() { // use defaults } + /** + * Constructs a new schema generation exception with the specified detail + * message and cause. + * + * @param message + * the detail message providing context about the failure + * @param cause + * the underlying cause of the exception + */ public SchemaGenerationException(String message, @NonNull Throwable cause) { super(message, cause); } + /** + * Constructs a new schema generation exception with the specified detail + * message. + * + * @param message + * the detail message providing context about the failure + */ public SchemaGenerationException(String message) { super(message); } + /** + * Constructs a new schema generation exception with the specified cause. + * + * @param cause + * the underlying cause of the exception + */ public SchemaGenerationException(@NonNull Throwable cause) { super(cause); } diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/AbstractDatatypeManager.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/AbstractDatatypeManager.java index 651c0ea20..9e8949ec0 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/AbstractDatatypeManager.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/AbstractDatatypeManager.java @@ -16,6 +16,14 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides a common base implementation for datatype management during schema + * generation. + *

+ * This class maintains a mapping between Metaschema data type adapters and + * their corresponding schema type names, handling the translation from + * Metaschema datatype names to format-specific type names. + */ public abstract class AbstractDatatypeManager implements IDatatypeManager { @NonNull private static final Map DATATYPE_TRANSLATION_MAP // NOPMD - intentional @@ -50,6 +58,11 @@ public abstract class AbstractDatatypeManager implements IDatatypeManager { @NonNull private final Map, String> datatypeToTypeMap = new ConcurrentHashMap<>(); // NOPMD - intentional + /** + * Get the mapping of Metaschema datatype names to schema type names. + * + * @return an unmodifiable map of datatype name translations + */ @SuppressWarnings("null") @NonNull protected static Map getDatatypeTranslationMap() { diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/IDatatypeManager.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/IDatatypeManager.java index bb6a5a211..7bf69987c 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/IDatatypeManager.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/IDatatypeManager.java @@ -11,8 +11,23 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Manages datatype mappings and tracks datatype usage during schema generation. + */ public interface IDatatypeManager { + /** + * Get the schema type name for the provided datatype adapter. + * + * @param datatype + * the datatype adapter to get the type name for + * @return the schema type name corresponding to the datatype + */ String getTypeNameForDatatype(@NonNull IDataTypeAdapter datatype); + /** + * Get the set of datatype names that have been used during schema generation. + * + * @return an unmodifiable set of used datatype names + */ Set getUsedTypes(); } diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/package-info.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/package-info.java index c19a58630..24e990db3 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/package-info.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/datatype/package-info.java @@ -4,8 +4,13 @@ */ /** - * Abstract support for managing Module data type implementations aligned with a - * given schema format for use in schema generation. + * Provides datatype management for schema generation. + *

+ * This package contains interfaces and abstract classes for managing Metaschema + * datatypes during schema generation, including mapping Metaschema types to + * their corresponding schema representations. + * + * @see gov.nist.secauto.metaschema.schemagen.datatype.IDatatypeManager */ package gov.nist.secauto.metaschema.schemagen.datatype; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/JsonSchemaGenerator.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/JsonSchemaGenerator.java index 65d5eff0a..0a283ecdc 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/JsonSchemaGenerator.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/JsonSchemaGenerator.java @@ -27,19 +27,39 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Generates JSON Schema documents from Metaschema modules. + *

+ * This generator produces JSON Schema draft-07 compatible schemas that can be + * used to validate JSON and YAML content conforming to the Metaschema model. + */ public class JsonSchemaGenerator extends AbstractSchemaGenerator { @NonNull private final JsonFactory jsonFactory; + /** + * Constructs a new JSON schema generator using a default JSON factory. + */ public JsonSchemaGenerator() { this(new JsonFactory()); } + /** + * Constructs a new JSON schema generator using the specified JSON factory. + * + * @param jsonFactory + * the Jackson JSON factory to use for creating JSON generators + */ public JsonSchemaGenerator(@NonNull JsonFactory jsonFactory) { this.jsonFactory = jsonFactory; } + /** + * Retrieves the JSON factory used by this generator. + * + * @return the JSON factory instance + */ @NonNull public JsonFactory getJsonFactory() { return jsonFactory; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/IJsonGenerationState.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/IJsonGenerationState.java index f537702fd..3d09d7532 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/IJsonGenerationState.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/IJsonGenerationState.java @@ -25,6 +25,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Represents the state information used during JSON schema generation. + *

+ * This interface extends {@link IGenerationState} with JSON-specific operations + * for managing schema definitions, properties, and datatype mappings. + */ public interface IJsonGenerationState extends IGenerationState { /** * Get the module this data is associated with. @@ -129,17 +135,51 @@ IJsonSchemaDefinitionAssembly getAssemblyDefinition( @NonNull IJsonSchemaPropertyGrouped getJsonSchemaPropertyGrouped(@NonNull INamedModelInstanceGrouped instance); + /** + * Generate JSON schema definitions for all used datatypes and add them to the + * provided definitions node. + * + * @param definitionsNode + * the JSON object node to add datatype definitions to + */ void generateDataTypeDefinitions(@NonNull ObjectNode definitionsNode); + /** + * Get the JSON node factory used for creating JSON schema nodes. + * + * @return the JSON node factory + */ @NonNull JsonNodeFactory getJsonNodeFactory(); + /** + * Get the JSON schema representation for the provided datatype adapter. + * + * @param datatype + * the datatype adapter to get the schema for + * @return the JSON schema representation for the datatype + */ @NonNull IDataTypeJsonSchema getSchema(@NonNull IDataTypeAdapter datatype); + /** + * Get the JSON schema representation for the datatype of the provided valued + * definition. + * + * @param definition + * the valued definition to get the datatype schema for + * @return the JSON schema representation for the definition's datatype + */ @NonNull IDataTypeJsonSchema getDataTypeSchemaForDefinition(@NonNull IValuedDefinition definition); + /** + * Convert a JSON key flag name to its string representation. + * + * @param jsonKeyFlagName + * the qualified name of the JSON key flag + * @return the string representation of the flag name + */ @NonNull default String toFlagName(@NonNull IEnhancedQName jsonKeyFlagName) { return jsonKeyFlagName.toEQName(); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/JsonGenerationState.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/JsonGenerationState.java index 266950f42..947825edb 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/JsonGenerationState.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/JsonGenerationState.java @@ -44,6 +44,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Maintains state during JSON Schema generation from a Metaschema module. + *

+ * This class manages caches for data type schemas, definition schemas, and + * provides methods for generating JSON schema definitions and writing the + * output. + */ public class JsonGenerationState extends AbstractGenerationState implements IJsonGenerationState { @@ -67,6 +74,16 @@ public class JsonGenerationState Map> groupedInstanceToJsonKeyToJsonSchemaMap = new ConcurrentHashMap<>(); + /** + * Constructs a new JSON generation state for the specified module. + * + * @param module + * the Metaschema module to generate a schema for + * @param writer + * the JSON generator for writing the schema output + * @param configuration + * the schema generation configuration settings + */ public JsonGenerationState( @NonNull IModule module, @NonNull JsonGenerator writer, @@ -288,26 +305,66 @@ public String generateJsonSchemaDefinitionName( return getTypeNameForDefinition(definition, builder.toString()); } + /** + * Writes an object node to the JSON output. + * + * @param schemaNode + * the object node to write + * @throws IOException + * if an I/O error occurs during writing + */ public void writeObject(ObjectNode schemaNode) throws IOException { getWriter().writeObject(schemaNode); } + /** + * Writes the start of a JSON object to the output. + * + * @throws IOException + * if an I/O error occurs during writing + */ @SuppressWarnings("resource") public void writeStartObject() throws IOException { getWriter().writeStartObject(); } + /** + * Writes the end of a JSON object to the output. + * + * @throws IOException + * if an I/O error occurs during writing + */ @SuppressWarnings("resource") public void writeEndObject() throws IOException { getWriter().writeEndObject(); } + /** + * Writes a field with a string value to the JSON output. + * + * @param fieldName + * the name of the field to write + * @param value + * the string value of the field + * @throws IOException + * if an I/O error occurs during writing + */ @SuppressWarnings("resource") public void writeField(String fieldName, String value) throws IOException { getWriter().writeStringField(fieldName, value); } + /** + * Writes a field with an object node value to the JSON output. + * + * @param fieldName + * the name of the field to write + * @param obj + * the object node value of the field + * @throws IOException + * if an I/O error occurs during writing + */ @SuppressWarnings("resource") public void writeField(String fieldName, ObjectNode obj) throws IOException { JsonGenerator writer = getWriter(); // NOPMD not closable here diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/JsonSchemaHelper.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/JsonSchemaHelper.java index fb59894a5..8f4161ac7 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/JsonSchemaHelper.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/JsonSchemaHelper.java @@ -46,6 +46,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Provides utility methods for generating JSON Schema elements from Metaschema + * model components. + *

+ * This class contains helper methods for generating titles, descriptions, + * defaults, properties, and handling choice combinations in JSON Schema output. + */ public final class JsonSchemaHelper { /** * Supports comparison of named properties by their property name. @@ -58,6 +65,14 @@ public final class JsonSchemaHelper { public static final Comparator DEFINABLE_NAME_COMPARATOR = Comparator.comparing(IJsonSchemaDefinable::getDefinitionName); + /** + * Generates a title property in the JSON Schema from the element's formal name. + * + * @param named + * the named model element to extract the title from + * @param obj + * the object node to add the title property to + */ public static void generateTitle( @NonNull INamedModelElement named, @NonNull ObjectNode obj) { @@ -67,6 +82,17 @@ public static void generateTitle( } } + /** + * Generates a description property in the JSON Schema from the element's + * description and remarks. + * + * @param + * the type of the named model element + * @param named + * the named model element to extract the description from + * @param obj + * the object node to add the description property to + */ public static void generateDescription( @NonNull NAMED named, @NonNull ObjectNode obj) { @@ -91,6 +117,15 @@ public static void generateDe } } + /** + * Generates a default property in the JSON Schema from the instance's default + * value. + * + * @param instance + * the valued instance to extract the default from + * @param obj + * the object node to add the default property to + */ public static void generateDefault( @NonNull IValuedInstance instance, @NonNull ObjectNode obj) { @@ -160,6 +195,16 @@ public static String generateDefinitionJsonPointer(@NonNull IJsonSchemaDefinable .toString()); } + /** + * Generates properties and required array for a JSON Schema object type. + * + * @param properties + * the collection of properties to generate + * @param node + * the object node to add the properties and required array to + * @param state + * the JSON generation state + */ public static void generateProperties( @NonNull Collection properties, @NonNull ObjectNode node, @@ -188,6 +233,22 @@ public static void generateProperties( } } + /** + * Builds a list of flag property schemas for the given definition. + *

+ * Flags used as JSON keys are excluded from the returned list. + * + * @param definition + * the model definition containing the flags + * @param jsonKeyFlagName + * the name of the flag used as JSON key, or {@code null} if none + * @param state + * the JSON generation state + * @return a list of flag property schemas, excluding the JSON key flag + * @throws IllegalArgumentException + * if the specified JSON key flag name does not exist on the + * definition + */ @NonNull public static List buildFlagProperties( @NonNull IModelDefinition definition, @@ -213,6 +274,18 @@ public static List buildFlagProperties( .collect(Collectors.toUnmodifiableList())); } + /** + * Builds a list of model property schemas for the given container definition. + *

+ * Choice instances are excluded from the returned list as they are handled + * separately. + * + * @param definition + * the container model definition containing the model instances + * @param state + * the JSON generation state + * @return a list of model property schemas, excluding choice instances + */ @NonNull public static List buildModelProperties( @NonNull IContainerModelAbsolute definition, @@ -224,6 +297,20 @@ public static List buildModelProperties( .collect(Collectors.toUnmodifiableList())); } + /** + * Generates the body of a JSON Schema for a field definition. + *

+ * For simple fields without non-value properties, generates a direct value + * reference. For complex fields with flags, generates an object type with + * properties. + * + * @param field + * the field definition schema to generate body for + * @param node + * the object node to add the schema to + * @param state + * the JSON generation state + */ public static void generateFieldBody( @NonNull IJsonSchemaDefinitionField field, @NonNull ObjectNode node, @@ -288,6 +375,19 @@ private static void generateComplexFieldBody( } } + /** + * Generates the body of a JSON Schema for an assembly definition. + *

+ * Handles choice combinations by generating either a single object type or an + * anyOf array when multiple choice combinations exist. + * + * @param assembly + * the assembly definition schema to generate body for + * @param node + * the object node to add the schema to + * @param state + * the JSON generation state + */ public static void generateAssemblyBody( @NonNull IJsonSchemaDefinitionAssembly assembly, @NonNull ObjectNode node, @@ -346,6 +446,20 @@ public boolean isRequired() { } } + /** + * Expands a base choice into all possible combinations with choice instances. + *

+ * Creates a Cartesian product of the base choice with all options from the + * provided choice instances. + * + * @param baseChoice + * the base choice to expand + * @param choiceInstances + * the choice instances to combine with + * @param state + * the JSON generation state + * @return a stream of all possible choice combinations + */ @NonNull public static Stream explodeChoices( @NonNull Choice baseChoice, @@ -359,19 +473,46 @@ public static Stream explodeChoices( return ObjectUtils.notNull(retval); } + /** + * Represents a single combination of properties in a choice group. + *

+ * Choice objects are used to track different valid combinations of properties + * when generating JSON Schema for assemblies with choice elements. + */ public static final class Choice { @NonNull private final List combinations; + /** + * Constructs a new choice with the specified property combinations. + * + * @param combinations + * the list of properties in this choice combination + */ public Choice(@NonNull List combinations) { this.combinations = combinations; } + /** + * Retrieves the properties in this choice combination. + * + * @return the list of property schemas + */ @NonNull public List getCombinations() { return combinations; } + /** + * Creates new choice combinations by adding each new choice to this choice. + *

+ * If newChoices is empty, returns a stream containing only this choice. + * + * @param newChoices + * the new property options to combine with this choice + * @return a stream of new choices, each containing this choice's properties + * plus one new property + */ @NonNull public Stream explode(@NonNull List newChoices) { return ObjectUtils.notNull(newChoices.isEmpty() diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/package-info.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/package-info.java index 1d71eca4f..144c6be04 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/package-info.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/impl/package-info.java @@ -3,4 +3,12 @@ * SPDX-License-Identifier: CC0-1.0 */ +/** + * Provides implementation classes for JSON Schema generation. + *

+ * This package contains internal implementation details for JSON Schema + * generation, including state management and helper utilities for constructing + * JSON Schema documents. + */ + package gov.nist.secauto.metaschema.schemagen.json.impl; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/package-info.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/package-info.java index 3e6c34cf3..65a00790c 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/package-info.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/json/package-info.java @@ -4,7 +4,13 @@ */ /** - * Provides JSON Schema generation capabilities based on a provided Module. + * Provides JSON Schema generation from Metaschema modules. + *

+ * This package contains the JSON Schema generator implementation that + * transforms Metaschema module definitions into JSON Schema documents + * conforming to the JSON Schema specification. + * + * @see gov.nist.secauto.metaschema.schemagen.json.JsonSchemaGenerator */ package gov.nist.secauto.metaschema.schemagen.json; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/package-info.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/package-info.java index c831f9275..34793535d 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/package-info.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/package-info.java @@ -4,7 +4,25 @@ */ /** - * Abstract support for schema generation. + * Provides schema generation capabilities for Metaschema modules. + *

+ * This package contains the core API and implementations for generating XML + * Schema (XSD) and JSON Schema from Metaschema module definitions. The main + * entry point is + * {@link gov.nist.secauto.metaschema.schemagen.ISchemaGenerator}, which + * provides methods to generate schemas in different formats. + *

+ * Key classes: + *

    + *
  • {@link gov.nist.secauto.metaschema.schemagen.ISchemaGenerator} - Main + * interface for schema generation
    • + *
  • {@link gov.nist.secauto.metaschema.schemagen.IGenerationState} - Manages + * state during schema generation
    • + *
  • {@link gov.nist.secauto.metaschema.schemagen.IInlineStrategy} - Controls + * definition inlining behavior
    • + *
  • {@link gov.nist.secauto.metaschema.schemagen.ModuleIndex} - Indexes + * definitions across modules
    • + *
*/ package gov.nist.secauto.metaschema.schemagen; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/XmlDatatypeManager.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/XmlDatatypeManager.java index 9bf91c84c..ae115ab14 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/XmlDatatypeManager.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/XmlDatatypeManager.java @@ -31,6 +31,7 @@ */ public class XmlDatatypeManager extends AbstractDatatypeManager { + /** The XML Schema namespace URI. */ public static final String NS_XML_SCHEMA = "http://www.w3.org/2001/XMLSchema"; @NonNull @@ -41,6 +42,21 @@ public class XmlDatatypeManager new XmlMarkupMultilineDatatypeProvider(), new XmlMarkupLineDatatypeProvider())))))); + /** + * Generates XML Schema datatype definitions for all used types. + *

+ * Iterates through registered datatype providers to generate definitions for + * all required types. Throws an exception if any required types are not + * provided. + * + * @param writer + * the XML stream writer to write datatype definitions to + * @throws XMLStreamException + * if an error occurs while writing XML content + * @throws IllegalStateException + * if any required datatypes are not provided by the registered + * providers + */ public void generateDatatypes(@NonNull XMLStreamWriter2 writer) throws XMLStreamException { // resolve dependencies Set used = getUsedTypes(); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/XmlSchemaGenerator.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/XmlSchemaGenerator.java index 89e37aef8..de9faeee8 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/XmlSchemaGenerator.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/XmlSchemaGenerator.java @@ -46,6 +46,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; +/** + * Generates XML Schema (XSD) documents from Metaschema modules. + *

+ * This generator produces W3C XML Schema documents that validate XML instances + * conforming to the Metaschema module definitions. + */ public class XmlSchemaGenerator extends AbstractSchemaGenerator< AutoCloser, @@ -54,20 +60,28 @@ public class XmlSchemaGenerator // private static final Logger LOGGER = // LogManager.getLogger(XmlSchemaGenerator.class); + /** The namespace prefix for XML Schema elements. */ @NonNull public static final String PREFIX_XML_SCHEMA = "xs"; + /** The XML Schema namespace URI. */ @NonNull public static final String NS_XML_SCHEMA = "http://www.w3.org/2001/XMLSchema"; @NonNull private static final String PREFIX_XML_SCHEMA_VERSIONING = "vs"; @NonNull private static final String NS_XML_SCHEMA_VERSIONING = "http://www.w3.org/2007/XMLSchema-versioning"; + /** The XHTML namespace URI used for documentation content. */ @NonNull public static final String NS_XHTML = "http://www.w3.org/1999/xhtml"; @NonNull private final XMLOutputFactory2 xmlOutputFactory; + /** + * Creates and configures a default XML output factory for schema generation. + * + * @return a configured XML output factory + */ @NonNull private static XMLOutputFactory2 defaultXMLOutputFactory() { XMLOutputFactory2 xmlOutputFactory = (XMLOutputFactory2) XMLOutputFactory.newInstance(); @@ -77,15 +91,29 @@ private static XMLOutputFactory2 defaultXMLOutputFactory() { return xmlOutputFactory; } + /** + * Constructs a new XML schema generator using the default XML output factory. + */ public XmlSchemaGenerator() { this(defaultXMLOutputFactory()); } + /** + * Constructs a new XML schema generator using the specified XML output factory. + * + * @param xmlOutputFactory + * the XML output factory to use for creating XML writers + */ @SuppressFBWarnings("EI_EXPOSE_REP2") public XmlSchemaGenerator(@NonNull XMLOutputFactory2 xmlOutputFactory) { this.xmlOutputFactory = xmlOutputFactory; } + /** + * Retrieves the XML output factory used by this generator. + * + * @return the XML output factory + */ protected XMLOutputFactory2 getXmlOutputFactory() { return xmlOutputFactory; } @@ -216,6 +244,18 @@ protected void generateSchema(XmlGenerationState state) { } } + /** + * Generates the schema metadata annotation containing module information. + *

+ * This includes the schema name, version, short name, and optional remarks. + * + * @param module + * the Metaschema module to extract metadata from + * @param state + * the XML generation state for writing output + * @throws XMLStreamException + * if an error occurs while writing XML content + */ protected static void generateSchemaMetadata( @NonNull IModule module, @NonNull XmlGenerationState state) diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractDatatypeContent.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractDatatypeContent.java index f3ec0d79c..47fdd7080 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractDatatypeContent.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractDatatypeContent.java @@ -13,12 +13,27 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; +/** + * Provides a common base implementation for datatype content used in XML schema + * generation. + *

+ * This class represents the schema content for a single datatype, including its + * type name and any dependencies on other datatypes. + */ public abstract class AbstractDatatypeContent implements IDatatypeContent { @NonNull private final String typeName; @NonNull private final List dependencies; + /** + * Construct a new datatype content instance. + * + * @param typeName + * the name of the datatype + * @param dependencies + * the list of datatype names this type depends on + */ public AbstractDatatypeContent(@NonNull String typeName, @NonNull List dependencies) { this.typeName = typeName; this.dependencies = CollectionUtil.unmodifiableList(new ArrayList<>(dependencies)); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractXmlDatatypeProvider.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractXmlDatatypeProvider.java index 9a0b5681c..06865e08b 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractXmlDatatypeProvider.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractXmlDatatypeProvider.java @@ -23,9 +23,21 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; +/** + * Provides a common base implementation for XML schema datatype providers. + *

+ * This class loads datatype definitions from an XML schema resource and + * provides them for use during schema generation. The schema is lazily loaded + * on first access. + */ public abstract class AbstractXmlDatatypeProvider implements IDatatypeProvider { private Map datatypes; + /** + * Get the input stream for the schema resource containing datatype definitions. + * + * @return the schema resource input stream + */ @Owning @NonNull protected abstract InputStream getSchemaResource(); @@ -47,9 +59,23 @@ private void initSchema() { } } + /** + * Query the schema loader for elements to be processed as datatype definitions. + * + * @param loader + * the schema loader to query + * @return the list of elements representing datatype definitions + */ @NonNull protected abstract List queryElements(JDom2XmlSchemaLoader loader); + /** + * Process the queried elements and create datatype content mappings. + * + * @param items + * the elements to process + * @return a map of datatype names to their content definitions + */ @NonNull protected abstract Map handleResults(@NonNull List items); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractXmlMarkupDatatypeProvider.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractXmlMarkupDatatypeProvider.java index f0eb5eb27..9274e8125 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractXmlMarkupDatatypeProvider.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/AbstractXmlMarkupDatatypeProvider.java @@ -19,6 +19,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides a base implementation for XML markup datatype providers. + *

+ * This class handles the loading and processing of XML schema resources that + * define markup datatypes (such as markup-line and markup-multiline). + */ public abstract class AbstractXmlMarkupDatatypeProvider extends AbstractXmlDatatypeProvider { @@ -44,6 +50,11 @@ protected List queryElements(JDom2XmlSchemaLoader loader) { CollectionUtil.singletonMap("xs", JDom2XmlSchemaLoader.NS_XML_SCHEMA)); } + /** + * Get the name of the data type provided by this provider. + * + * @return the data type name + */ @NonNull protected abstract String getDataTypeName(); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/CompositeDatatypeProvider.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/CompositeDatatypeProvider.java index 271ef895d..2d7ff9691 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/CompositeDatatypeProvider.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/CompositeDatatypeProvider.java @@ -23,14 +23,31 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A composite datatype provider that aggregates multiple datatype providers. + *

+ * This class implements the composite pattern, delegating datatype operations + * to a collection of underlying providers. + */ public class CompositeDatatypeProvider implements IDatatypeProvider { @NonNull private final List proxiedProviders; + /** + * Constructs a new composite datatype provider with the given providers. + * + * @param proxiedProviders + * the list of providers to aggregate + */ public CompositeDatatypeProvider(@NonNull List proxiedProviders) { this.proxiedProviders = CollectionUtil.unmodifiableList(new ArrayList<>(proxiedProviders)); } + /** + * Retrieves the list of proxied datatype providers. + * + * @return an unmodifiable list of the underlying providers + */ @NonNull protected List getProxiedProviders() { return proxiedProviders; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/DocumentationGenerator.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/DocumentationGenerator.java index 9f750323a..e0b8b1b53 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/DocumentationGenerator.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/DocumentationGenerator.java @@ -22,6 +22,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Generates XML Schema documentation elements for Metaschema model elements. + *

+ * This class produces {@code xs:annotation} elements containing both structured + * application information and human-readable documentation content. + */ public final class DocumentationGenerator { @Nullable @@ -63,21 +69,41 @@ private DocumentationGenerator(@NonNull INamedInstance instance) { this.modelElement = instance; } + /** + * Retrieves the formal name of the model element. + * + * @return the formal name, or {@code null} if not defined + */ @Nullable public String getFormalName() { return formalName; } + /** + * Retrieves the description of the model element. + * + * @return the description as markup, or {@code null} if not defined + */ @Nullable public MarkupLine getDescription() { return description; } + /** + * Retrieves the remarks associated with the model element. + * + * @return a list of remarks, which may be empty but never {@code null} + */ @NonNull public List getRemarks() { return remarks; } + /** + * Retrieves the underlying model element. + * + * @return the model element + */ @NonNull public IModelElement getModelElement() { return modelElement; @@ -93,18 +119,52 @@ private void generate(@NonNull XmlGenerationState state) { } } + /** + * Generates XML Schema documentation for a definition. + * + * @param definition + * the definition to generate documentation for + * @param state + * the XML generation state for writing output + */ public static void generateDocumentation( @NonNull IDefinition definition, @NonNull XmlGenerationState state) { new DocumentationGenerator(definition).generate(state); } + /** + * Generates XML Schema documentation for a named instance. + * + * @param instance + * the named instance to generate documentation for + * @param state + * the XML generation state for writing output + */ public static void generateDocumentation( @NonNull INamedInstance instance, @NonNull XmlGenerationState state) { new DocumentationGenerator(instance).generate(state); } + /** + * Generates XML Schema documentation with explicit content. + *

+ * Creates an {@code xs:annotation} element containing both structured + * application information ({@code xs:appinfo}) and human-readable documentation + * ({@code xs:documentation}). + * + * @param formalName + * the formal name, or {@code null} if not available + * @param description + * the description markup, or {@code null} if not available + * @param remarks + * the list of remarks to include + * @param xmlNS + * the target XML namespace for custom elements + * @param state + * the XML generation state for writing output + */ public static void generateDocumentation( // NOPMD acceptable complexity @Nullable String formalName, @Nullable MarkupLine description, diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/IDatatypeProvider.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/IDatatypeProvider.java index 76fc7a723..e99cd2192 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/IDatatypeProvider.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/IDatatypeProvider.java @@ -14,10 +14,35 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides XML Schema datatype definitions for schema generation. + *

+ * Implementations supply datatype content that can be written to an XML Schema + * document. + */ public interface IDatatypeProvider { + /** + * Retrieves all datatypes provided by this provider. + * + * @return a map of datatype names to their content definitions + */ @NonNull Map getDatatypes(); + /** + * Generates XML Schema datatype definitions for the specified required types. + *

+ * Only datatypes that are both provided by this provider and included in the + * required types set will be generated. + * + * @param requiredTypes + * the set of datatype names that are required + * @param writer + * the XML stream writer to write datatype definitions to + * @return the set of datatype names that were actually generated + * @throws XMLStreamException + * if an error occurs while writing XML content + */ @NonNull Set generateDatatypes(Set requiredTypes, @NonNull XMLStreamWriter2 writer) throws XMLStreamException; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/JDom2DatatypeContent.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/JDom2DatatypeContent.java index 008e9f151..35fb9c2b0 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/JDom2DatatypeContent.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/JDom2DatatypeContent.java @@ -19,12 +19,28 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Represents datatype content backed by JDOM2 elements. + *

+ * This class stores XML Schema datatype definitions as JDOM2 elements and + * provides the capability to write them to an XML stream. + */ public class JDom2DatatypeContent extends AbstractDatatypeContent { @NonNull private final List content; + /** + * Constructs a new JDOM2-backed datatype content instance. + * + * @param typeName + * the name of the datatype + * @param content + * the list of JDOM2 elements representing the datatype definition + * @param dependencies + * the list of datatype names that this datatype depends on + */ public JDom2DatatypeContent( @NonNull String typeName, @NonNull List content, @@ -33,6 +49,11 @@ public JDom2DatatypeContent( this.content = CollectionUtil.unmodifiableList(new ArrayList<>(content)); } + /** + * Retrieves the JDOM2 elements representing the datatype content. + * + * @return an unmodifiable list of JDOM2 elements + */ protected List getContent() { return content; } diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/JDom2XmlSchemaLoader.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/JDom2XmlSchemaLoader.java index 98a0b5bb4..c985aa594 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/JDom2XmlSchemaLoader.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/JDom2XmlSchemaLoader.java @@ -25,34 +25,81 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; +/** + * Loads and queries XML Schema documents using JDOM2. + *

+ * This class provides functionality to load XML Schema documents from various + * sources and query their content using XPath expressions. + */ public class JDom2XmlSchemaLoader { + /** The XML Schema namespace URI. */ @NonNull public static final String NS_XML_SCHEMA = "http://www.w3.org/2001/XMLSchema"; @NonNull private final Document document; + /** + * Constructs a new XML Schema loader from a file path. + * + * @param path + * the path to the XML Schema file + * @throws JDOMException + * if an error occurs parsing the XML + * @throws IOException + * if an I/O error occurs reading the file + */ @SuppressWarnings("null") @SuppressFBWarnings(value = "CT_CONSTRUCTOR_THROW", justification = "Use of final fields") public JDom2XmlSchemaLoader(@NonNull Path path) throws JDOMException, IOException { this(new SAXBuilder().build(path.toFile())); } + /** + * Constructs a new XML Schema loader from an input stream. + * + * @param is + * the input stream containing the XML Schema content + * @throws JDOMException + * if an error occurs parsing the XML + * @throws IOException + * if an I/O error occurs reading the stream + */ @SuppressWarnings("null") @SuppressFBWarnings(value = "CT_CONSTRUCTOR_THROW", justification = "Use of final fields") public JDom2XmlSchemaLoader(@NonNull InputStream is) throws JDOMException, IOException { this(new SAXBuilder().build(is)); } + /** + * Constructs a new XML Schema loader from a JDOM2 document. + * + * @param document + * the JDOM2 document containing the XML Schema + */ @SuppressFBWarnings("EI_EXPOSE_REP2") public JDom2XmlSchemaLoader(@NonNull Document document) { this.document = document; } + /** + * Retrieves the underlying JDOM2 document. + * + * @return the JDOM2 document + */ protected Document getNode() { return document; } + /** + * Executes an XPath query and returns matching elements. + * + * @param path + * the XPath expression to evaluate + * @param prefixToNamespaceMap + * a map of namespace prefixes to URIs for use in the XPath query + * @return a list of matching JDOM2 elements + */ @SuppressWarnings("null") @NonNull public List getContent( diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/XmlGenerationState.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/XmlGenerationState.java index 560c141e5..bdcf76c7d 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/XmlGenerationState.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/XmlGenerationState.java @@ -44,6 +44,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Manages state and provides utility methods during XML Schema generation. + *

+ * This class tracks types, namespaces, and provides methods for writing XML + * Schema elements during the schema generation process. + */ public class XmlGenerationState extends AbstractGenerationState, XmlDatatypeManager> { @NonNull @@ -59,6 +65,16 @@ public class XmlGenerationState private final AtomicInteger prefixNum = new AtomicInteger(); // 0 + /** + * Constructs a new XML generation state for the given module. + * + * @param module + * the Metaschema module being generated + * @param writer + * the auto-closing XML stream writer wrapper + * @param configuration + * the schema generation configuration options + */ public XmlGenerationState( @NonNull IModule module, @NonNull AutoCloser writer, @@ -67,28 +83,60 @@ public XmlGenerationState( this.defaultNS = ObjectUtils.notNull(module.getXmlNamespace().toASCIIString()); } + /** + * Retrieves the underlying XML stream writer. + * + * @return the XML stream writer + */ @SuppressWarnings("resource") @NonNull public XMLStreamWriter2 getXMLStreamWriter() { return getWriter().getResource(); } + /** + * Retrieves the default XML namespace for this schema. + * + * @return the default namespace URI + */ @NonNull public String getDefaultNS() { return defaultNS; } + /** + * Retrieves the namespace used for datatype definitions. + * + * @return the datatype namespace URI + */ @NonNull public String getDatatypeNS() { return getDefaultNS(); } + /** + * Retrieves the XML namespace for the given model element. + * + * @param modelElement + * the model element to get the namespace for + * @return the XML namespace URI + */ @SuppressWarnings("null") @NonNull public String getNS(@NonNull IModelElement modelElement) { return modelElement.getContainingModule().getXmlNamespace().toASCIIString(); } + /** + * Retrieves or generates a namespace prefix for the given namespace. + *

+ * Returns {@code null} for the default namespace. For other namespaces, + * generates a unique prefix if one does not already exist. + * + * @param namespace + * the namespace URI to get a prefix for + * @return the namespace prefix, or {@code null} if it is the default namespace + */ public String getNSPrefix(String namespace) { String retval = null; if (!getDefaultNS().equals(namespace)) { @@ -99,6 +147,15 @@ public String getNSPrefix(String namespace) { return retval; } + /** + * Creates a new qualified name with the given local name and namespace. + * + * @param localName + * the local name for the QName + * @param namespace + * the namespace URI for the QName + * @return a new QName with an appropriate prefix + */ @NonNull protected QName newQName( @NonNull String localName, @@ -112,6 +169,15 @@ protected QName newQName( prefix == null ? new QName(namespace, localName) : new QName(namespace, localName, prefix)); } + /** + * Creates a new qualified name for a definition type. + * + * @param definition + * the definition to create a type name for + * @param suffix + * an optional suffix to append to the type name, or {@code null} + * @return a new QName for the definition type + */ @NonNull protected QName newQName( @NonNull IDefinition definition, @@ -121,6 +187,18 @@ protected QName newQName( getNS(definition)); } + /** + * Retrieves or creates the XML type representation for a definition. + *

+ * Creates and caches the appropriate XML type based on the definition's model + * type (flag, field, or assembly). + * + * @param definition + * the definition to get the XML type for + * @return the XML type representing the definition + * @throws UnsupportedOperationException + * if the definition is a choice or choice group + */ public IXmlType getXmlForDefinition(@NonNull IDefinition definition) { IXmlType retval = definitionToTypeMap.get(definition); if (retval == null) { @@ -151,6 +229,13 @@ public IXmlType getXmlForDefinition(@NonNull IDefinition definition) { return retval; } + /** + * Retrieves or creates a simple type for a data type adapter. + * + * @param dataType + * the data type adapter + * @return the XML simple type representation + */ @NonNull public IXmlSimpleType getSimpleType(@NonNull IDataTypeAdapter dataType) { IXmlSimpleType type = dataTypeToSimpleTypeMap.get(dataType); @@ -165,6 +250,17 @@ public IXmlSimpleType getSimpleType(@NonNull IDataTypeAdapter dataType) { return type; } + /** + * Retrieves or creates a simple type for a valued definition. + *

+ * If the definition has allowed value constraints, creates an appropriate + * restriction or union type. Otherwise, returns the simple type for the + * underlying data type. + * + * @param definition + * the valued definition + * @return the XML simple type representation + */ @NonNull public IXmlSimpleType getSimpleType(@NonNull IValuedDefinition definition) { IXmlSimpleType simpleType = definitionToSimpleTypeMap.get(definition); @@ -201,18 +297,41 @@ public IXmlSimpleType getSimpleType(@NonNull IValuedDefinition definition) { return simpleType; } + /** + * Creates a new complex type for a field definition. + * + * @param definition + * the field definition + * @return a new complex type representation + */ @NonNull protected IXmlComplexType newComplexType(@NonNull IFieldDefinition definition) { QName qname = newQName(definition, null); return new XmlComplexTypeFieldDefinition(qname, definition); } + /** + * Creates a new complex type for an assembly definition. + * + * @param definition + * the assembly definition + * @return a new complex type representation + */ @NonNull protected IXmlComplexType newComplexType(@NonNull IAssemblyDefinition definition) { QName qname = newQName(definition, null); return new XmlComplexTypeAssemblyDefinition(qname, definition); } + /** + * Generates all XML types that are not inline and are referenced. + *

+ * Iterates through all definitions and generates types that need to be written + * as separate type definitions in the schema. + * + * @throws XMLStreamException + * if an error occurs while writing XML content + */ public void generateXmlTypes() throws XMLStreamException { for (IXmlType type : definitionToTypeMap.values()) { @@ -225,14 +344,46 @@ public void generateXmlTypes() throws XMLStreamException { getDatatypeManager().generateDatatypes(getXMLStreamWriter()); } + /** + * Writes an attribute to the current element. + * + * @param localName + * the local name of the attribute + * @param value + * the value of the attribute + * @throws XMLStreamException + * if an error occurs while writing + */ public void writeAttribute(@NonNull String localName, @NonNull String value) throws XMLStreamException { getXMLStreamWriter().writeAttribute(localName, value); } + /** + * Writes a start element with the given namespace and local name. + * + * @param namespaceUri + * the namespace URI for the element + * @param localName + * the local name of the element + * @throws XMLStreamException + * if an error occurs while writing + */ public void writeStartElement(@NonNull String namespaceUri, @NonNull String localName) throws XMLStreamException { getXMLStreamWriter().writeStartElement(namespaceUri, localName); } + /** + * Writes a start element with the given prefix, local name, and namespace. + * + * @param prefix + * the namespace prefix for the element + * @param localName + * the local name of the element + * @param namespaceUri + * the namespace URI for the element + * @throws XMLStreamException + * if an error occurs while writing + */ public void writeStartElement( @NonNull String prefix, @NonNull String localName, @@ -241,14 +392,38 @@ public void writeStartElement( } + /** + * Writes an end element for the current element. + * + * @throws XMLStreamException + * if an error occurs while writing + */ public void writeEndElement() throws XMLStreamException { getXMLStreamWriter().writeEndElement(); } + /** + * Writes character content to the current element. + * + * @param text + * the text content to write + * @throws XMLStreamException + * if an error occurs while writing + */ public void writeCharacters(@NonNull String text) throws XMLStreamException { getXMLStreamWriter().writeCharacters(text); } + /** + * Writes a namespace declaration. + * + * @param prefix + * the namespace prefix + * @param namespaceUri + * the namespace URI + * @throws XMLStreamException + * if an error occurs while writing + */ public void writeNamespace(String prefix, String namespaceUri) throws XMLStreamException { getXMLStreamWriter().writeNamespace(prefix, namespaceUri); } diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/XmlProseCompositDatatypeProvider.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/XmlProseCompositDatatypeProvider.java index d5f11fcf2..ba42ce457 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/XmlProseCompositDatatypeProvider.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/XmlProseCompositDatatypeProvider.java @@ -16,11 +16,23 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A composite datatype provider specialized for prose markup types. + *

+ * This provider extends the composite provider to additionally generate base + * prose datatype definitions when prose markup types are used. + */ public class XmlProseCompositDatatypeProvider extends CompositeDatatypeProvider { private final XmlProseBaseDatatypeProvider proseBaseProvider = new XmlProseBaseDatatypeProvider(); + /** + * Constructs a new prose composite datatype provider. + * + * @param proxiedProviders + * the list of underlying providers to aggregate + */ public XmlProseCompositDatatypeProvider(@NonNull List proxiedProviders) { super(proxiedProviders); } diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/package-info.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/package-info.java index b57f8dcd8..8cd12e4d3 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/package-info.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/package-info.java @@ -3,4 +3,12 @@ * SPDX-License-Identifier: CC0-1.0 */ +/** + * Provides implementation classes for XML Schema generation. + *

+ * This package contains internal implementation details for XML Schema + * generation, including state management, datatype providers, and documentation + * generation utilities. + */ + package gov.nist.secauto.metaschema.schemagen.xml.impl; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlComplexType.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlComplexType.java index f543cb255..8e6282274 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlComplexType.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlComplexType.java @@ -17,12 +17,29 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides a common base implementation for XML complex type schema elements. + *

+ * This class represents a complex type in an XML schema that corresponds to a + * Metaschema model definition (assembly or field with flags). + * + * @param + * the type of model definition this complex type represents + */ public abstract class AbstractXmlComplexType extends AbstractXmlType implements IXmlComplexType { @NonNull private final D definition; + /** + * Construct a new complex type. + * + * @param qname + * the qualified name for the type + * @param definition + * the model definition this type represents + */ public AbstractXmlComplexType( @NonNull QName qname, @NonNull D definition) { @@ -55,8 +72,26 @@ public void generate(@NonNull XmlGenerationState state) { } } + /** + * Generate the body content of the complex type. + * + * @param state + * the generation state for context and writing + * @throws XMLStreamException + * if an error occurs while writing the XML + */ protected abstract void generateTypeBody(@NonNull XmlGenerationState state) throws XMLStreamException; + /** + * Generate an XML schema attribute declaration for a flag instance. + * + * @param instance + * the flag instance to generate an attribute for + * @param state + * the generation state for context and writing + * @throws XMLStreamException + * if an error occurs while writing the XML + */ protected static void generateFlagInstance(@NonNull IFlagInstance instance, @NonNull XmlGenerationState state) throws XMLStreamException { state.writeStartElement(XmlSchemaGenerator.PREFIX_XML_SCHEMA, "attribute", XmlSchemaGenerator.NS_XML_SCHEMA); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlSimpleType.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlSimpleType.java index 108326d79..23bbfaaad 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlSimpleType.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlSimpleType.java @@ -13,6 +13,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides a common base implementation for XML simple type schema elements. + *

+ * This class represents a simple type in an XML schema that corresponds to a + * Metaschema valued definition (field or flag). + */ public abstract class AbstractXmlSimpleType extends AbstractXmlType implements IXmlSimpleType { @@ -20,11 +26,24 @@ public abstract class AbstractXmlSimpleType @NonNull private final IValuedDefinition definition; + /** + * Construct a new simple type. + * + * @param qname + * the qualified name for the type + * @param definition + * the valued definition this type represents + */ public AbstractXmlSimpleType(@NonNull QName qname, @NonNull IValuedDefinition definition) { super(qname); this.definition = definition; } + /** + * Get the valued definition this type represents. + * + * @return the valued definition + */ @NonNull public IValuedDefinition getDefinition() { return definition; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlType.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlType.java index a73ac16e5..2d6464c75 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlType.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/AbstractXmlType.java @@ -9,10 +9,22 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides a common base implementation for XML schema type elements. + *

+ * This abstract class serves as the foundation for all XML type + * representations, maintaining the qualified name that identifies the type. + */ public abstract class AbstractXmlType implements IXmlType { @NonNull private final QName qname; + /** + * Construct a new XML type. + * + * @param qname + * the qualified name for the type + */ public AbstractXmlType(@NonNull QName qname) { this.qname = qname; } diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/IXmlComplexType.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/IXmlComplexType.java index 49cd8350a..6be84b9d8 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/IXmlComplexType.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/IXmlComplexType.java @@ -11,7 +11,20 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Represents an XML Schema complex type derived from a Metaschema model + * definition. + *

+ * Complex types are used to represent Metaschema assemblies and fields that + * have flags (attributes) or child elements. Unlike simple types, complex types + * can have both element content and attributes. + */ public interface IXmlComplexType extends IXmlType { + /** + * Get the Metaschema definition that this complex type is derived from. + * + * @return the underlying Metaschema definition + */ @NonNull IDefinition getDefinition(); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/IXmlSimpleType.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/IXmlSimpleType.java index 5380ce311..29187e41a 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/IXmlSimpleType.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/IXmlSimpleType.java @@ -10,7 +10,19 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Represents an XML Schema simple type derived from a Metaschema data type. + *

+ * Simple types are used to represent scalar values in XML Schema, such as + * strings, numbers, and dates. They may include restrictions like enumerated + * values or pattern constraints. + */ public interface IXmlSimpleType extends IXmlType { + /** + * Get the data type adapter that handles value conversion for this simple type. + * + * @return the data type adapter + */ @NonNull IDataTypeAdapter getDataTypeAdapter(); diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlComplexTypeAssemblyDefinition.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlComplexTypeAssemblyDefinition.java index 48ced825d..071052095 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlComplexTypeAssemblyDefinition.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlComplexTypeAssemblyDefinition.java @@ -29,9 +29,25 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * An XML Schema complex type implementation for Metaschema assembly + * definitions. + *

+ * This class generates XML Schema complexType elements that represent + * Metaschema assemblies, including their child model instances (fields, + * assemblies, choices) and flag instances (attributes). + */ public class XmlComplexTypeAssemblyDefinition extends AbstractXmlComplexType { + /** + * Construct a new complex type for an assembly definition. + * + * @param qname + * the qualified name for the XML Schema type + * @param definition + * the Metaschema assembly definition to generate the type for + */ public XmlComplexTypeAssemblyDefinition( @NonNull QName qname, @NonNull IAssemblyDefinition definition) { @@ -61,6 +77,19 @@ protected void generateTypeBody(XmlGenerationState state) throws XMLStreamExcept } } + /** + * Generate XML Schema elements for a model instance. + *

+ * Handles grouped elements, assemblies, fields (wrapped and unwrapped), + * choices, and choice groups. + * + * @param modelInstance + * the model instance to generate schema elements for + * @param state + * the schema generation state for writing output + * @throws XMLStreamException + * if an error occurs while writing XML + */ protected void generateModelInstance( // NOPMD acceptable complexity @NonNull IModelInstanceAbsolute modelInstance, @NonNull XmlGenerationState state) @@ -123,6 +152,18 @@ protected void generateModelInstance( // NOPMD acceptable complexity } } + /** + * Generate an XML Schema element declaration for a named model instance. + * + * @param modelInstance + * the named model instance to generate a declaration for + * @param grouped + * {@code true} if the instance is within a grouping element + * @param state + * the schema generation state for writing output + * @throws XMLStreamException + * if an error occurs while writing XML + */ protected void generateNamedModelInstance( @NonNull INamedModelInstanceAbsolute modelInstance, boolean grouped, @@ -154,6 +195,21 @@ protected void generateNamedModelInstance( state.writeEndElement(); // xs:element } + /** + * Generate an XML Schema group reference for an unwrapped field instance. + *

+ * Unwrapped fields are used for multiline markup content that appears directly + * within the parent element without a wrapper element. + * + * @param fieldInstance + * the unwrapped field instance to generate a reference for + * @param grouped + * {@code true} if the instance is within a grouping element + * @param state + * the schema generation state for writing output + * @throws XMLStreamException + * if an error occurs while writing XML + */ protected static void generateUnwrappedFieldInstance( @NonNull IFieldInstanceAbsolute fieldInstance, boolean grouped, @@ -188,6 +244,16 @@ protected static void generateUnwrappedFieldInstance( state.writeEndElement(); // xs:group } + /** + * Generate an XML Schema choice element for a choice model instance. + * + * @param choice + * the choice instance to generate schema elements for + * @param state + * the schema generation state for writing output + * @throws XMLStreamException + * if an error occurs while writing XML + */ protected void generateChoiceModelInstance( @NonNull IChoiceInstance choice, @NonNull XmlGenerationState state) throws XMLStreamException { @@ -231,6 +297,21 @@ private void generateChoiceGroupInstance(IChoiceGroupInstance choiceGroup, XmlGe state.writeEndElement(); // xs:choice } + /** + * Generate an XML Schema element declaration for a grouped named model + * instance. + *

+ * Grouped instances appear within choice groups and do not have occurrence + * constraints at the element level since these are handled by the parent + * choice. + * + * @param instance + * the grouped named model instance to generate a declaration for + * @param state + * the schema generation state for writing output + * @throws XMLStreamException + * if an error occurs while writing XML + */ protected void generateGroupedNamedModelInstance( @NonNull INamedModelInstanceGrouped instance, @NonNull XmlGenerationState state) throws XMLStreamException { diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlComplexTypeFieldDefinition.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlComplexTypeFieldDefinition.java index af6135911..e1f5920b0 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlComplexTypeFieldDefinition.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlComplexTypeFieldDefinition.java @@ -16,8 +16,25 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * An XML Schema complex type implementation for Metaschema field definitions + * that have flags. + *

+ * Fields with flags require a complex type in XML Schema because they need both + * content (the field value) and attributes (the flags). This class generates + * either simpleContent or complexContent extensions depending on whether the + * field's data type produces mixed XML content. + */ public class XmlComplexTypeFieldDefinition extends AbstractXmlComplexType { + /** + * Construct a new complex type for a field definition. + * + * @param qname + * the qualified name for the XML Schema type + * @param definition + * the Metaschema field definition to generate the type for + */ public XmlComplexTypeFieldDefinition( @NonNull QName qname, @NonNull IFieldDefinition definition) { diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeReference.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeReference.java index e03590de9..a5d1847f3 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeReference.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeReference.java @@ -12,6 +12,14 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Represents a reference to a built-in XML Schema data type. + *

+ * This class provides a reference to an existing data type that is not + * generated by the schema generator, but is instead handled by the data type + * manager. The type is referenced by its qualified name without generating any + * additional schema content. + */ // TODO: remove, since this doesn't represent a type public class XmlSimpleTypeDataTypeReference extends AbstractXmlType @@ -19,6 +27,14 @@ public class XmlSimpleTypeDataTypeReference @NonNull private final IDataTypeAdapter dataTypeAdapter; + /** + * Construct a new data type reference. + * + * @param typeName + * the qualified name of the referenced data type + * @param dataTypeAdapter + * the data type adapter that handles value conversion + */ public XmlSimpleTypeDataTypeReference( @NonNull QName typeName, @NonNull IDataTypeAdapter dataTypeAdapter) { diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeRestriction.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeRestriction.java index 457d50305..a08197382 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeRestriction.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeRestriction.java @@ -21,11 +21,29 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * An XML Schema simple type that restricts a base data type with enumerated + * allowed values. + *

+ * This class generates an xs:simpleType with xs:restriction containing + * xs:enumeration elements for each allowed value defined in the Metaschema + * constraints. + */ public class XmlSimpleTypeDataTypeRestriction extends AbstractXmlSimpleType { @NonNull private final AllowedValueCollection allowedValuesCollection; + /** + * Construct a new data type restriction. + * + * @param qname + * the qualified name for the XML Schema type + * @param definition + * the Metaschema definition that this restriction applies to + * @param allowedValuesCollection + * the collection of allowed values to use as enumeration constraints + */ public XmlSimpleTypeDataTypeRestriction( @NonNull QName qname, @NonNull IValuedDefinition definition, @@ -34,6 +52,11 @@ public XmlSimpleTypeDataTypeRestriction( this.allowedValuesCollection = allowedValuesCollection; } + /** + * Get the collection of allowed values for this restriction. + * + * @return the allowed values collection + */ protected AllowedValueCollection getAllowedValuesCollection() { return allowedValuesCollection; } @@ -84,6 +107,19 @@ public void generate(XmlGenerationState state) { } } + /** + * Generate an XML Schema annotation containing documentation for an allowed + * value. + * + * @param description + * the markup description to include in the documentation + * @param xmlNS + * the XML namespace for documentation elements + * @param state + * the schema generation state for writing output + * @throws XMLStreamException + * if an error occurs while writing XML + */ public static void generateDescriptionAnnotation( @NonNull MarkupLine description, @NonNull String xmlNS, diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeUnion.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeUnion.java index 34ad7f5ef..daa0e3f4c 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeUnion.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeUnion.java @@ -21,11 +21,28 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * An XML Schema simple type that is a union of multiple member types. + *

+ * This class generates an xs:simpleType with xs:union that combines multiple + * simple types. Member types may be referenced by name or inlined depending on + * their generation requirements. + */ public class XmlSimpleTypeUnion extends AbstractXmlSimpleType { @NonNull private final List simpleTypes; + /** + * Construct a new union type. + * + * @param qname + * the qualified name for the XML Schema type + * @param definition + * the Metaschema definition that this union applies to + * @param simpleTypes + * the member types to include in the union + */ public XmlSimpleTypeUnion( @NonNull QName qname, @NonNull IValuedDefinition definition, @@ -34,6 +51,11 @@ public XmlSimpleTypeUnion( this.simpleTypes = CollectionUtil.requireNonEmpty(CollectionUtil.listOrEmpty(simpleTypes)); } + /** + * Get the member types that make up this union. + * + * @return an unmodifiable list of member simple types + */ @NonNull public List getSimpleTypes() { return simpleTypes; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/package-info.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/package-info.java index 7ca818916..5e061f360 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/package-info.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/package-info.java @@ -4,8 +4,11 @@ */ /** - * Supports generation of XML Schema types based on Module contructs (i.e. - * flags, fields, assemblies). + * Provides XML Schema type representations for schema generation. + *

+ * This package contains classes that represent XML Schema type elements, + * including both simple types (for scalar values) and complex types (for + * structured content like assemblies and fields with flags). */ package gov.nist.secauto.metaschema.schemagen.xml.impl.schematype; diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/package-info.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/package-info.java index d0047a5ff..86905b823 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/package-info.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/package-info.java @@ -4,7 +4,12 @@ */ /** - * Provides XML Schema generation capabilities based on a provided Module. + * Provides XML Schema (XSD) generation from Metaschema modules. + *

+ * This package contains the XML Schema generator implementation that transforms + * Metaschema module definitions into W3C XML Schema Definition (XSD) documents. + * + * @see gov.nist.secauto.metaschema.schemagen.xml.XmlSchemaGenerator */ package gov.nist.secauto.metaschema.schemagen.xml; From 9c0c9cc79674e16d29299bd1b72928184ecd175d Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Mon, 29 Dec 2025 08:52:32 -0500 Subject: [PATCH 2/3] feat(databind,maven-plugin): add complete Javadoc coverage Add Javadoc documentation to all public/protected methods and create/enhance package-info.java files across databind and maven-plugin modules. databind module: - Document codegen, io, and model packages with method-level Javadoc - Enhance package-info.java files with detailed descriptions - Excludes generated binding classes per project conventions metaschema-maven-plugin module: - Document all Mojo classes and inner classes - Add package-info.java with plugin goal documentation Achieves 0 Checkstyle MissingJavadocMethod violations in target packages. --- .../PostProcessingModuleLoaderStrategy.java | 50 +++++--- .../databind/RootAssemblyBindingMatcher.java | 33 +++++ .../databind/SimpleModuleLoaderStrategy.java | 21 ++++ .../DefaultModuleBindingGenerator.java | 16 +++ .../databind/codegen/IGeneratedClass.java | 13 +- .../codegen/IModuleBindingGenerator.java | 16 +++ .../databind/codegen/JavaCompilerSupport.java | 105 +++++++++++++++- .../databind/codegen/PackageMetadata.java | 36 ++++++ .../codegen/PackageProductionImpl.java | 16 +++ .../databind/codegen/ProductionImpl.java | 34 +++++ .../impl/DefaultGeneratedModuleClass.java | 18 +++ .../databind/codegen/impl/package-info.java | 11 ++ .../typeinfo/IMetaschemaClassFactory.java | 7 ++ .../databind/codegen/typeinfo/ITypeInfo.java | 12 ++ .../codegen/typeinfo/ITypeResolver.java | 7 ++ .../typeinfo/def/IDefinitionTypeInfo.java | 6 + .../def/IModelDefinitionTypeInfo.java | 7 ++ .../codegen/typeinfo/def/package-info.java | 12 ++ .../codegen/typeinfo/package-info.java | 12 ++ .../io/AbstractSerializationBase.java | 25 ++++ .../databind/io/DeserializationFeature.java | 27 ++++ .../databind/io/SerializationFeature.java | 21 +++- .../io/json/DefaultJsonSerializer.java | 30 +++++ .../databind/io/json/IJsonParsingContext.java | 13 ++ .../databind/io/json/IJsonWritingContext.java | 8 ++ .../databind/io/json/JsonFactoryFactory.java | 11 ++ .../databind/io/json/MetaschemaJsonUtil.java | 9 ++ .../io/json/MetaschemaJsonWriter.java | 11 ++ .../databind/io/json/package-info.java | 18 ++- .../metaschema/databind/io/package-info.java | 18 ++- .../databind/io/xml/CommentFilter.java | 6 + .../databind/io/xml/DefaultXmlSerializer.java | 16 +++ .../databind/io/xml/IXmlWritingContext.java | 18 +++ .../databind/io/xml/MetaschemaXmlWriter.java | 11 ++ .../databind/io/xml/package-info.java | 19 ++- .../function/DatabindFunctionLibrary.java | 6 + .../databind/metapath/function/Model.java | 6 + .../databind/model/AbstractBoundModule.java | 7 ++ .../databind/model/IBoundDefinition.java | 6 + .../databind/model/IBoundFieldValue.java | 6 + .../model/IBoundInstanceModelField.java | 9 ++ .../databind/model/IBoundModelElement.java | 6 + .../databind/model/IBoundProperty.java | 9 ++ .../databind/model/annotations/ModelUtil.java | 6 + .../AbstractBoundDefinitionModelComplex.java | 10 ++ .../model/impl/BoundInstanceModelChoice.java | 6 + .../model/impl/ClassIntrospector.java | 6 + .../model/impl/ConstraintSupport.java | 6 + .../databind/model/impl/DefaultGroupAs.java | 7 ++ .../impl/IFeatureInstanceModelGroupAs.java | 6 + .../impl/InstanceModelAssemblyComplex.java | 6 + .../model/impl/InstanceModelChoiceGroup.java | 6 + .../model/impl/InstanceModelFieldComplex.java | 6 + .../model/impl/InstanceModelFieldScalar.java | 6 + .../impl/InstanceModelGroupedAssembly.java | 6 + .../InstanceModelGroupedFieldComplex.java | 6 + .../AbstractModelInstanceCollectionInfo.java | 10 ++ .../AbstractModelInstanceReadHandler.java | 9 ++ .../AbstractModelInstanceWriteHandler.java | 9 ++ .../info/IFeatureComplexItemValueHandler.java | 7 ++ .../info/IFeatureScalarItemValueHandler.java | 7 ++ .../databind/model/info/IItemReadHandler.java | 6 + .../model/info/IItemValueHandler.java | 9 ++ .../model/info/IItemWriteHandler.java | 6 + .../info/IModelInstanceCollectionInfo.java | 9 ++ .../model/info/IModelInstanceReadHandler.java | 10 ++ .../info/IModelInstanceWriteHandler.java | 10 ++ .../model/info/ListCollectionInfo.java | 9 ++ .../model/info/MapCollectionInfo.java | 9 ++ .../model/info/SingletonCollectionInfo.java | 9 ++ .../metaschema/BindingConstraintLoader.java | 7 ++ .../model/metaschema/BindingModuleLoader.java | 6 + .../metaschema/IBindingDefinitionModel.java | 6 + .../IBindingDefinitionModelAssembly.java | 6 + .../model/metaschema/IBindingInstance.java | 6 + .../metaschema/IBindingInstanceModel.java | 6 + .../metaschema/IBindingMetaschemaModule.java | 6 + .../metaschema/IBindingModelElement.java | 6 + .../metaschema/IBindingModuleLoader.java | 6 + .../IConfigurableMessageConstraintBase.java | 6 + .../model/metaschema/IConstraintBase.java | 6 + .../metaschema/IModelConstraintsBase.java | 6 + .../metaschema/ITargetedConstraintBase.java | 6 + .../metaschema/IValueConstraintsBase.java | 6 + .../IValueTargetedConstraintsBase.java | 6 + .../ModuleLoadingPostProcessor.java | 6 + .../impl/AbstractAbsoluteModelGenerator.java | 6 + .../metaschema/impl/AbstractAllowedValue.java | 6 + .../impl/AssemblyModelGenerator.java | 6 + .../metaschema/impl/BindingConstants.java | 6 + .../impl/ChoiceGroupModelGenerator.java | 6 + .../metaschema/impl/ChoiceModelGenerator.java | 6 + .../impl/ConstraintBindingSupport.java | 6 + .../impl/DefinitionAssemblyGlobal.java | 6 + .../impl/DefinitionFieldGlobal.java | 6 + .../metaschema/impl/DefinitionFlagGlobal.java | 6 + .../metaschema/impl/FlagContainerSupport.java | 6 + .../metaschema/impl/InstanceFlagInline.java | 6 + .../impl/InstanceFlagReference.java | 6 + .../impl/InstanceModelAssemblyInline.java | 6 + .../impl/InstanceModelAssemblyReference.java | 6 + .../metaschema/impl/InstanceModelChoice.java | 6 + .../impl/InstanceModelChoiceGroup.java | 6 + .../impl/InstanceModelFieldInline.java | 6 + .../impl/InstanceModelFieldReference.java | 6 + .../InstanceModelGroupedAssemblyInline.java | 5 + ...InstanceModelGroupedAssemblyReference.java | 6 + .../impl/InstanceModelGroupedFieldInline.java | 5 + .../InstanceModelGroupedFieldReference.java | 6 + .../model/metaschema/impl/ModelSupport.java | 6 + .../maven/plugin/AbstractMetaschemaMojo.java | 117 +++++++++++++++++- .../maven/plugin/GenerateSchemaMojo.java | 10 ++ .../maven/plugin/GenerateSourcesMojo.java | 1 + .../metaschema/maven/plugin/package-info.java | 53 ++++++++ 114 files changed, 1337 insertions(+), 33 deletions(-) create mode 100644 metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/package-info.java diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/PostProcessingModuleLoaderStrategy.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/PostProcessingModuleLoaderStrategy.java index b419b6afd..e9502fecf 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/PostProcessingModuleLoaderStrategy.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/PostProcessingModuleLoaderStrategy.java @@ -24,21 +24,47 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A module loader strategy that applies post-processors to loaded modules. + *

+ * This strategy wraps another {@link IBindingContext.IModuleLoaderStrategy} and + * ensures that configured {@link IModuleLoader.IModulePostProcessor} instances + * are invoked on each module before it is registered. Post-processing is + * applied only once per module, even if the module is referenced multiple + * times. + * + * @since 2.0.0 + */ public class PostProcessingModuleLoaderStrategy implements IBindingContext.IModuleLoaderStrategy { @NonNull private final List modulePostProcessors; - // private final Set resolvedModules = new HashSet<>(); - // private final Lock resolvedModulesLock = new ReentrantLock(); private final IBindingContext.IModuleLoaderStrategy delegate; private final Set postProcessedModules = new HashSet<>(); private final Lock postProcessedModulesLock = new ReentrantLock(); + /** + * Construct a new post-processing module loader strategy using the default + * delegate strategy. + * + * @param modulePostProcessors + * the post-processors to apply to loaded modules + */ public PostProcessingModuleLoaderStrategy( @NonNull List modulePostProcessors) { this(modulePostProcessors, new SimpleModuleLoaderStrategy()); } + /** + * Construct a new post-processing module loader strategy with a custom + * delegate. + * + * @param modulePostProcessors + * the post-processors to apply to loaded modules + * @param delegate + * the delegate strategy to use for actual module loading and + * registration + */ public PostProcessingModuleLoaderStrategy( @NonNull List modulePostProcessors, @NonNull IBindingContext.IModuleLoaderStrategy delegate) { @@ -46,6 +72,11 @@ public PostProcessingModuleLoaderStrategy( this.delegate = delegate; } + /** + * Get the configured module post-processors. + * + * @return an unmodifiable list of post-processors + */ @NonNull protected List getModulePostProcessors() { return modulePostProcessors; @@ -109,21 +140,6 @@ public Collection getBindingMatchers() { public IBoundDefinitionModelComplex getBoundDefinitionForClass( Class clazz, IBindingContext bindingContext) { - - // - // resolvedModulesLock.lock(); - // try { - // if (!resolvedModules.contains(module)) { - // // add first, to avoid loops - // resolvedModules.add(module); - // for (IModuleLoader.IModulePostProcessor postProcessor : - // getModulePostProcessors()) { - // postProcessor.processModule(module); - // } - // } - // } finally { - // resolvedModulesLock.unlock(); - // } return delegate.getBoundDefinitionForClass(clazz, bindingContext); } } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/RootAssemblyBindingMatcher.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/RootAssemblyBindingMatcher.java index 1cde9e046..9860a3941 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/RootAssemblyBindingMatcher.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/RootAssemblyBindingMatcher.java @@ -15,6 +15,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * A binding matcher that matches based on a root assembly definition. + *

+ * This implementation matches XML elements by their qualified name and + * JSON/YAML properties by their root name, allowing the binding context to + * identify the correct bound class for a given document root element. + */ class RootAssemblyBindingMatcher implements IBindingMatcher { @NonNull private final IBoundDefinitionModelAssembly definition; @@ -22,24 +29,50 @@ class RootAssemblyBindingMatcher implements IBindingMatcher { private final Lazy rootQName = ObjectUtils.notNull( Lazy.of(() -> getDefinition().getRootQName().toQName())); + /** + * Construct a new binding matcher for the provided root assembly definition. + * + * @param definition + * the root assembly definition to match against + */ public RootAssemblyBindingMatcher( @NonNull IBoundDefinitionModelAssembly definition) { this.definition = definition; } + /** + * Get the assembly definition this matcher is based on. + * + * @return the assembly definition + */ protected IBoundDefinitionModelAssembly getDefinition() { return definition; } + /** + * Get the bound class associated with this matcher's definition. + * + * @return the bound class + */ protected Class getClazz() { return getDefinition().getBoundClass(); } + /** + * Get the XML qualified name for the root element. + * + * @return the root element's QName + */ @NonNull protected QName getRootQName() { return ObjectUtils.notNull(rootQName.get()); } + /** + * Get the JSON/YAML root property name. + * + * @return the root JSON name + */ @SuppressWarnings("null") @NonNull protected String getRootJsonName() { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/SimpleModuleLoaderStrategy.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/SimpleModuleLoaderStrategy.java index f127a0174..0819b3c0c 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/SimpleModuleLoaderStrategy.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/SimpleModuleLoaderStrategy.java @@ -12,6 +12,16 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A simple module loader strategy that supports optional dynamic code + * generation. + *

+ * By default, dynamic compilation is disabled. To enable dynamic compilation of + * Metaschema modules into bound Java classes, provide an + * {@link IModuleBindingGenerator} implementation to the constructor. + * + * @since 2.0.0 + */ public class SimpleModuleLoaderStrategy extends AbstractModuleLoaderStrategy { @NonNull @@ -25,10 +35,21 @@ public class SimpleModuleLoaderStrategy @NonNull private final IModuleBindingGenerator generator; + /** + * Construct a new simple module loader strategy with dynamic compilation + * disabled. + */ public SimpleModuleLoaderStrategy() { this(COMPILATION_DISABLED_GENERATOR); } + /** + * Construct a new simple module loader strategy with the provided binding + * generator. + * + * @param generator + * the generator to use for dynamic module compilation + */ public SimpleModuleLoaderStrategy(@NonNull IModuleBindingGenerator generator) { this.generator = generator; } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/DefaultModuleBindingGenerator.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/DefaultModuleBindingGenerator.java index 1aa802413..296c8a208 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/DefaultModuleBindingGenerator.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/DefaultModuleBindingGenerator.java @@ -15,10 +15,26 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Default implementation of {@link IModuleBindingGenerator} that generates and + * compiles Java classes for a Metaschema module. + *

+ * This generator creates Java source files representing the module and its + * definitions, compiles them, and loads the resulting classes using a custom + * class loader. + */ public class DefaultModuleBindingGenerator implements IModuleBindingGenerator { @NonNull private final Path compilePath; + /** + * Construct a new binding generator that generates classes in the specified + * directory. + * + * @param compilePath + * the directory where generated Java classes will be created and + * compiled + */ public DefaultModuleBindingGenerator(@NonNull Path compilePath) { this.compilePath = compilePath; } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/IGeneratedClass.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/IGeneratedClass.java index 67de9ed57..6851681d7 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/IGeneratedClass.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/IGeneratedClass.java @@ -9,16 +9,23 @@ import java.nio.file.Path; +/** + * Provides information about a generated Java class file. + *

+ * This interface represents a Java class that has been generated during + * Metaschema processing, providing access to both the physical file location + * and the type information for the generated class. + */ public interface IGeneratedClass { /** - * The file the class was written to. + * Get the file the class was written to. * - * @return the class file + * @return the class file path */ Path getClassFile(); /** - * The type info for the class. + * Get the type info for the class. * * @return the class's type info */ diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/IModuleBindingGenerator.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/IModuleBindingGenerator.java index 72b63a3b2..67c74fe92 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/IModuleBindingGenerator.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/IModuleBindingGenerator.java @@ -11,8 +11,24 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A functional interface for generating bound Java classes from a Metaschema + * module. + *

+ * Implementations of this interface are responsible for generating, compiling, + * and loading Java classes that represent the module and its definitions. + */ @FunctionalInterface public interface IModuleBindingGenerator { + /** + * Generate bound Java classes for the provided Metaschema module. + * + * @param module + * the Metaschema module to generate classes for + * @return the generated bound module class + * @throws MetaschemaException + * if an error occurs during generation or compilation + */ @NonNull Class generate(@NonNull IModule module) throws MetaschemaException; } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/JavaCompilerSupport.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/JavaCompilerSupport.java index d08f746cb..139c37d58 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/JavaCompilerSupport.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/JavaCompilerSupport.java @@ -25,6 +25,14 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Provides support for compiling Java source files using the system Java + * compiler. + *

+ * This class wraps the {@link javax.tools.JavaCompiler} API to provide a + * simplified interface for compiling generated Java source files. It supports + * configuring the classpath, module path, and output directory. + */ public class JavaCompilerSupport { @Nullable private Logger logger; @@ -37,43 +45,91 @@ public class JavaCompilerSupport { @NonNull private final Set rootModuleNames = new LinkedHashSet<>(); + /** + * Construct a new compiler support instance. + * + * @param classDir + * the directory where compiled class files will be written + */ public JavaCompilerSupport(@NonNull Path classDir) { this.classDir = classDir; } + /** + * Get the configured classpath entries. + * + * @return the classpath entries + */ public Set getClassPath() { return classPath; } + /** + * Get the configured module path entries. + * + * @return the module path entries + */ public Set getModulePath() { return modulePath; } + /** + * Get the configured root module names. + * + * @return the root module names + */ public Set getRootModuleNames() { return rootModuleNames; } + /** + * Add an entry to the classpath. + * + * @param entry + * the classpath entry to add + */ public void addToClassPath(@NonNull String entry) { classPath.add(entry); } + /** + * Add an entry to the module path. + * + * @param entry + * the module path entry to add + */ public void addToModulePath(@NonNull String entry) { modulePath.add(entry); } + /** + * Add a root module name. + * + * @param entry + * the root module name to add + */ public void addRootModule(@NonNull String entry) { rootModuleNames.add(entry); } + /** + * Set the logger for compilation messages. + * + * @param logger + * the logger to use + */ public void setLogger(@NonNull Logger logger) { this.logger = logger; } + /** + * Generate the compiler options based on the current configuration. + * + * @return the list of compiler options + */ @NonNull protected List generateCompilerOptions() { List options = new LinkedList<>(); - // options.add("-verbose"); - // options.add("-g"); options.add("-d"); options.add(classDir.toString()); @@ -93,11 +149,11 @@ protected List generateCompilerOptions() { } /** - * Generate and compile Java classes. + * Compile the provided Java source files. * * @param classFiles - * the files to compile - * @return information about the generated classes + * the source files to compile + * @return information about the compilation result * @throws IOException * if an error occurred while compiling the classes * @throws IllegalArgumentException @@ -105,7 +161,6 @@ protected List generateCompilerOptions() { * compilation units are of other kind than * {@link javax.tools.JavaFileObject.Kind#SOURCE} */ - public CompilationResult compile(@NonNull List classFiles) throws IOException { DiagnosticCollector diagnostics = new DiagnosticCollector<>(); @@ -149,6 +204,9 @@ public CompilationResult compile(@NonNull List classFiles) throws IOExcept } } + /** + * Contains the result of a compilation operation. + */ public static final class CompilationResult { private final boolean successful; @NonNull @@ -159,22 +217,57 @@ private CompilationResult(boolean successful, @NonNull DiagnosticCollector getDiagnostics() { return diagnostics; } } + /** + * A logging interface for compilation messages. + */ public interface Logger { + /** + * Check if debug logging is enabled. + * + * @return {@code true} if debug logging is enabled + */ boolean isDebugEnabled(); + /** + * Check if info logging is enabled. + * + * @return {@code true} if info logging is enabled + */ boolean isInfoEnabled(); + /** + * Log a debug message. + * + * @param msg + * the message to log + */ void debug(String msg); + /** + * Log an info message. + * + * @param msg + * the message to log + */ void info(String msg); } } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/PackageMetadata.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/PackageMetadata.java index e305fd577..02305c5d9 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/PackageMetadata.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/PackageMetadata.java @@ -11,6 +11,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Tracks metadata about a Java package during code generation. + *

+ * This class aggregates information about generated module classes that share + * the same package name, ensuring consistent XML namespace association. + */ class PackageMetadata { @NonNull private final String packageName; @@ -19,27 +25,57 @@ class PackageMetadata { @NonNull private final List moduleProductions = new LinkedList<>(); + /** + * Construct package metadata based on an initial module production. + * + * @param moduleProduction + * the first module production for this package + */ public PackageMetadata(@NonNull IGeneratedModuleClass moduleProduction) { packageName = moduleProduction.getPackageName(); xmlNamespace = moduleProduction.getModule().getXmlNamespace(); moduleProductions.add(moduleProduction); } + /** + * Get the Java package name. + * + * @return the package name + */ @NonNull protected String getPackageName() { return packageName; } + /** + * Get the XML namespace associated with this package. + * + * @return the XML namespace URI + */ @NonNull protected URI getXmlNamespace() { return xmlNamespace; } + /** + * Get the module productions associated with this package. + * + * @return the list of module productions + */ @NonNull protected List getModuleProductions() { return moduleProductions; } + /** + * Add a module production to this package. + * + * @param moduleProduction + * the module production to add + * @throws IllegalStateException + * if the module's XML namespace does not match the package's + * namespace + */ public void addModule(@NonNull IGeneratedModuleClass moduleProduction) { URI nextXmlNamespace = moduleProduction.getModule().getXmlNamespace(); if (!xmlNamespace.equals(nextXmlNamespace)) { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/PackageProductionImpl.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/PackageProductionImpl.java index c50c188d9..5d6789e7a 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/PackageProductionImpl.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/PackageProductionImpl.java @@ -14,12 +14,28 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; +/** + * Default implementation of {@link IPackageProduction} representing a generated + * package-info.java class. + */ class PackageProductionImpl implements IPackageProduction { @NonNull private final URI xmlNamespace; @NonNull private final IGeneratedClass packageInfoClass; + /** + * Construct a new package production. + * + * @param metadata + * the package metadata + * @param classFactory + * the class factory to use for generating the package-info class + * @param targetDirectory + * the directory to generate the class in + * @throws IOException + * if an error occurs during class generation + */ @SuppressFBWarnings(value = "CT_CONSTRUCTOR_THROW", justification = "Use of final fields") public PackageProductionImpl( @NonNull PackageMetadata metadata, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/ProductionImpl.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/ProductionImpl.java index 2e6705493..4668dbf44 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/ProductionImpl.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/ProductionImpl.java @@ -21,6 +21,10 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Default implementation of {@link IProduction} that tracks generated classes + * for modules and packages. + */ class ProductionImpl implements IProduction { @NonNull @@ -30,6 +34,18 @@ class ProductionImpl implements IProduction { private final Map packageNameToProductionMap // NOPMD - immutable = new HashMap<>(); + /** + * Add a module and its imports to this production. + * + * @param module + * the module to add + * @param classFactory + * the class factory to use for generation + * @param targetDirectory + * the target directory for generated classes + * @throws IOException + * if an error occurs during generation + */ public void addModule( @NonNull IModule module, @NonNull IMetaschemaClassFactory classFactory, @@ -45,6 +61,19 @@ public void addModule( } } + /** + * Add a package to this production. + * + * @param metadata + * the package metadata + * @param classFactory + * the class factory to use for generation + * @param targetDirectory + * the target directory for generated classes + * @return the generated package production + * @throws IOException + * if an error occurs during generation + */ protected IPackageProduction addPackage( @NonNull PackageMetadata metadata, @NonNull IMetaschemaClassFactory classFactory, @@ -67,6 +96,11 @@ public Collection getModuleProductions() { return Collections.unmodifiableCollection(moduleToProductionMap.values()); } + /** + * Get all package productions in this production. + * + * @return an unmodifiable collection of package productions + */ @SuppressWarnings("null") @NonNull protected Collection getPackageProductions() { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/impl/DefaultGeneratedModuleClass.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/impl/DefaultGeneratedModuleClass.java index 8bfc6fabf..d51b430f5 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/impl/DefaultGeneratedModuleClass.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/impl/DefaultGeneratedModuleClass.java @@ -20,6 +20,10 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Contains information about a generated class representing a Metaschema + * module. + */ public class DefaultGeneratedModuleClass extends DefaultGeneratedClass implements IGeneratedModuleClass { @@ -30,6 +34,20 @@ public class DefaultGeneratedModuleClass @NonNull private final String packageName; + /** + * Construct a new generated module class. + * + * @param module + * the Metaschema module this class represents + * @param className + * the type info for the generated class + * @param classFile + * the file the class was written to + * @param definitionClassMap + * a map of definitions to their generated classes + * @param packageName + * the Java package name for this module + */ public DefaultGeneratedModuleClass( @NonNull IModule module, @NonNull ClassName className, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/impl/package-info.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/impl/package-info.java index 66426cda3..07425c9f0 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/impl/package-info.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/impl/package-info.java @@ -3,4 +3,15 @@ * SPDX-License-Identifier: CC0-1.0 */ +/** + * Provides default implementations for generated class representations. + *

+ * This package contains implementation classes for tracking generated Java + * source files, including module classes, definition classes, and supporting + * utilities for annotation generation. + * + * @see gov.nist.secauto.metaschema.databind.codegen.IGeneratedClass + * @see gov.nist.secauto.metaschema.databind.codegen.IGeneratedModuleClass + */ + package gov.nist.secauto.metaschema.databind.codegen.impl; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/IMetaschemaClassFactory.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/IMetaschemaClassFactory.java index c9cadafca..69c31b7b6 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/IMetaschemaClassFactory.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/IMetaschemaClassFactory.java @@ -18,6 +18,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A factory for generating Java classes from Metaschema modules and + * definitions. + *

+ * This interface provides methods for generating module classes, definition + * classes, and package-info classes based on Metaschema constructs. + */ public interface IMetaschemaClassFactory { /** * Get a new instance of the default class generation factory that uses the diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/ITypeInfo.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/ITypeInfo.java index 4889f452d..2c46afb42 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/ITypeInfo.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/ITypeInfo.java @@ -11,7 +11,19 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides type information for a Java property generated from a Metaschema + * construct. + *

+ * This interface defines methods for retrieving names and types used when + * generating Java code for Metaschema elements. + */ public interface ITypeInfo { + /** + * Get the parent definition type info that contains this type. + * + * @return the parent type info + */ @NonNull IDefinitionTypeInfo getParentTypeInfo(); diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/ITypeResolver.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/ITypeResolver.java index b9936b8a5..89dd17831 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/ITypeResolver.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/ITypeResolver.java @@ -28,6 +28,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Resolves type information for Metaschema constructs. + *

+ * This interface provides methods for resolving Java class names, package + * names, and type information for Metaschema modules, definitions, and + * instances. + */ public interface ITypeResolver { /** * Construct a new type resolver using the default implementation. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/IDefinitionTypeInfo.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/IDefinitionTypeInfo.java index 86b202f1f..fee78b228 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/IDefinitionTypeInfo.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/IDefinitionTypeInfo.java @@ -16,6 +16,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Provides type information for a Metaschema definition. + *

+ * This interface provides access to type resolution and instance information + * for generating Java classes from Metaschema definitions. + */ public interface IDefinitionTypeInfo { /** * Get the definition associated with this type info. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/IModelDefinitionTypeInfo.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/IModelDefinitionTypeInfo.java index 8b039deff..d23aff668 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/IModelDefinitionTypeInfo.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/IModelDefinitionTypeInfo.java @@ -20,6 +20,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Provides type information for a Metaschema model definition. + *

+ * This interface extends {@link IDefinitionTypeInfo} to provide additional type + * information specific to model definitions, including class names, base + * classes, and flag instances. + */ public interface IModelDefinitionTypeInfo extends IDefinitionTypeInfo { /** * Construct a new type information object for the provided {@code definition}. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/package-info.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/package-info.java index cd1639437..e88dd3d6d 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/package-info.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/def/package-info.java @@ -3,4 +3,16 @@ * SPDX-License-Identifier: CC0-1.0 */ +/** + * Provides type information for Metaschema definition elements during code + * generation. + *

+ * This package contains interfaces and implementations for representing Java + * type information for Metaschema assembly and field definitions, enabling the + * generation of corresponding Java classes. + * + * @see gov.nist.secauto.metaschema.databind.codegen.typeinfo.def.IDefinitionTypeInfo + * @see gov.nist.secauto.metaschema.databind.codegen.typeinfo.def.IModelDefinitionTypeInfo + */ + package gov.nist.secauto.metaschema.databind.codegen.typeinfo.def; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/package-info.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/package-info.java index 81db21603..cb598bf17 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/package-info.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/codegen/typeinfo/package-info.java @@ -3,4 +3,16 @@ * SPDX-License-Identifier: CC0-1.0 */ +/** + * Provides type information for Metaschema model elements during code + * generation. + *

+ * This package contains interfaces and implementations for resolving and + * representing Java type information for Metaschema definitions and instances, + * including flags, fields, assemblies, and choice groups. + * + * @see gov.nist.secauto.metaschema.databind.codegen.typeinfo.ITypeResolver + * @see gov.nist.secauto.metaschema.databind.codegen.typeinfo.IMetaschemaClassFactory + */ + package gov.nist.secauto.metaschema.databind.codegen.typeinfo; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/AbstractSerializationBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/AbstractSerializationBase.java index e3a27f223..633d1ec17 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/AbstractSerializationBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/AbstractSerializationBase.java @@ -15,6 +15,16 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Abstract base class for serializers and deserializers that provides common + * configuration management functionality. + *

+ * This class maintains a reference to the bound assembly definition and manages + * configuration features that control serialization/deserialization behavior. + * + * @param + * the type of configuration feature this class manages + */ @SuppressWarnings("PMD.ReplaceVectorWithList") // false positive abstract class AbstractSerializationBase> implements IMutableConfiguration { @@ -23,6 +33,12 @@ abstract class AbstractSerializationBase> @NonNull private final DefaultConfiguration configuration; + /** + * Construct a new serialization base with the provided definition. + * + * @param definition + * the bound assembly definition describing the data structure + */ protected AbstractSerializationBase(@NonNull IBoundDefinitionModelAssembly definition) { this.definition = definition; this.configuration = new DefaultConfiguration<>(); @@ -49,6 +65,15 @@ protected IBoundDefinitionModelAssembly getDefinition() { return definition; } + /** + * Callback method invoked when the configuration has been changed. + *

+ * Subclasses can override this method to handle configuration changes, such as + * resetting cached factory instances. + * + * @param config + * the updated configuration + */ @SuppressWarnings("unused") protected void configurationChanged(@NonNull IMutableConfiguration config) { // do nothing by default. Methods can override this to deal with factory caching diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/DeserializationFeature.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/DeserializationFeature.java index d25ce12dc..9794fb1ca 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/DeserializationFeature.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/DeserializationFeature.java @@ -10,10 +10,27 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Configuration features that control the deserialization behavior of + * Metaschema-bound object readers. + *

+ * Each feature has a default value that can be overridden when configuring a + * deserializer. + * + * @param + * the value type of the configuration feature + */ @SuppressWarnings("PMD.DataClass") // not a data class public final class DeserializationFeature extends AbstractConfigurationFeature { + /** + * The default maximum number of codepoints that can be read from a YAML + * document. + */ public static final int YAML_CODEPOINT_LIMIT_DEFAULT = Integer.MAX_VALUE - 1; // 2 GB + /** + * The default number of bytes used for format detection lookahead. + */ public static final int FORMAT_DETECTION_LOOKAHEAD = 32_768; // 2 GB /** @@ -71,6 +88,16 @@ public final class DeserializationFeature public static final DeserializationFeature DESERIALIZE_VALIDATE_REQUIRED_FIELDS = new DeserializationFeature<>("validate-required-fields", Boolean.class, true); + /** + * Construct a new deserialization feature. + * + * @param name + * the feature name used for identification + * @param valueClass + * the class of the feature value type + * @param defaultValue + * the default value for this feature + */ private DeserializationFeature( @NonNull String name, @NonNull Class valueClass, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/SerializationFeature.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/SerializationFeature.java index 405a097b6..1e0f581f7 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/SerializationFeature.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/SerializationFeature.java @@ -9,6 +9,16 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Configuration features that control the serialization behavior of + * Metaschema-bound object writers. + *

+ * Each feature has a default value that can be overridden when configuring a + * serializer. + * + * @param + * the value type of the configuration feature + */ public final class SerializationFeature extends AbstractConfigurationFeature { /** @@ -21,11 +31,20 @@ public final class SerializationFeature public static final SerializationFeature SERIALIZE_ROOT = new SerializationFeature<>("serialize-root", Boolean.class, true); + /** + * Construct a new serialization feature. + * + * @param name + * the feature name used for identification + * @param valueClass + * the class of the feature value type + * @param defaultValue + * the default value for this feature + */ private SerializationFeature( @NonNull String name, @NonNull Class valueClass, @NonNull V defaultValue) { super(name, valueClass, defaultValue); } - } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/DefaultJsonSerializer.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/DefaultJsonSerializer.java index 30e8b6ab3..6ebc99b67 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/DefaultJsonSerializer.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/DefaultJsonSerializer.java @@ -22,6 +22,16 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Provides support for serializing bound Java objects to JSON format based on a + * Metaschema module definition. + *

+ * This serializer uses Jackson's {@link JsonGenerator} to produce JSON output + * that conforms to the Metaschema-defined data structure. + * + * @param + * the Java type of the bound object to be serialized + */ public class DefaultJsonSerializer extends AbstractSerializer { private Lazy factory; @@ -39,6 +49,12 @@ public DefaultJsonSerializer(@NonNull IBoundDefinitionModelAssembly definition) resetFactory(); } + /** + * Resets the JSON factory to use a freshly created instance. + *

+ * This method is called when the serializer configuration changes to ensure the + * factory reflects the current settings. + */ protected final void resetFactory() { this.factory = Lazy.of(this::newFactoryInstance); } @@ -62,11 +78,25 @@ protected JsonFactory newFactoryInstance() { return JsonFactoryFactory.instance(); } + /** + * Get the configured JSON factory instance. + * + * @return the JSON factory used to create JSON generators + */ @NonNull private JsonFactory getJsonFactory() { return ObjectUtils.notNull(factory.get()); } + /** + * Create a new JSON generator for writing to the provided writer. + * + * @param writer + * the writer to send JSON output to + * @return a new JSON generator configured with pretty printing + * @throws IOException + * if an error occurs while creating the generator + */ @SuppressWarnings("resource") @NonNull private JsonGenerator newJsonGenerator(@NonNull Writer writer) throws IOException { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/IJsonParsingContext.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/IJsonParsingContext.java index 1446975b4..e93d655f4 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/IJsonParsingContext.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/IJsonParsingContext.java @@ -10,9 +10,22 @@ import gov.nist.secauto.metaschema.databind.io.IParsingContext; import gov.nist.secauto.metaschema.databind.model.info.IItemReadHandler; +/** + * Provides the parsing context for reading JSON-based Metaschema module + * instances. + *

+ * This interface extends {@link IParsingContext} with JSON-specific reader and + * problem handler types. + * + * @see JsonParser + * @see IJsonProblemHandler + */ public interface IJsonParsingContext extends IParsingContext { // no additional methods + /** + * A reader for processing JSON instances using the item read handler pattern. + */ interface IInstanceReader extends IItemReadHandler { // no additional methods } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/IJsonWritingContext.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/IJsonWritingContext.java index 39fe5c314..c82872107 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/IJsonWritingContext.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/IJsonWritingContext.java @@ -9,6 +9,14 @@ import gov.nist.secauto.metaschema.databind.io.IWritingContext; +/** + * Provides the writing context for serializing Java objects to JSON format. + *

+ * This interface extends {@link IWritingContext} with a JSON-specific writer + * type. + * + * @see JsonGenerator + */ public interface IJsonWritingContext extends IWritingContext { // no additional methods } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/JsonFactoryFactory.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/JsonFactoryFactory.java index f5982f28c..feadc67f8 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/JsonFactoryFactory.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/JsonFactoryFactory.java @@ -12,10 +12,21 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A factory for creating and configuring {@link JsonFactory} instances with + * standard Metaschema settings. + *

+ * This class provides a singleton factory instance configured for optimal use + * with Metaschema data binding operations. The factory is configured to not + * auto-close streams and includes a default codec. + */ public final class JsonFactoryFactory { @NonNull private static final JsonFactory SINGLETON = newJsonFactoryInstance(); + /** + * Private constructor to prevent instantiation. + */ private JsonFactoryFactory() { // disable construction } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/MetaschemaJsonUtil.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/MetaschemaJsonUtil.java index 38ac006f2..3fe093257 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/MetaschemaJsonUtil.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/MetaschemaJsonUtil.java @@ -25,8 +25,17 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Utility methods for processing Metaschema-based JSON data. + *

+ * This class provides helper methods for generating mappings between JSON + * property names and their corresponding Metaschema model instances. + */ final class MetaschemaJsonUtil { + /** + * Private constructor to prevent instantiation. + */ private MetaschemaJsonUtil() { // disable construction } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/MetaschemaJsonWriter.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/MetaschemaJsonWriter.java index 4e222f2d2..c5cac6bdf 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/MetaschemaJsonWriter.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/MetaschemaJsonWriter.java @@ -35,6 +35,17 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides support for writing Metaschema-bound Java objects to JSON format. + *

+ * This class implements the {@link IItemWriteHandler} interface to serialize + * bound objects to JSON using Jackson's {@link JsonGenerator}. It handles + * flags, fields, assemblies, and choice groups according to the Metaschema JSON + * serialization rules. + * + * @see IJsonWritingContext + * @see JsonGenerator + */ @SuppressWarnings("PMD.CouplingBetweenObjects") public class MetaschemaJsonWriter implements IJsonWritingContext, IItemWriteHandler { @NonNull diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/package-info.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/package-info.java index 485293198..a592f08c8 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/package-info.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/json/package-info.java @@ -4,7 +4,23 @@ */ /** - * Supports reading and writing JSON instance data. + * Provides support for reading and writing Metaschema instance data in JSON + * format. + *

+ * This package contains JSON-specific implementations of the serialization and + * deserialization interfaces, including: + *

    + *
  • JSON deserializer for reading JSON into bound objects
    • + *
  • JSON serializer for writing bound objects to JSON
    • + *
  • JSON-specific problem handlers for error recovery
    • + *
  • JSON parsing and writing context interfaces
    • + *
+ *

+ * The JSON implementation uses Jackson for JSON processing. + * + * @see gov.nist.secauto.metaschema.databind.io.json.DefaultJsonDeserializer + * @see gov.nist.secauto.metaschema.databind.io.json.DefaultJsonSerializer + * @see gov.nist.secauto.metaschema.databind.io.json.IJsonProblemHandler */ package gov.nist.secauto.metaschema.databind.io.json; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/package-info.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/package-info.java index e4f745e37..8bfdf5142 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/package-info.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/package-info.java @@ -4,8 +4,22 @@ */ /** - * Provides core functionality for reading and writing instance data to and from - * bound objects. + * Provides core functionality for reading and writing Metaschema instance data + * to and from bound Java objects. + *

+ * This package contains the serialization and deserialization infrastructure + * for Metaschema-based data binding, including: + *

    + *
  • Abstract base classes for serializers and deserializers
    • + *
  • Configuration features for controlling serialization behavior
    • + *
  • Format detection and model detection utilities
    • + *
  • Problem handling interfaces for customizing error recovery
    • + *
+ * + * @see gov.nist.secauto.metaschema.databind.io.ISerializer + * @see gov.nist.secauto.metaschema.databind.io.IDeserializer + * @see gov.nist.secauto.metaschema.databind.io.IBoundLoader + * @see gov.nist.secauto.metaschema.databind.io.Format */ package gov.nist.secauto.metaschema.databind.io; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/CommentFilter.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/CommentFilter.java index 7ebc31386..0078cf41b 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/CommentFilter.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/CommentFilter.java @@ -9,6 +9,12 @@ import javax.xml.stream.XMLStreamConstants; import javax.xml.stream.events.XMLEvent; +/** + * An XML event filter that excludes comment events from the event stream. + *

+ * This filter is used during XML parsing to skip over comment nodes, allowing + * the parser to focus only on meaningful content. + */ public class CommentFilter implements EventFilter { @Override diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/DefaultXmlSerializer.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/DefaultXmlSerializer.java index c11742411..b7e5706f3 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/DefaultXmlSerializer.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/DefaultXmlSerializer.java @@ -27,6 +27,16 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Provides support for serializing bound Java objects to XML format based on a + * Metaschema module definition. + *

+ * This serializer uses StAX's {@link XMLStreamWriter2} to produce XML output + * that conforms to the Metaschema-defined data structure. + * + * @param + * the Java type of the bound object to be serialized + */ public class DefaultXmlSerializer extends AbstractSerializer { private Lazy factory; @@ -44,6 +54,12 @@ public DefaultXmlSerializer(@NonNull IBoundDefinitionModelAssembly definition) { resetFactory(); } + /** + * Resets the XML output factory to use a freshly created instance. + *

+ * This method is called when the serializer configuration changes to ensure the + * factory reflects the current settings. + */ protected final void resetFactory() { this.factory = Lazy.of(this::newFactoryInstance); } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/IXmlWritingContext.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/IXmlWritingContext.java index baf315091..056842d75 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/IXmlWritingContext.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/IXmlWritingContext.java @@ -15,7 +15,25 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides the writing context for serializing Java objects to XML format. + *

+ * This interface extends {@link IWritingContext} with an XML-specific writer + * type and adds a method for writing root elements. + * + * @see XMLStreamWriter2 + */ public interface IXmlWritingContext extends IWritingContext { + /** + * Write the root element for the provided definition and bound object. + * + * @param definition + * the assembly definition describing the root element + * @param item + * the bound object to serialize as the root element + * @throws IOException + * if an error occurs during writing + */ void writeRoot( @NonNull IBoundDefinitionModelAssembly definition, @NonNull IBoundObject item) throws IOException; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/MetaschemaXmlWriter.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/MetaschemaXmlWriter.java index 90a70e0db..56e2af0d5 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/MetaschemaXmlWriter.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/MetaschemaXmlWriter.java @@ -37,6 +37,17 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Provides support for writing Metaschema-bound Java objects to XML format. + *

+ * This class implements the {@link IXmlWritingContext} interface to serialize + * bound objects to XML using StAX's {@link XMLStreamWriter2}. It handles flags + * as attributes and fields/assemblies as child elements according to the + * Metaschema XML serialization rules. + * + * @see IXmlWritingContext + * @see XMLStreamWriter2 + */ public class MetaschemaXmlWriter implements IXmlWritingContext { @NonNull private final XMLStreamWriter2 writer; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/package-info.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/package-info.java index 6b3b59546..2c0c90701 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/package-info.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/xml/package-info.java @@ -4,7 +4,24 @@ */ /** - * Supports reading and writing XML instance data. + * Provides support for reading and writing Metaschema instance data in XML + * format. + *

+ * This package contains XML-specific implementations of the serialization and + * deserialization interfaces, including: + *

    + *
  • XML deserializer for reading XML into bound objects
    • + *
  • XML serializer for writing bound objects to XML
    • + *
  • XML-specific problem handlers for error recovery
    • + *
  • XML parsing and writing context interfaces
    • + *
+ *

+ * The XML implementation uses StAX (Streaming API for XML) for XML processing, + * specifically the Woodstox implementation. + * + * @see gov.nist.secauto.metaschema.databind.io.xml.DefaultXmlDeserializer + * @see gov.nist.secauto.metaschema.databind.io.xml.DefaultXmlSerializer + * @see gov.nist.secauto.metaschema.databind.io.xml.IXmlProblemHandler */ package gov.nist.secauto.metaschema.databind.io.xml; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/metapath/function/DatabindFunctionLibrary.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/metapath/function/DatabindFunctionLibrary.java index 45dd6ed93..e262f1bc5 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/metapath/function/DatabindFunctionLibrary.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/metapath/function/DatabindFunctionLibrary.java @@ -7,6 +7,12 @@ import gov.nist.secauto.metaschema.core.metapath.function.FunctionLibrary; +/** + * Function library providing databind-specific Metapath functions. + *

+ * This library registers functions that are specific to the data binding layer, + * such as the model() function for accessing module information. + */ public class DatabindFunctionLibrary extends FunctionLibrary { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/metapath/function/Model.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/metapath/function/Model.java index 0a4dc2ad5..958826846 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/metapath/function/Model.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/metapath/function/Model.java @@ -23,6 +23,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Implementation of the model() Metapath function. + *

+ * This function provides access to module model information during Metapath + * evaluation in the context of data binding operations. + */ public final class Model { @NonNull static final IFunction SIGNATURE = IFunction.builder() diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/AbstractBoundModule.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/AbstractBoundModule.java index 2164cfd93..9a67ebd6f 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/AbstractBoundModule.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/AbstractBoundModule.java @@ -28,6 +28,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * An abstract base class for Metaschema modules bound to Java classes. + *

+ * This class provides the common implementation for modules that are defined + * through Java annotations on classes, enabling data binding between Metaschema + * module definitions and Java objects. + */ public abstract class AbstractBoundModule extends AbstractModule< IBoundModule, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundDefinition.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundDefinition.java index 7b9660e3f..463b4752e 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundDefinition.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundDefinition.java @@ -7,6 +7,12 @@ import gov.nist.secauto.metaschema.core.model.IDefinition; +/** + * A Metaschema definition (flag, field, or assembly) bound to Java data. + *

+ * This interface combines the bound model element capabilities with the core + * Metaschema definition interface. + */ public interface IBoundDefinition extends IBoundModelElement, IDefinition { // no additional methods } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundFieldValue.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundFieldValue.java index e416d3f3d..e83597fcf 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundFieldValue.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundFieldValue.java @@ -18,6 +18,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Represents the bound value of a field definition. + *

+ * This interface provides access to the scalar value within a field, including + * support for JSON value key handling and default values. + */ public interface IBoundFieldValue extends IFeatureScalarItemValueHandler, IBoundProperty { @Override @Nullable diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundInstanceModelField.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundInstanceModelField.java index 572d6dc31..1b2c9f620 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundInstanceModelField.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundInstanceModelField.java @@ -19,6 +19,15 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Represents a field instance bound to a Java field. + *

+ * This interface handles both scalar (simple type) and complex (class-bound) + * field instances. + * + * @param + * the Java type for associated bound objects + */ public interface IBoundInstanceModelField extends IBoundInstanceModelNamed, IFieldInstanceAbsolute { @Override diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundModelElement.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundModelElement.java index 8936d837f..d38c061d4 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundModelElement.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundModelElement.java @@ -7,6 +7,12 @@ import gov.nist.secauto.metaschema.core.model.IModelElement; +/** + * A Metaschema model element bound to Java data. + *

+ * This interface extends the core model element interface to provide access to + * the containing bound module. + */ public interface IBoundModelElement extends IModelElement { @Override diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundProperty.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundProperty.java index d4661a4a3..37b5fa995 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundProperty.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/IBoundProperty.java @@ -11,6 +11,15 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Represents a bound property on a Metaschema definition. + *

+ * A bound property combines the model object binding with Java field access and + * JSON naming capabilities. + * + * @param + * the Java type for associated bound objects + */ public interface IBoundProperty extends IBoundModelObject, IFeatureJavaField, IJsonNamed { /** * Copy this instance from one parent object to another. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/annotations/ModelUtil.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/annotations/ModelUtil.java index 663d12a74..91cd46d25 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/annotations/ModelUtil.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/annotations/ModelUtil.java @@ -30,6 +30,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Utility methods for processing Metaschema binding annotations. + *

+ * This class provides helper methods for extracting and interpreting annotation + * values from Java classes and fields. + */ public final class ModelUtil { // TODO: replace NO_STRING_VALUE with NULL_VALUE where possible. URIs will not // allow NULL_VALUE. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/AbstractBoundDefinitionModelComplex.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/AbstractBoundDefinitionModelComplex.java index 32b36e4bc..27641dee3 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/AbstractBoundDefinitionModelComplex.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/AbstractBoundDefinitionModelComplex.java @@ -23,6 +23,16 @@ import edu.umd.cs.findbugs.annotations.Nullable; import nl.talsmasoftware.lazy4j.Lazy; +/** + * An abstract base implementation of a complex model definition bound to a Java + * class. + *

+ * This class provides the common implementation for field and assembly + * definitions that are bound to Java classes through annotations. + * + * @param + * the annotation type used to configure the definition + */ public abstract class AbstractBoundDefinitionModelComplex implements IBoundDefinitionModelComplex { @NonNull diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/BoundInstanceModelChoice.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/BoundInstanceModelChoice.java index c11da7a92..c04364c92 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/BoundInstanceModelChoice.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/BoundInstanceModelChoice.java @@ -31,6 +31,12 @@ * is used for annotation-based bindings (classes with {@code @BoundChoice} * annotations). */ +/** + * Implementation of a choice instance within a bound model. + *

+ * This class represents a choice between multiple model instances in a + * Metaschema assembly. + */ public final class BoundInstanceModelChoice extends AbstractChoiceInstance< IBoundDefinitionModelAssembly, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/ClassIntrospector.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/ClassIntrospector.java index b24a8fbf3..17bb9ca12 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/ClassIntrospector.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/ClassIntrospector.java @@ -10,6 +10,12 @@ import java.util.LinkedList; import java.util.List; +/** + * Utility class for introspecting Java classes bound to Metaschema definitions. + *

+ * This class provides methods to analyze class hierarchies and extract + * binding-related information from annotated classes. + */ public final class ClassIntrospector { private ClassIntrospector() { // disable construction diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/ConstraintSupport.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/ConstraintSupport.java index ce5fabf8d..650442c20 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/ConstraintSupport.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/ConstraintSupport.java @@ -16,6 +16,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Support class for managing constraints on bound definitions. + *

+ * This class provides utilities for processing and applying constraints defined + * through binding annotations. + */ public final class ConstraintSupport { private ConstraintSupport() { // disable construction diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/DefaultGroupAs.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/DefaultGroupAs.java index c164e3673..ad3fb5ce8 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/DefaultGroupAs.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/DefaultGroupAs.java @@ -17,6 +17,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; +/** + * Default implementation of {@link IGroupAs} for bound model instances. + *

+ * This class represents the group-as configuration for collection-type model + * instances, including the qualified name and grouping behaviors for XML and + * JSON serialization. + */ public class DefaultGroupAs implements IGroupAs { @NonNull private final IEnhancedQName qname; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/IFeatureInstanceModelGroupAs.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/IFeatureInstanceModelGroupAs.java index e4d501312..8d690a444 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/IFeatureInstanceModelGroupAs.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/IFeatureInstanceModelGroupAs.java @@ -13,6 +13,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A feature interface for model instances that support group-as configuration. + *

+ * This interface provides access to the group-as settings that control how + * collections of model instances are serialized in XML and JSON. + */ public interface IFeatureInstanceModelGroupAs extends IGroupable { /** * Get the underlying group-as provider. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelAssemblyComplex.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelAssemblyComplex.java index 9d88db845..5952127ea 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelAssemblyComplex.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelAssemblyComplex.java @@ -39,6 +39,12 @@ * Implements a Metaschema module assembly instance bound to a Java field, * supported by a bound definition class. */ +/** + * Implementation of an assembly instance bound to a Java field. + *

+ * This class handles the binding of a field referencing an assembly definition + * to the containing assembly's model. + */ public final class InstanceModelAssemblyComplex extends AbstractAssemblyInstance< IBoundDefinitionModelAssembly, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelChoiceGroup.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelChoiceGroup.java index e9edf4579..6ccd8c951 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelChoiceGroup.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelChoiceGroup.java @@ -42,6 +42,12 @@ * Implements a Metaschema module choice group instance bound to a Java field. */ @SuppressWarnings("PMD.CouplingBetweenObjects") +/** + * Implementation of a choice group instance bound to a Java field. + *

+ * This class handles the binding of a field that can contain multiple types of + * model instances as members of a choice group. + */ public final class InstanceModelChoiceGroup extends AbstractChoiceGroupInstance< IBoundDefinitionModelAssembly, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelFieldComplex.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelFieldComplex.java index 29a1f1545..274d26969 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelFieldComplex.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelFieldComplex.java @@ -41,6 +41,12 @@ * Implements a Metaschema module field instance bound to a Java field, * supported by a bound definition class. */ +/** + * Implementation of a complex field instance bound to a Java field. + *

+ * This class handles the binding of a field referencing a complex field + * definition (one that can contain flags) to the containing assembly's model. + */ public final class InstanceModelFieldComplex extends AbstractFieldInstance< IBoundDefinitionModelAssembly, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelFieldScalar.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelFieldScalar.java index 5cbeaeb5a..502568c94 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelFieldScalar.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelFieldScalar.java @@ -45,6 +45,12 @@ * Implements a Metaschema module field instance bound to a scalar valued Java * field. */ +/** + * Implementation of a scalar field instance bound to a Java field. + *

+ * This class handles the binding of a field with only a scalar value (no flags) + * to the containing assembly's model. + */ public final class InstanceModelFieldScalar extends AbstractInlineFieldDefinition< IBoundDefinitionModelAssembly, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelGroupedAssembly.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelGroupedAssembly.java index 2efa7fe17..b20e1b5d1 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelGroupedAssembly.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelGroupedAssembly.java @@ -32,6 +32,12 @@ * Represents an assembly model instance that is a member of a choice group * instance. */ +/** + * Implementation of an assembly instance within a choice group. + *

+ * This class represents an assembly that is a member of a choice group, + * allowing polymorphic model content. + */ public class InstanceModelGroupedAssembly extends AbstractAssemblyInstance< IBoundInstanceModelChoiceGroup, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelGroupedFieldComplex.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelGroupedFieldComplex.java index 309a31063..5f072125a 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelGroupedFieldComplex.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/impl/InstanceModelGroupedFieldComplex.java @@ -35,6 +35,12 @@ * Represents an field model instance that is a member of a choice group * instance. */ +/** + * Implementation of a complex field instance within a choice group. + *

+ * This class represents a complex field that is a member of a choice group, + * allowing polymorphic model content. + */ public class InstanceModelGroupedFieldComplex extends AbstractFieldInstance< IBoundInstanceModelChoiceGroup, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceCollectionInfo.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceCollectionInfo.java index d9d1d1d16..14beace2b 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceCollectionInfo.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceCollectionInfo.java @@ -9,6 +9,16 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * An abstract base class for managing collection information for model + * instances. + *

+ * This class provides common functionality for handling collections of items + * during serialization and deserialization. + * + * @param + * the Java type of items in the collection + */ public abstract class AbstractModelInstanceCollectionInfo implements IModelInstanceCollectionInfo { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceReadHandler.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceReadHandler.java index b6df78b43..8d27c0bed 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceReadHandler.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceReadHandler.java @@ -12,6 +12,15 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * An abstract base class for reading model instance collections. + *

+ * This class provides the framework for reading collections of items during + * deserialization, with support for different collection types. + * + * @param + * the Java type of items being read + */ public abstract class AbstractModelInstanceReadHandler implements IModelInstanceReadHandler { @NonNull private final IBoundInstanceModel instance; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceWriteHandler.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceWriteHandler.java index 6c2183d06..734cd9612 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceWriteHandler.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/AbstractModelInstanceWriteHandler.java @@ -15,6 +15,15 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * An abstract base class for writing model instance collections. + *

+ * This class provides the framework for writing collections of items during + * serialization, with support for different collection types. + * + * @param + * the Java type of items being written + */ public abstract class AbstractModelInstanceWriteHandler implements IModelInstanceWriteHandler { @NonNull diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IFeatureComplexItemValueHandler.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IFeatureComplexItemValueHandler.java index 2dd007e4b..0c3c05a86 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IFeatureComplexItemValueHandler.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IFeatureComplexItemValueHandler.java @@ -20,6 +20,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * A feature interface for handling complex item values during binding + * operations. + *

+ * Complex items are bound to Java classes and can contain flags and other + * nested model content. + */ public interface IFeatureComplexItemValueHandler extends IItemValueHandler { /** * Get the Metaschema definition representing the bound complex data. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IFeatureScalarItemValueHandler.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IFeatureScalarItemValueHandler.java index a11feeab9..7477d1563 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IFeatureScalarItemValueHandler.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IFeatureScalarItemValueHandler.java @@ -12,6 +12,13 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * A feature interface for handling scalar item values during binding + * operations. + *

+ * Scalar items have simple values that can be converted directly by a data type + * adapter. + */ public interface IFeatureScalarItemValueHandler extends IItemValueHandler, IValuedMutable { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemReadHandler.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemReadHandler.java index 5140c3792..c524c6a6c 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemReadHandler.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemReadHandler.java @@ -22,6 +22,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Handler interface for reading bound items during deserialization. + *

+ * Implementations of this interface handle the reading of different types of + * model items (flags, fields, assemblies, choice groups). + */ public interface IItemReadHandler { /** * Parse and return an item. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemValueHandler.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemValueHandler.java index cf5631e97..61b4dfc40 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemValueHandler.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemValueHandler.java @@ -20,6 +20,15 @@ * @param * the Java type of the item */ +/** + * Handler interface for processing bound item values. + *

+ * This interface provides methods for reading and writing items, as well as + * deep copying items during binding operations. + * + * @param + * the Java type of the handled item value + */ public interface IItemValueHandler { /** * Parse and return an item. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemWriteHandler.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemWriteHandler.java index 668e56cc9..ee75459af 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemWriteHandler.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IItemWriteHandler.java @@ -21,6 +21,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Handler interface for writing bound items during serialization. + *

+ * Implementations of this interface handle the writing of different types of + * model items (flags, fields, assemblies, choice groups). + */ public interface IItemWriteHandler { /** * Write an item. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceCollectionInfo.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceCollectionInfo.java index 668974bdc..b85d02390 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceCollectionInfo.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceCollectionInfo.java @@ -22,6 +22,15 @@ import edu.umd.cs.findbugs.annotations.Nullable; // REFACTOR: parameterize the item type? +/** + * Provides information about the collection type for a model instance. + *

+ * This interface abstracts the differences between singleton, list, and map + * collection types for model instances. + * + * @param + * the Java type of items in the collection + */ public interface IModelInstanceCollectionInfo { @SuppressWarnings("PMD.ShortMethodName") diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceReadHandler.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceReadHandler.java index f098ce800..9c8663b58 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceReadHandler.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceReadHandler.java @@ -12,6 +12,16 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Handler interface for reading model instance collections during + * deserialization. + *

+ * This interface provides methods for accepting individual items read from a + * stream and combining them into a collection. + * + * @param + * the Java type of items being read + */ public interface IModelInstanceReadHandler { @Nullable default ITEM readSingleton() throws IOException { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceWriteHandler.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceWriteHandler.java index f1b881565..5c603384f 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceWriteHandler.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/IModelInstanceWriteHandler.java @@ -11,6 +11,16 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Handler interface for writing model instance collections during + * serialization. + *

+ * This interface provides methods for iterating over collection items and + * writing them to an output stream. + * + * @param + * the Java type of items being written + */ public interface IModelInstanceWriteHandler { default void writeSingleton(@NonNull ITEM item) throws IOException { writeItem(item); diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/ListCollectionInfo.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/ListCollectionInfo.java index af8af629d..d54071b49 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/ListCollectionInfo.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/ListCollectionInfo.java @@ -19,6 +19,15 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Collection information for list-based model instance collections. + *

+ * This class handles model instances where multiple items are stored in a + * {@link java.util.List}. + * + * @param + * the Java type of items in the list + */ class ListCollectionInfo extends AbstractModelInstanceCollectionInfo { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/MapCollectionInfo.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/MapCollectionInfo.java index 78fc30fc5..a84008866 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/MapCollectionInfo.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/MapCollectionInfo.java @@ -21,6 +21,15 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Collection information for map-based model instance collections. + *

+ * This class handles model instances where items are stored in a + * {@link java.util.Map}, keyed by a JSON key flag value. + * + * @param + * the Java type of items in the map + */ class MapCollectionInfo extends AbstractModelInstanceCollectionInfo { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/SingletonCollectionInfo.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/SingletonCollectionInfo.java index 93ef2af2b..e84953e96 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/SingletonCollectionInfo.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/info/SingletonCollectionInfo.java @@ -17,6 +17,15 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Collection information for singleton model instance values. + *

+ * This class handles model instances with a maximum occurrence of 1, where the + * value is stored directly rather than in a collection. + * + * @param + * the Java type of the singleton item + */ class SingletonCollectionInfo extends AbstractModelInstanceCollectionInfo { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/BindingConstraintLoader.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/BindingConstraintLoader.java index 7419544e6..2edb7b892 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/BindingConstraintLoader.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/BindingConstraintLoader.java @@ -56,6 +56,13 @@ * every use. Any constraint set imported is also loaded and cached * automatically. */ +/** + * Loads Metaschema constraints from external constraint files using data + * binding. + *

+ * This class provides functionality to parse constraint files and apply them to + * Metaschema modules. + */ public class BindingConstraintLoader extends AbstractLoader> implements IConstraintLoader { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/BindingModuleLoader.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/BindingModuleLoader.java index 492f1d37a..65b9d62ea 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/BindingModuleLoader.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/BindingModuleLoader.java @@ -45,6 +45,12 @@ * {@link SimpleModuleLoaderStrategy} initialized using the * {@link DefaultModuleBindingGenerator}. */ +/** + * Loads Metaschema modules from XML or YAML sources using data binding. + *

+ * This class provides functionality to parse Metaschema module files and + * construct the corresponding module model. + */ public class BindingModuleLoader extends AbstractModuleLoader implements IBindingModuleLoader { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingDefinitionModel.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingDefinitionModel.java index 19856f109..bfc9ab992 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingDefinitionModel.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingDefinitionModel.java @@ -7,6 +7,12 @@ import gov.nist.secauto.metaschema.core.model.IModelDefinition; +/** + * Represents a Metaschema model definition loaded via data binding. + *

+ * This interface provides access to the binding-specific metadata for field and + * assembly definitions. + */ public interface IBindingDefinitionModel extends IModelDefinition, IBindingModelElement { // no additional methods } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingDefinitionModelAssembly.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingDefinitionModelAssembly.java index 10712d3ff..a6f6b1418 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingDefinitionModelAssembly.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingDefinitionModelAssembly.java @@ -7,6 +7,12 @@ import gov.nist.secauto.metaschema.core.model.IAssemblyDefinition; +/** + * Represents a Metaschema assembly definition loaded via data binding. + *

+ * This interface provides access to assembly-specific metadata including the + * root name for assemblies that can serve as document roots. + */ public interface IBindingDefinitionModelAssembly extends IBindingDefinitionModel, IAssemblyDefinition { // no additional methods } diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingInstance.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingInstance.java index 3e2d19e26..dd27a9ba9 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingInstance.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingInstance.java @@ -9,6 +9,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Represents a Metaschema instance loaded via data binding. + *

+ * This interface provides access to binding-specific metadata for flag, field, + * and assembly instances. + */ public interface IBindingInstance extends IInstance, IBindingModelElement { @Override @NonNull diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingInstanceModel.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingInstanceModel.java index 6cdb82e44..e151b3432 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingInstanceModel.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingInstanceModel.java @@ -7,6 +7,12 @@ import gov.nist.secauto.metaschema.core.model.IModelInstance; +/** + * Represents a Metaschema model instance loaded via data binding. + *

+ * This interface provides access to binding-specific metadata for field and + * assembly instances. + */ public interface IBindingInstanceModel extends IBindingInstance, IModelInstance { @Override IBindingDefinitionModelAssembly getContainingDefinition(); diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingMetaschemaModule.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingMetaschemaModule.java index c294ad7aa..2831fc767 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingMetaschemaModule.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingMetaschemaModule.java @@ -15,6 +15,12 @@ /** * A Metaschema module represented as binding to Java classes and fields. */ +/** + * Represents a Metaschema module loaded via data binding. + *

+ * This interface provides access to the bound representation of a Metaschema + * module, including its definitions and constraints. + */ public interface IBindingMetaschemaModule extends IMetaschemaModule { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingModelElement.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingModelElement.java index 784cdc413..e4def0c4a 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingModelElement.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingModelElement.java @@ -10,6 +10,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; +/** + * Represents a Metaschema model element loaded via data binding. + *

+ * This interface is the base type for all model elements that are loaded from + * Metaschema source files using data binding. + */ public interface IBindingModelElement extends IModelElement { @Override IBindingMetaschemaModule getContainingModule(); diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingModuleLoader.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingModuleLoader.java index 795b83f71..7de3be385 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingModuleLoader.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingModuleLoader.java @@ -28,6 +28,12 @@ * {@link DefaultModuleBindingGenerator}. * */ +/** + * Loader interface for Metaschema modules using data binding. + *

+ * This interface defines the contract for loading Metaschema modules from + * various sources (files, URIs, etc.) using the data binding layer. + */ public interface IBindingModuleLoader extends IModuleLoader, IMutableConfiguration> { /** diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConfigurableMessageConstraintBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConfigurableMessageConstraintBase.java index 0fbec1dea..5ace1ac1a 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConfigurableMessageConstraintBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConfigurableMessageConstraintBase.java @@ -10,6 +10,12 @@ /** * Represents constraint metadata that is common to all constraints. */ +/** + * Base interface for constraints with configurable messages. + *

+ * This interface provides access to the message configuration for constraints + * that can report custom validation messages. + */ public interface IConfigurableMessageConstraintBase extends IConstraintBase { /** * Get a custom message to use when the constraint is not satisfied. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConstraintBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConstraintBase.java index 444ca08b8..c879b064e 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConstraintBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConstraintBase.java @@ -17,6 +17,12 @@ /** * Represents constraint metadata that is common to all constraints. */ +/** + * Base interface for all constraint bindings. + *

+ * This interface provides access to common constraint properties such as ID, + * level, and formal name. + */ public interface IConstraintBase { /** diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IModelConstraintsBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IModelConstraintsBase.java index 7b7416a0d..5c1af6c87 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IModelConstraintsBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IModelConstraintsBase.java @@ -11,6 +11,12 @@ * Provides a common interface for model (assembly/field) constraint binding * objects. */ +/** + * Base interface for model-level constraint bindings. + *

+ * This interface provides access to constraints that apply to assemblies and + * their model content. + */ public interface IModelConstraintsBase extends IValueConstraintsBase { @Override List getRules(); diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/ITargetedConstraintBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/ITargetedConstraintBase.java index ea7c5173d..0785deda1 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/ITargetedConstraintBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/ITargetedConstraintBase.java @@ -11,6 +11,12 @@ * Represents constraint metadata that is common to all constraints that are * targeted at a specific set of nodes matching the target. */ +/** + * Base interface for targeted constraint bindings. + *

+ * This interface provides access to constraints that target specific nodes + * within a Metaschema model using Metapath expressions. + */ public interface ITargetedConstraintBase extends IConstraintBase { /** * The target to match to determine the nodes to check against the constraint. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueConstraintsBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueConstraintsBase.java index 798264a8f..fb77119e0 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueConstraintsBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueConstraintsBase.java @@ -16,6 +16,12 @@ /** * Provides a common interface for value constraint binding objects. */ +/** + * Base interface for value-level constraint bindings. + *

+ * This interface provides access to constraints that apply to flag and field + * values. + */ public interface IValueConstraintsBase extends IBoundObject { /** * Get the let expressions defined for this constraint set. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueTargetedConstraintsBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueTargetedConstraintsBase.java index 251608a95..859493eea 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueTargetedConstraintsBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueTargetedConstraintsBase.java @@ -10,6 +10,12 @@ /** * Provides a common interface for targeted value constraint binding objects. */ +/** + * Base interface for targeted value constraint bindings. + *

+ * This interface combines targeted and value constraint capabilities for + * constraints that apply to specific value nodes. + */ public interface IValueTargetedConstraintsBase extends IValueConstraintsBase { /** * {@inheritDoc} diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/ModuleLoadingPostProcessor.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/ModuleLoadingPostProcessor.java index 63bd1c109..d013d2e39 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/ModuleLoadingPostProcessor.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/ModuleLoadingPostProcessor.java @@ -16,6 +16,12 @@ * @since 2.0.0 */ @FunctionalInterface +/** + * Post-processor interface for module loading operations. + *

+ * Implementations can perform additional processing on modules after they have + * been loaded, such as applying external constraints. + */ public interface ModuleLoadingPostProcessor { /** * Post-processes the provided Metaschema module. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AbstractAbsoluteModelGenerator.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AbstractAbsoluteModelGenerator.java index 5e5ac46d2..b1837a38f 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AbstractAbsoluteModelGenerator.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AbstractAbsoluteModelGenerator.java @@ -41,6 +41,12 @@ @SuppressWarnings({ "PMD.AbstractClassWithoutAbstractMethod", "PMD.UseConcurrentHashMap" }) +/** + * Abstract base class for generating absolute model structures from bindings. + *

+ * This class provides common functionality for building model containers from + * Metaschema module bindings. + */ public abstract class AbstractAbsoluteModelGenerator< PARENT extends IContainerModelAbsolute, BUILDER extends DefaultChoiceModelBuilder< diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AbstractAllowedValue.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AbstractAllowedValue.java index c823d71d9..95d96360e 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AbstractAllowedValue.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AbstractAllowedValue.java @@ -10,6 +10,12 @@ import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Abstract base class for allowed value implementations. + *

+ * This class provides common functionality for representing individual allowed + * values within an allowed-values constraint. + */ public abstract class AbstractAllowedValue implements IAllowedValue { @Nullable diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AssemblyModelGenerator.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AssemblyModelGenerator.java index cfd7fbd7d..fcfe672b9 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AssemblyModelGenerator.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/AssemblyModelGenerator.java @@ -36,6 +36,12 @@ * This class is not thread safe. */ @SuppressWarnings("PMD.UseConcurrentHashMap") +/** + * Generates assembly model structures from binding data. + *

+ * This class handles the creation of model containers for assembly definitions + * loaded from Metaschema sources. + */ public final class AssemblyModelGenerator extends AbstractAbsoluteModelGenerator< IBindingDefinitionModelAssembly, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/BindingConstants.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/BindingConstants.java index 357811512..9ee6996cd 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/BindingConstants.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/BindingConstants.java @@ -6,6 +6,12 @@ package gov.nist.secauto.metaschema.databind.model.metaschema.impl; // REFACTOR: is this needed/used? +/** + * Constants used throughout the binding implementation. + *

+ * This class defines constant values for default settings and namespace URIs + * used in Metaschema bindings. + */ public final class BindingConstants { public static final String METASCHEMA_ASSEMBLY_REFERENCE_NAME = "assembly"; public static final String METASCHEMA_ASSEMBLY_INLINE_DEFINITION_NAME = "define-assembly"; diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ChoiceGroupModelGenerator.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ChoiceGroupModelGenerator.java index bf85aa8f1..60505af00 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ChoiceGroupModelGenerator.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ChoiceGroupModelGenerator.java @@ -32,6 +32,12 @@ *

* This method isn't thread safe. */ +/** + * Generates choice group model structures from binding data. + *

+ * This class handles the creation of choice group containers for assemblies + * that contain polymorphic model content. + */ public final class ChoiceGroupModelGenerator extends DefaultChoiceGroupModelBuilder< INamedModelInstanceGrouped, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ChoiceModelGenerator.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ChoiceModelGenerator.java index 70dd58999..7809ecee0 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ChoiceModelGenerator.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ChoiceModelGenerator.java @@ -33,6 +33,12 @@ *

* This class is not thread safe. */ +/** + * Generates choice model structures from binding data. + *

+ * This class handles the creation of choice containers for assemblies that + * contain exclusive model alternatives. + */ public final class ChoiceModelGenerator extends AbstractAbsoluteModelGenerator< IContainerModelAbsolute, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ConstraintBindingSupport.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ConstraintBindingSupport.java index ba6339418..af0e0295e 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ConstraintBindingSupport.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ConstraintBindingSupport.java @@ -61,6 +61,12 @@ * Supports parsing constraints declared within a bound object. */ @SuppressWarnings("PMD.CouplingBetweenObjects") +/** + * Support class for building constraints from binding data. + *

+ * This class provides utility methods for converting constraint binding + * representations to constraint model objects. + */ public final class ConstraintBindingSupport { private ConstraintBindingSupport() { // disable construction diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionAssemblyGlobal.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionAssemblyGlobal.java index 54cabd0f0..0ee827d4b 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionAssemblyGlobal.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionAssemblyGlobal.java @@ -40,6 +40,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of a global assembly definition from binding data. + *

+ * This class represents an assembly definition that is declared at the module + * level and can be referenced by instances. + */ public class DefinitionAssemblyGlobal extends AbstractGlobalAssemblyDefinition< IBindingMetaschemaModule, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionFieldGlobal.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionFieldGlobal.java index 037db058e..ff4db556b 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionFieldGlobal.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionFieldGlobal.java @@ -34,6 +34,12 @@ import edu.umd.cs.findbugs.annotations.Nullable; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of a global field definition from binding data. + *

+ * This class represents a field definition that is declared at the module level + * and can be referenced by instances. + */ public class DefinitionFieldGlobal extends AbstractGlobalFieldDefinition implements IBindingDefinitionModel { diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionFlagGlobal.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionFlagGlobal.java index eb434c117..b144dcffd 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionFlagGlobal.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/DefinitionFlagGlobal.java @@ -29,6 +29,12 @@ import edu.umd.cs.findbugs.annotations.Nullable; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of a global flag definition from binding data. + *

+ * This class represents a flag definition that is declared at the module level + * and can be referenced by instances. + */ public class DefinitionFlagGlobal extends AbstractGlobalFlagDefinition { @NonNull diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/FlagContainerSupport.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/FlagContainerSupport.java index 97545c6ea..e766815f3 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/FlagContainerSupport.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/FlagContainerSupport.java @@ -27,6 +27,12 @@ import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; @SuppressWarnings("PMD.OnlyOneReturn") +/** + * Support class for building flag containers from binding data. + *

+ * This class provides utility methods for discovering and organizing flag + * instances from Metaschema module bindings. + */ public final class FlagContainerSupport { @SuppressFBWarnings(value = "CT_CONSTRUCTOR_THROW", justification = "Use of final fields") @NonNull diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceFlagInline.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceFlagInline.java index c3038e651..d7a129ec3 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceFlagInline.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceFlagInline.java @@ -32,6 +32,12 @@ import edu.umd.cs.findbugs.annotations.Nullable; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of an inline flag instance from binding data. + *

+ * This class represents a flag that is defined inline within its containing + * definition rather than as a reference. + */ public class InstanceFlagInline extends AbstractInlineFlagDefinition< IBindingDefinitionModel, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceFlagReference.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceFlagReference.java index 3df4bfad3..c4ca138cd 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceFlagReference.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceFlagReference.java @@ -28,6 +28,12 @@ import edu.umd.cs.findbugs.annotations.Nullable; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of a flag instance reference from binding data. + *

+ * This class represents a reference to a globally defined flag within a + * containing definition. + */ public class InstanceFlagReference extends AbstractFlagInstance< IBindingDefinitionModel, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelAssemblyInline.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelAssemblyInline.java index 5ab22cf0e..0c11c2f07 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelAssemblyInline.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelAssemblyInline.java @@ -45,6 +45,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of an inline assembly instance from binding data. + *

+ * This class represents an assembly that is defined inline within its + * containing assembly rather than as a reference. + */ public class InstanceModelAssemblyInline extends AbstractInlineAssemblyDefinition< IContainerModelAbsolute, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelAssemblyReference.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelAssemblyReference.java index fb2ca3a65..4ac33729b 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelAssemblyReference.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelAssemblyReference.java @@ -29,6 +29,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of an assembly instance reference from binding data. + *

+ * This class represents a reference to a globally defined assembly within a + * containing assembly's model. + */ public class InstanceModelAssemblyReference extends AbstractAssemblyInstance< IContainerModelAbsolute, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelChoice.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelChoice.java index 1a9aed5c7..a5d3fe935 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelChoice.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelChoice.java @@ -25,6 +25,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of a choice instance from binding data. + *

+ * This class represents a choice between exclusive model alternatives within an + * assembly. + */ public class InstanceModelChoice extends AbstractChoiceInstance< IBindingDefinitionModelAssembly, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelChoiceGroup.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelChoiceGroup.java index 86967b960..1b33666c2 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelChoiceGroup.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelChoiceGroup.java @@ -28,6 +28,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of a choice group instance from binding data. + *

+ * This class represents a collection of polymorphic model instances that can + * contain different types of members. + */ public class InstanceModelChoiceGroup extends AbstractChoiceGroupInstance< IBindingDefinitionModelAssembly, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelFieldInline.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelFieldInline.java index 7d0d10bf9..2617a9d08 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelFieldInline.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelFieldInline.java @@ -42,6 +42,12 @@ import edu.umd.cs.findbugs.annotations.Nullable; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of an inline field instance from binding data. + *

+ * This class represents a field that is defined inline within its containing + * assembly rather than as a reference. + */ public class InstanceModelFieldInline extends AbstractInlineFieldDefinition< IContainerModelAbsolute, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelFieldReference.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelFieldReference.java index f2e1b5f51..5a66804dc 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelFieldReference.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelFieldReference.java @@ -30,6 +30,12 @@ import edu.umd.cs.findbugs.annotations.Nullable; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of a field instance reference from binding data. + *

+ * This class represents a reference to a globally defined field within a + * containing assembly's model. + */ public class InstanceModelFieldReference extends AbstractFieldInstance< IContainerModelAbsolute, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedAssemblyInline.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedAssemblyInline.java index e5696bb72..c587a7555 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedAssemblyInline.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedAssemblyInline.java @@ -41,6 +41,11 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of an inline grouped assembly instance from binding data. + *

+ * This class represents an inline assembly member of a choice group. + */ public class InstanceModelGroupedAssemblyInline extends AbstractInlineAssemblyDefinition< IChoiceGroupInstance, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedAssemblyReference.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedAssemblyReference.java index 33e3b83d9..c7c933e0a 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedAssemblyReference.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedAssemblyReference.java @@ -26,6 +26,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of a grouped assembly reference from binding data. + *

+ * This class represents a reference to a global assembly as a member of a + * choice group. + */ public class InstanceModelGroupedAssemblyReference extends AbstractAssemblyInstance< IChoiceGroupInstance, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedFieldInline.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedFieldInline.java index d21da7412..16f093046 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedFieldInline.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedFieldInline.java @@ -38,6 +38,11 @@ import edu.umd.cs.findbugs.annotations.Nullable; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of an inline grouped field instance from binding data. + *

+ * This class represents an inline field member of a choice group. + */ public class InstanceModelGroupedFieldInline extends AbstractInlineFieldDefinition< IChoiceGroupInstance, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedFieldReference.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedFieldReference.java index e699aa9be..df41fdaf3 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedFieldReference.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/InstanceModelGroupedFieldReference.java @@ -26,6 +26,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import nl.talsmasoftware.lazy4j.Lazy; +/** + * Implementation of a grouped field reference from binding data. + *

+ * This class represents a reference to a global field as a member of a choice + * group. + */ public class InstanceModelGroupedFieldReference extends AbstractFieldInstance< IChoiceGroupInstance, diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ModelSupport.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ModelSupport.java index 31f555409..83ba60e7f 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ModelSupport.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/impl/ModelSupport.java @@ -45,6 +45,12 @@ import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.Nullable; +/** + * Utility class providing support methods for model construction. + *

+ * This class provides common utility methods used when building model + * structures from Metaschema bindings. + */ public final class ModelSupport { private ModelSupport() { // disable construction diff --git a/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/AbstractMetaschemaMojo.java b/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/AbstractMetaschemaMojo.java index c22e2b593..d2170bc61 100644 --- a/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/AbstractMetaschemaMojo.java +++ b/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/AbstractMetaschemaMojo.java @@ -47,8 +47,6 @@ import org.apache.maven.plugin.MojoExecutionException; import org.apache.maven.plugin.logging.Log; import org.apache.maven.plugins.annotations.Parameter; - -import javax.inject.Inject; import org.apache.maven.project.MavenProject; import org.codehaus.plexus.util.DirectoryScanner; import org.sonatype.plexus.build.incremental.BuildContext; @@ -74,11 +72,31 @@ import java.util.stream.Collectors; import java.util.stream.Stream; +import javax.inject.Inject; import javax.tools.DiagnosticCollector; import edu.umd.cs.findbugs.annotations.NonNull; import edu.umd.cs.findbugs.annotations.SuppressFBWarnings; +/** + * Abstract base class for Metaschema Maven plugin goals. + *

+ * This class provides common functionality for loading Metaschema modules, + * managing constraint sets, handling incremental builds, and performing + * code/schema generation. Concrete implementations should override the + * {@link #generate(Set)} method to provide specific generation behavior. + *

+ * The plugin supports: + *

    + *
  • Loading multiple Metaschema modules from a configured directory
    • + *
  • Applying external constraint sets to modules
    • + *
  • Incremental build support through stale file tracking
    • + *
  • Configurable file encoding for generated sources
    • + *
+ * + * @see GenerateSourcesMojo + * @see GenerateSchemaMojo + */ public abstract class AbstractMetaschemaMojo extends AbstractMojo { private static final String[] DEFAULT_INCLUDES = { "**/*.xml" }; @@ -205,6 +223,11 @@ protected final MavenProject getMavenProject() { return mavenProject; } + /** + * Retrieve the plugin artifacts available to this mojo. + * + * @return the list of plugin artifacts + */ protected final List getPluginArtifacts() { return pluginArtifacts; } @@ -290,6 +313,18 @@ protected Stream getModuleSources() { return Stream.of(ds.getIncludedFiles()).map(filename -> new File(metaschemaDir, filename)).distinct(); } + /** + * Create a new binding context configured with the specified module post + * processor. + * + * @param modulePostProcessor + * the post processor to apply to loaded modules + * @return the configured binding context + * @throws IOException + * if an I/O error occurs during context creation + * @throws MetaschemaException + * if an error occurs while processing the Metaschema module + */ @NonNull protected IBindingContext newBindingContext( @NonNull IModuleLoader.IModulePostProcessor modulePostProcessor) throws IOException, MetaschemaException { @@ -403,6 +438,14 @@ protected boolean isGenerationRequired() { return generate; } + /** + * Retrieve the combined classpath containing both project dependencies and + * plugin artifacts. + * + * @return a set of classpath elements as absolute paths + * @throws DependencyResolutionRequiredException + * if the project dependencies cannot be resolved + */ protected Set getClassPath() throws DependencyResolutionRequiredException { Set pathElements; try { @@ -422,6 +465,21 @@ protected Set getClassPath() throws DependencyResolutionRequiredExceptio return pathElements; } + /** + * Load and validate the Metaschema modules to generate sources or schemas for. + * + * @param bindingContext + * the binding context to use for module loading and validation + * @param modulePostProcessor + * the post processor to apply to each loaded module + * @return the set of loaded and validated modules + * @throws MetaschemaException + * if an error occurs while processing the Metaschema module + * @throws IOException + * if an I/O error occurs while loading a module + * @throws ConstraintValidationException + * if constraint validation fails on a loaded module + */ @NonNull protected Set getModulesToGenerateFor( @NonNull IBindingContext bindingContext, @@ -458,6 +516,14 @@ protected Set getModulesToGenerateFor( return modules; } + /** + * Create or update the stale file to record the current build time. + * + * @param staleFile + * the stale file to create or update + * @throws MojoExecutionException + * if the stale file cannot be created + */ protected void createStaleFile(@NonNull File staleFile) throws MojoExecutionException { // create the stale file if (!staleFileDirectory.exists() && !staleFileDirectory.mkdirs()) { @@ -572,6 +638,18 @@ private List performGeneration( @NonNull protected abstract List generate(@NonNull Set modules) throws MojoExecutionException; + /** + * A validation result handler that logs validation findings using the Maven + * plugin logger. + *

+ * Findings are logged at different levels based on their severity: + *

    + *
  • CRITICAL and ERROR - logged at error level
    • + *
  • WARNING - logged at warn level
    • + *
  • INFORMATIONAL - logged at info level
    • + *
  • All other severities - logged at debug level
    • + *
+ */ protected final class LoggingValidationHandler extends AbstractValidationResultProcessor { @@ -700,6 +778,13 @@ private CharSequence getMessage(@NonNull ConstraintValidationFinding finding) { } } + /** + * A module binding generator that generates and compiles Java classes for + * Metaschema modules during plugin execution. + *

+ * This generator uses the plugin's classpath for compilation, ensuring that all + * necessary dependencies are available during the code generation process. + */ public class ModuleBindingGenerator implements IModuleBindingGenerator { @NonNull private final Path compilePath; @@ -708,6 +793,14 @@ public class ModuleBindingGenerator implements IModuleBindingGenerator { @NonNull private final IBindingConfiguration bindingConfiguration; + /** + * Construct a new module binding generator. + * + * @param compilePath + * the directory path where generated classes will be compiled to + * @param bindingConfiguration + * the binding configuration to use for code generation + */ public ModuleBindingGenerator( @NonNull Path compilePath, @NonNull IBindingConfiguration bindingConfiguration) { @@ -718,6 +811,15 @@ public ModuleBindingGenerator( this.bindingConfiguration = bindingConfiguration; } + /** + * Generate Java source files for the specified module. + * + * @param module + * the Metaschema module to generate classes for + * @return the production containing the generated class information + * @throws MetaschemaException + * if an error occurs during class generation + */ @NonNull public IProduction generateClasses(@NonNull IModule module) throws MetaschemaException { IProduction production; @@ -797,9 +899,20 @@ public Class generate(IModule module) throws MetaschemaE } } + /** + * A module post processor that applies external constraints to modules, + * excluding the built-in Metaschema module to avoid duplicate constraint + * application. + */ private static class LimitedExternalConstraintsModulePostProcessor extends ExternalConstraintsModulePostProcessor { + /** + * Construct a new post processor with the specified constraint sets. + * + * @param additionalConstraintSets + * the constraint sets to apply to modules + */ public LimitedExternalConstraintsModulePostProcessor( @NonNull Collection additionalConstraintSets) { super(additionalConstraintSets); diff --git a/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/GenerateSchemaMojo.java b/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/GenerateSchemaMojo.java index 96c86e110..e2556b4d6 100644 --- a/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/GenerateSchemaMojo.java +++ b/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/GenerateSchemaMojo.java @@ -43,8 +43,17 @@ @Mojo(name = "generate-schemas", defaultPhase = LifecyclePhase.GENERATE_RESOURCES) public class GenerateSchemaMojo extends AbstractMetaschemaMojo { + /** + * Supported schema output formats for generation. + */ public enum SchemaFormat { + /** + * XML Schema Definition (XSD) format. + */ XSD, + /** + * JSON Schema format. + */ JSON_SCHEMA; } @@ -128,6 +137,7 @@ protected String getStaleFileName() { * * @param modules * the Metaschema modules to generate the schema for + * @return the list of generated schema files * @throws MojoExecutionException * if an error occurred during generation */ diff --git a/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/GenerateSourcesMojo.java b/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/GenerateSourcesMojo.java index b21901bbe..6ff1d2e3c 100644 --- a/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/GenerateSourcesMojo.java +++ b/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/GenerateSourcesMojo.java @@ -76,6 +76,7 @@ protected List getConfigs() { * * @param modules * the collection of Metaschema modules to generate sources for + * @return the list of generated Java source files * @throws MojoExecutionException * if an error occurred while generating sources */ diff --git a/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/package-info.java b/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/package-info.java new file mode 100644 index 000000000..17cf36c28 --- /dev/null +++ b/metaschema-maven-plugin/src/main/java/gov/nist/secauto/metaschema/maven/plugin/package-info.java @@ -0,0 +1,53 @@ +/* + * SPDX-FileCopyrightText: none + * SPDX-License-Identifier: CC0-1.0 + */ + +/** + * Provides Maven plugin goals for Metaschema-based code and schema generation. + *

+ * This package contains Maven plugin Mojos that integrate Metaschema processing + * into Maven builds. The plugin supports generating Java binding classes and + * schema files (XSD and JSON Schema) from Metaschema module definitions. + *

+ * Available goals: + *

    + *
  • {@code generate-sources} - Generates Java source files from Metaschema + * modules, bound to the {@code generate-sources} lifecycle phase
    • + *
  • {@code generate-schemas} - Generates XML Schema (XSD) and/or JSON Schema + * files from Metaschema modules, bound to the {@code generate-resources} + * lifecycle phase
    • + *
+ *

+ * Key classes: + *

    + *
  • {@link gov.nist.secauto.metaschema.maven.plugin.AbstractMetaschemaMojo} - + * Base class providing common functionality for module loading, constraint + * handling, and incremental build support
    • + *
  • {@link gov.nist.secauto.metaschema.maven.plugin.GenerateSourcesMojo} - + * Generates Java binding classes from Metaschema modules
    • + *
  • {@link gov.nist.secauto.metaschema.maven.plugin.GenerateSchemaMojo} - + * Generates schema files from Metaschema modules
    • + *
+ *

+ * Example plugin configuration: + * + * 

{@code
+ * 
+ *   gov.nist.secauto.metaschema
+ *   metaschema-maven-plugin
+ *   
+ *     
+ *       
+ *         generate-sources
+ *       
+ *     
+ *   
+ * 
+ * }
+ * + * @see gov.nist.secauto.metaschema.maven.plugin.GenerateSourcesMojo + * @see gov.nist.secauto.metaschema.maven.plugin.GenerateSchemaMojo + */ + +package gov.nist.secauto.metaschema.maven.plugin; From 2d363ddff501016927482ff321b5529e993eeaaa Mon Sep 17 00:00:00 2001 From: David Waltermire Date: Mon, 29 Dec 2025 09:24:10 -0500 Subject: [PATCH 3/3] fix: address PR review feedback - Fix misleading inline comment (32 KB not 2 GB) in DeserializationFeature.java - Remove duplicate Javadoc blocks in IBindingMetaschemaModule.java - Remove duplicate Javadoc blocks in IConfigurableMessageConstraintBase.java - Remove duplicate Javadoc blocks in IConstraintBase.java - Remove duplicate Javadoc blocks in IValueConstraintsBase.java - Remove duplicate Javadoc blocks in IValueTargetedConstraintsBase.java - Add @NonNull annotation to getAllowedValuesCollection() in XmlSimpleTypeDataTypeRestriction.java --- .../secauto/metaschema/databind/io/DeserializationFeature.java | 2 +- .../databind/model/metaschema/IBindingMetaschemaModule.java | 3 --- .../model/metaschema/IConfigurableMessageConstraintBase.java | 3 --- .../metaschema/databind/model/metaschema/IConstraintBase.java | 3 --- .../databind/model/metaschema/IValueConstraintsBase.java | 3 --- .../model/metaschema/IValueTargetedConstraintsBase.java | 3 --- .../xml/impl/schematype/XmlSimpleTypeDataTypeRestriction.java | 1 + 7 files changed, 2 insertions(+), 16 deletions(-) diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/DeserializationFeature.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/DeserializationFeature.java index 9794fb1ca..3ef7e5ac2 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/DeserializationFeature.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/io/DeserializationFeature.java @@ -31,7 +31,7 @@ public final class DeserializationFeature /** * The default number of bytes used for format detection lookahead. */ - public static final int FORMAT_DETECTION_LOOKAHEAD = 32_768; // 2 GB + public static final int FORMAT_DETECTION_LOOKAHEAD = 32_768; // 32 KB /** * If enabled, perform constraint validation on the deserialized bound objects. diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingMetaschemaModule.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingMetaschemaModule.java index 2831fc767..31094e174 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingMetaschemaModule.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IBindingMetaschemaModule.java @@ -12,9 +12,6 @@ import edu.umd.cs.findbugs.annotations.NonNull; -/** - * A Metaschema module represented as binding to Java classes and fields. - */ /** * Represents a Metaschema module loaded via data binding. *

diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConfigurableMessageConstraintBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConfigurableMessageConstraintBase.java index 5ace1ac1a..a03e80293 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConfigurableMessageConstraintBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConfigurableMessageConstraintBase.java @@ -7,9 +7,6 @@ import edu.umd.cs.findbugs.annotations.Nullable; -/** - * Represents constraint metadata that is common to all constraints. - */ /** * Base interface for constraints with configurable messages. *

diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConstraintBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConstraintBase.java index c879b064e..7197e9cf7 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConstraintBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IConstraintBase.java @@ -14,9 +14,6 @@ import edu.umd.cs.findbugs.annotations.Nullable; -/** - * Represents constraint metadata that is common to all constraints. - */ /** * Base interface for all constraint bindings. *

diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueConstraintsBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueConstraintsBase.java index fb77119e0..f4de460cc 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueConstraintsBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueConstraintsBase.java @@ -13,9 +13,6 @@ import edu.umd.cs.findbugs.annotations.NonNull; -/** - * Provides a common interface for value constraint binding objects. - */ /** * Base interface for value-level constraint bindings. *

diff --git a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueTargetedConstraintsBase.java b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueTargetedConstraintsBase.java index 859493eea..ae35c6314 100644 --- a/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueTargetedConstraintsBase.java +++ b/databind/src/main/java/gov/nist/secauto/metaschema/databind/model/metaschema/IValueTargetedConstraintsBase.java @@ -7,9 +7,6 @@ import java.util.List; -/** - * Provides a common interface for targeted value constraint binding objects. - */ /** * Base interface for targeted value constraint bindings. *

diff --git a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeRestriction.java b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeRestriction.java index a08197382..cf993e1d4 100644 --- a/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeRestriction.java +++ b/schemagen/src/main/java/gov/nist/secauto/metaschema/schemagen/xml/impl/schematype/XmlSimpleTypeDataTypeRestriction.java @@ -57,6 +57,7 @@ public XmlSimpleTypeDataTypeRestriction( * * @return the allowed values collection */ + @NonNull protected AllowedValueCollection getAllowedValuesCollection() { return allowedValuesCollection; }