Final updates to parser writer code (#4)

* Be more permissive with validations when concerning subtypes of custom parsers

* Working primitivea rray expected parsers

* GWT-incompatible first attempt

* Working GWT compatible primitive collection parser

* Enhance type validation in parser generation by including checks for interfaces and wildcards. Update method names for clarity and improve handling of unsupported types in map field parsing.

* Fix test

* Get the proper package name

* Update documentation

* Review comments

* Remove lines

Author: JornC

gwt-beans-codegen-core/architecture.md

@@ -8,10 +8,12 @@
 
 The main orchestrator (`ParserGenerator`) that coordinates the generation process:
 
-- Accepts configuration parameters
-- Initiates type analysis
+- Accepts configuration parameters (root class, output directory, parser package, custom parser directory)
+- Initiates type analysis via TypeAnalyzer
 - Manages the generation workflow
-- Handles file output
+- Handles file output and directory cleanup
+- Provides command-line interface with argument parsing
+- Supports version and git hash tracking for @Generated annotations
 
 #### 2. Type Analyzer
 
@@ -21,31 +23,52 @@ The `TypeAnalyzer` component performs deep inspection of Java classes:
 - Handles type hierarchies and dependencies
 - Filters out primitive types and built-in classes
 - Manages type name collisions
+- Supports polymorphic type discovery via @JsonSubTypes
+- Validates unsupported types and throws appropriate exceptions
+- Tracks custom parser types to avoid generation conflicts
 
 #### 3. Parser Writers
 
-Two specialized writers handle different aspects of parser generation:
+Specialized writers handle different aspects of parser generation:
 
-##### Root Parser Writer
+##### ParserWriter
 
-- Generates the main entry point parser
-- Handles top-level configuration
-- Manages the primary parsing logic
+- Main writer that coordinates parser generation for all discovered types
+- Manages output directory and file writing
+- Handles generator metadata (name, version, git hash)
+- Creates parser class specifications with proper annotations
 
-##### Sub-Type Parser Writer
+##### ParserWriterUtils
 
-- Generates parsers for nested and dependent types
-- Handles complex type relationships
-- Manages naming conflicts for nested types
-
-#### 4. Parser Writer Utils
-
-Shared utilities for parser generation:
-
-- Code block generation
+- Shared utilities for parser generation
+- Code block generation for different field types
 - File I/O operations
 - Type conversion utilities
 - Common parsing patterns
+- Custom parser registry management
+- Polymorphic parser generation logic
+
+#### 4. Field Parsers
+
+Specialized parsers for different field types:
+
+- **SimpleFieldParser**: Handles primitives and wrappers (String, int, boolean, etc.)
+- **EnumFieldParser**: Handles enum types with @JsonCreator support
+- **CollectionFieldParser**: Handles List, Set, and object arrays
+- **MapFieldParser**: Handles Map types with String/Enum/complex keys
+- **PrimitiveArrayFieldParser**: Handles primitive arrays (int[], double[], etc.)
+- **CustomObjectFieldParser**: Handles custom objects requiring generated parsers
+
+#### 5. Configuration Validator
+
+The `ConfigurationValidator` ensures type compatibility:
+
+- Validates class structure and annotations
+- Checks for polymorphic type requirements (@JsonTypeInfo, @JsonSubTypes)
+- Validates field types and key types for maps
+- Ensures proper constructor availability
+- Validates getter/setter pairs
+- Provides detailed error reporting with visual indicators
 
 ### Generated Parser Structure
 
@@ -54,58 +77,109 @@ Each generated parser follows a consistent pattern:
 ```java
 @Generated(
     value = "nl.aerius.codegen.ParserGenerator",
-    date = "timestamp"
+    comments = "version: x.x.x (git: abc123)"
 )
 public class TypeNameParser {
+    public static TypeName parse(final String jsonText) {
+        if (jsonText == null) {
+            return null;
+        }
+        return parse(JSONObjectHandle.fromText(jsonText));
+    }
+
     public static TypeName parse(final JSONObjectHandle obj) {
         if (obj == null) {
             return null;
         }
         final TypeName config = new TypeName();
-        // Field parsing logic
+        parse(obj, config);
         return config;
     }
+
+    public static void parse(final JSONObjectHandle obj, final TypeName config) {
+        if (obj == null || config == null) {
+            return;
+        }
+        // Field parsing logic with null checks
+    }
+}
+```
+
+For polymorphic types, the main parse method includes switch-based type discrimination:
+
+```java
+public static BaseType parse(final JSONObjectHandle obj) {
+    if (obj == null) {
+        return null;
+    }
+    
+    final String typeName = obj.getString("_type");
+    switch (typeName) {
+    case "TypeA":
+        return SubTypeAParser.parse(obj);
+    case "TypeB":
+        return SubTypeBParser.parse(obj);
+    default:
+        throw new RuntimeException("Unknown type name '" + typeName + "'");
+    }
 }
 ```
 
 ## Data Flow
 
 1. **Type Discovery**
 
-   - Root class analysis
-   - Recursive type scanning
-   - Dependency resolution
-
-2. **Parser Generation**
+   - Root class analysis via reflection
+   - Recursive type scanning through fields and generic parameters
+   - Polymorphic subtype discovery via @JsonSubTypes
+   - Dependency resolution and ordering
+   - Custom parser type filtering
 
-   - Template selection
-   - Code generation
-   - File writing
+2. **Validation**
 
-3. **Validation**
    - Type compatibility checks
-   - Name collision detection
-   - Output verification
+   - Polymorphic annotation validation
+   - Constructor and accessor validation
+   - Map key type validation
+   - Error reporting with visual indicators
+
+3. **Parser Generation**
+
+   - Template selection based on type category
+   - Code generation using JavaPoet
+   - Field-specific parsing logic generation
+   - Polymorphic parser generation for base types
+   - Custom parser integration
+
+4. **File Output**
+   - Directory cleanup and creation
+   - Java file writing with proper formatting
+   - Import statement management
+   - Custom parser import tracking
 
 ## Design Decisions
 
 ### 1. Static Parse Methods
 
-- Parsers use static methods for simplicity
+- Parsers use static methods for simplicity and performance
 - No state maintenance required
 - Easy to use in streaming contexts
+- Consistent with utility class patterns
 
 ### 2. Null Safety
 
 - All parsers handle null inputs gracefully
-- Clear null checking patterns
-- Type-safe output
+- Clear null checking patterns with early returns
+- Type-safe output with proper null handling
+- Consistent null behavior across all parsers
 
 ### 3. Error Handling
 
 - Early validation of input types
-- Clear error messages
+- Clear error messages with context
 - Fail-fast approach for invalid configurations
+- UnsupportedTypeException for unsupported types
+- Detailed validation reporting with visual indicators
 
 ### 4. Custom Parser Integration
 
@@ -122,26 +196,50 @@ public class CustomTypeParser {
 
 Integration points:
 
-- Custom parser discovery
-- Type resolution
-- Parser registration
-- Error handling for custom parsers
+- Custom parser discovery via directory scanning
+- Type resolution and registration
+- Import tracking for generated code
+- Validation bypass for custom parser types
+
+### 5. Polymorphic Type Support
+
+- Automatic discovery of @JsonSubTypes annotations
+- Generation of switch-based type discrimination
+- Support for @JsonTypeInfo with NAME discriminator
+- Validation of polymorphic type requirements
+- Proper subtype parser generation and integration
 
-### 5. Performance Considerations
+### 6. Performance Considerations
 
 1. **Type Analysis & Generation**
 
-   - Caching of type information
+   - Caching of type information during analysis
    - Lazy loading of dependent types
    - Memory-efficient type hierarchy traversal
    - Optimized template processing
-   - Efficient string handling
-   - Minimized object creation
+   - Efficient string handling and code generation
+   - Minimized object creation during generation
 
 2. **Runtime Performance**
-   - Efficient null checking
-   - Optimized collection handling
-   - Memory usage patterns
-   - Performance metrics collection
-   - Memory usage tracking
-   - Generation time profiling
+   - Efficient null checking patterns
+   - Optimized collection handling with specific forEach methods
+   - Memory usage patterns for large collections
+   - Performance metrics collection capabilities
+   - Memory usage tracking during generation
+   - Generation time profiling support
+
+### 7. Testing Strategy
+
+- **Expected Parser Tests**: Validate reference implementation
+- **Generated Parser Tests**: Validate generated code functionality
+- **Round-trip Tests**: JSON → Object → JSON validation
+- **Validation Tests**: Type compatibility and error handling
+- **Custom Parser Tests**: Integration and discovery validation
+- **Unsupported Type Tests**: Error handling for invalid types
+
+### 8. GWT Compatibility
+
+- Uses nl.aerius.wui.service.json.JSONObjectHandle for GWT compatibility
+- Avoids Java 8+ features and unsupported types
+- Maintains compatibility with GWT compilation
+- Supports GWT-specific JSON handling patterns

gwt-beans-codegen-core/development-plan.md

@@ -21,12 +21,14 @@ We're building a JSON parser generator that will replace GWT-RPC serialization.
    - Map<String, String>, HashMap<String, Integer>
    - LinkedHashMap<String, Double>
    - All primitive arrays (int[], long[], double[], float[], byte[], short[], char[], boolean[])
+   - Object arrays (String[], Integer[], etc.)
 
 3. **Object Support**
 
    - Custom object references
    - Null handling for all types
    - Custom parser integration
+   - Polymorphic type support with @JsonTypeInfo and @JsonSubTypes
 
 4. **Complex Types**
    - List<CustomObject>
@@ -38,12 +40,27 @@ We're building a JSON parser generator that will replace GWT-RPC serialization.
    - Map<Enum, String>
    - Map<Enum, CustomObject>
    - Map<Enum, primitive types>
+   - Nested collections and maps (2+ levels)
+   - Complex key types with fromStringValue() methods
+
+5. **Polymorphic Support**
+   - @JsonTypeInfo with NAME discriminator
+   - @JsonSubTypes for concrete implementations
+   - Automatic subtype discovery and parser generation
+   - Switch-based polymorphic parsing
+
+6. **Validation & Testing**
+   - Comprehensive type validation
+   - Custom parser discovery and integration
+   - Round-trip testing (JSON → Object → JSON)
+   - Generated vs expected parser comparison
+   - Unsupported type detection and error handling
 
 ### Remaining Implementation Tasks
 
-1. **Complex Nested Structures** [HIGH]
+1. **Complex Nested Structures** [MEDIUM]
 
-   - Deeply nested collections (3+ levels)
+   - Deeply nested collections (3+ levels) - partially working
    - Examples to implement:
      ```java
      class ComplexNested {
@@ -60,15 +77,15 @@ We're building a JSON parser generator that will replace GWT-RPC serialization.
    - Add usage examples and best practices
    - Document performance considerations
 
-3. **Testing Strategy** [HIGH]
+3. **Testing Strategy** [MEDIUM]
 
    - Add performance benchmarks for different type combinations
    - Create stress tests for deeply nested structures
    - Add memory usage tests for large collections
    - Implement test coverage reporting
    - Add integration tests with real-world scenarios
 
-4. **Performance Optimization** [MEDIUM]
+4. **Performance Optimization** [LOW]
    - Profile parser generation for large type hierarchies
    - Optimize memory usage during type analysis
    - Cache frequently used type information
@@ -96,10 +113,12 @@ The following types will NOT be supported due to GWT compatibility or design dec
    - Calendar
 
 4. **Collection Limitations**
-   - Map with non-String keys (except enums)
+   - Map with non-String keys (except enums and supported primitive wrappers)
    - Queue and Deque implementations
    - SortedSet/TreeSet
    - SortedMap/TreeMap
+   - Generic types with wildcards
+   - Inner classes (must be top-level)
 
 ## Development Constraints
 
@@ -129,6 +148,8 @@ The following types will NOT be supported due to GWT compatibility or design dec
 - Custom parsers sourced from original location
 - Uses Jackson for test serialization
 - Keep type analysis and parsing logic separate
+- Polymorphic types require both @JsonTypeInfo and @JsonSubTypes annotations
+- Interfaces must be annotated with @JsonTypeInfo for polymorphic handling
 
 ### Migration Guide