feat: ESPI 4.0 Schema Compliance - Phase 16b: UsagePoint Add Enum Fields & Reorder #84
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…lds & Reorder This PR implements Phase 16b of the UsagePoint schema compliance work, adding 3 missing enum fields and reordering all entity fields to match exact ESPI 4.0 XSD sequence. Builds on Phase 16a (PR #83) which added Boolean/String fields. ## Changes in Phase 16b ### New Enum Classes (domain/common) - `AmiBillingReadyKind` - AMI billing readiness lifecycle states (7 values) - `UsagePointConnectedKind` - Network connection states (3 values) - `PhaseCodeKind` - Phase identifiers for electrical systems (27 values) ### Entity Updates (UsagePointEntity) - Added 3 enum fields in correct XSD positions: - `amiBillingReady` (XSD position 5) - `connectionState` (XSD position 7) - `phaseCode` (XSD position 15) - **Reordered ALL fields to match exact ESPI 4.0 XSD element sequence** - Added XSD position comments for each field (positions 1-21) - Added section headers for clarity (XSD fields, legacy fields, relationships) - Documented legacy fields (`uri`, `kind`) as NOT in XSD for Phase 16c review ### Database Migrations Updated all three vendor-specific V2 migrations: - **H2**: Added 3 enum columns (VARCHAR 32) in XSD sequence - **MySQL**: Added 3 enum columns (VARCHAR 32) in XSD sequence - **PostgreSQL**: Added 3 enum columns (VARCHAR 32) in XSD sequence ### Testing - Added comprehensive repository test: `shouldPersistAndRetrievePhase16bEnumFields()` - Verifies all 3 enum fields persist and retrieve correctly - All 584 tests passing (was 583, added 1 new test) ## XSD Compliance Achieved Fields now match exact ESPI 4.0 XSD sequence (espi.xsd:486-613): 1. roleFlags 2. ServiceCategory 3. status 4. serviceDeliveryPoint (relationship) 5. **amiBillingReady** ✅ NEW (Phase 16b) 6. checkBilling (Phase 16a) 7. **connectionState** ✅ NEW (Phase 16b) 8. estimatedLoad 9. grounded (Phase 16a) 10. isSdp (Phase 16a) 11. isVirtual (Phase 16a) 12. minimalUsageExpected (Phase 16a) 13. nominalServiceVoltage 14. outageRegion (Phase 16a) 15. **phaseCode** ✅ NEW (Phase 16b) 16. ratedCurrent 17. ratedPower 18. readCycle (Phase 16a) 19. readRoute (Phase 16a) 20. serviceDeliveryRemark (Phase 16a) 21. servicePriority (Phase 16a) 22-23. pnodeRefs, aggregateNodeRefs (relationships) ## Technical Details ### Enum Design - All enums follow existing ServiceCategory pattern - String-based values for AmiBillingReadyKind, UsagePointConnectedKind - Integer-based values for PhaseCodeKind (per XSD UInt16) - Each enum has `fromValue()` method for deserialization - Stored as VARCHAR(32) in database using `@Enumerated(EnumType.STRING)` ### Field Ordering - Entity fields now match exact XSD element sequence - Improves maintainability and XSD compliance verification - Inline comments mark XSD positions for each field - Legacy fields clearly separated with TODO for Phase 16c ### Additive-Only Changes This PR is **100% additive** with zero breaking changes: - All new fields are nullable/optional - No field deletions or renames - No changes to existing relationships - Backward compatible database migrations ## Test Results ``` Tests run: 584, Failures: 0, Errors: 0, Skipped: 0 BUILD SUCCESS ``` ## Related - Issue #28 - Phase 16: UsagePoint - PR #83 - Phase 16a: Add Missing Boolean/String Fields - Part 2 of 5 sub-phases for complete UsagePoint compliance ## Next Steps (Phase 16c) - Repository cleanup (remove non-indexed queries) - Review legacy fields (`kind`, `uri`) - Convert @query to Spring Data JPA derived queries Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
dfcoffin
deleted the
feature/schema-compliance-phase-16b-add-enum-fields
branch
dfcoffin
added a commit
that referenced
this pull request
Jan 15, 2026
…leanup This PR implements Phase 16c of the UsagePoint schema compliance work, cleaning up the repository to remove non-indexed queries and convert to Spring Data JPA derived query methods for optimal performance. ## Changes in Phase 16c ### Repository Query Optimization Removed methods that query non-indexed columns or perform full table scans: - **Removed `findByResourceUri(String uri)`** - Queries `uri` field which is NOT indexed and is a legacy field NOT in ESPI 4.0 XSD - **Removed `findAllIds()`** - Full table scan without WHERE clause (performance risk) - **Removed `existsByUuid(UUID uuid)`** - Use built-in `existsById(UUID id)` instead - **Removed `deleteByUuid(UUID uuid)`** - Use built-in `deleteById(UUID id)` instead ### Spring Data JPA Derived Queries Converted `@Query` annotations to Spring Data JPA derived query methods: - **`findAllByRetailCustomerId(Long retailCustomerId)`** - Uses indexed `retail_customer_id` - **`findAllByUpdatedAfter(LocalDateTime lastUpdate)`** - Uses indexed `updated` column ### Retained Methods (All Use Indexed Columns) - `findByRelatedHref(String href)` - Uses indexed relationship table - `findAllByRetailCustomerId(Long retailCustomerId)` - Uses indexed `retail_customer_id` - `findAllByUpdatedAfter(LocalDateTime lastUpdate)` - Uses indexed `updated` - `findAllIdsByRetailCustomerId(Long retailCustomerId)` - Uses indexed `retail_customer_id` ### Database Index Analysis Current indexed columns on `usage_points` table: - `kind` - Indexed but NOT in ESPI 4.0 XSD (legacy field, no queries use it) - `status` - Indexed (no queries currently use it) - `retail_customer_id` - Indexed ✅ USED by queries - `service_delivery_point_id` - Indexed (no queries currently use it) - `local_time_parameters_id` - Indexed (no queries currently use it) - `created` - Indexed (no queries currently use it) - `updated` - Indexed ✅ USED by queries ### Test Updates - Removed 4 test methods for deleted repository methods: - `shouldFindUsagePointByResourceUri()` - `shouldFindAllUsagePointIds()` - `shouldCheckIfUsagePointExistsByUuid()` - `shouldDeleteUsagePointByUuid()` - Updated `shouldHandleEmptyResultsGracefully()` to test only retained methods - Updated method call from `findAllUpdatedAfter()` to `findAllByUpdatedAfter()` ## Technical Details ### Performance Benefits All remaining queries use indexed columns: - Eliminates full table scans (removed `findAllIds`) - Uses database indexes for O(log n) lookups instead of O(n) scans - Removes queries on non-indexed legacy field (`uri`) ### Spring Data JPA Patterns - Derived query methods (e.g., `findAllByRetailCustomerId`) are automatically implemented by Spring Data JPA at runtime - Reduces custom JPQL code and improves maintainability - Type-safe method names reduce query errors ### Legacy Field Review **`kind` field** (NOT in ESPI 4.0 XSD): - Has database index but is NOT used by any queries - Field exists in entity but not in XSD specification - No repository methods query this field - Consider for removal in future phase **`uri` field** (NOT in ESPI 4.0 XSD): - Legacy field documented in Phase 16b - No longer queryable (removed `findByResourceUri`) - Consider for removal in future phase ## Test Results ``` Tests run: 580, Failures: 0, Errors: 0, Skipped: 0 BUILD SUCCESS ``` *Note: Was 584 tests, now 580 (removed 4 tests for deleted methods)* ## Related - Issue #28 - Phase 16: UsagePoint - PR #83 - Phase 16a: Add Missing Boolean/String Fields (merged) - PR #84 - Phase 16b: Add Enum Fields & Reorder (merged) - Part 3 of 5 sub-phases for complete UsagePoint compliance ## Next Steps (Phase 16d) - Mapper bidirectional updates - Update Entity-to-DTO mappings - Update DTO-to-Entity mappings - Handle all embedded SummaryMeasurement mappings Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
dfcoffin
added a commit
that referenced
this pull request
Jan 15, 2026
…leanup (#85) This PR implements Phase 16c of the UsagePoint schema compliance work, cleaning up the repository to remove non-indexed queries and convert to Spring Data JPA derived query methods for optimal performance. ## Changes in Phase 16c ### Repository Query Optimization Removed methods that query non-indexed columns or perform full table scans: - **Removed `findByResourceUri(String uri)`** - Queries `uri` field which is NOT indexed and is a legacy field NOT in ESPI 4.0 XSD - **Removed `findAllIds()`** - Full table scan without WHERE clause (performance risk) - **Removed `existsByUuid(UUID uuid)`** - Use built-in `existsById(UUID id)` instead - **Removed `deleteByUuid(UUID uuid)`** - Use built-in `deleteById(UUID id)` instead ### Spring Data JPA Derived Queries Converted `@Query` annotations to Spring Data JPA derived query methods: - **`findAllByRetailCustomerId(Long retailCustomerId)`** - Uses indexed `retail_customer_id` - **`findAllByUpdatedAfter(LocalDateTime lastUpdate)`** - Uses indexed `updated` column ### Retained Methods (All Use Indexed Columns) - `findByRelatedHref(String href)` - Uses indexed relationship table - `findAllByRetailCustomerId(Long retailCustomerId)` - Uses indexed `retail_customer_id` - `findAllByUpdatedAfter(LocalDateTime lastUpdate)` - Uses indexed `updated` - `findAllIdsByRetailCustomerId(Long retailCustomerId)` - Uses indexed `retail_customer_id` ### Database Index Analysis Current indexed columns on `usage_points` table: - `kind` - Indexed but NOT in ESPI 4.0 XSD (legacy field, no queries use it) - `status` - Indexed (no queries currently use it) - `retail_customer_id` - Indexed ✅ USED by queries - `service_delivery_point_id` - Indexed (no queries currently use it) - `local_time_parameters_id` - Indexed (no queries currently use it) - `created` - Indexed (no queries currently use it) - `updated` - Indexed ✅ USED by queries ### Test Updates - Removed 4 test methods for deleted repository methods: - `shouldFindUsagePointByResourceUri()` - `shouldFindAllUsagePointIds()` - `shouldCheckIfUsagePointExistsByUuid()` - `shouldDeleteUsagePointByUuid()` - Updated `shouldHandleEmptyResultsGracefully()` to test only retained methods - Updated method call from `findAllUpdatedAfter()` to `findAllByUpdatedAfter()` ## Technical Details ### Performance Benefits All remaining queries use indexed columns: - Eliminates full table scans (removed `findAllIds`) - Uses database indexes for O(log n) lookups instead of O(n) scans - Removes queries on non-indexed legacy field (`uri`) ### Spring Data JPA Patterns - Derived query methods (e.g., `findAllByRetailCustomerId`) are automatically implemented by Spring Data JPA at runtime - Reduces custom JPQL code and improves maintainability - Type-safe method names reduce query errors ### Legacy Field Review **`kind` field** (NOT in ESPI 4.0 XSD): - Has database index but is NOT used by any queries - Field exists in entity but not in XSD specification - No repository methods query this field - Consider for removal in future phase **`uri` field** (NOT in ESPI 4.0 XSD): - Legacy field documented in Phase 16b - No longer queryable (removed `findByResourceUri`) - Consider for removal in future phase ## Test Results ``` Tests run: 580, Failures: 0, Errors: 0, Skipped: 0 BUILD SUCCESS ``` *Note: Was 584 tests, now 580 (removed 4 tests for deleted methods)* ## Related - Issue #28 - Phase 16: UsagePoint - PR #83 - Phase 16a: Add Missing Boolean/String Fields (merged) - PR #84 - Phase 16b: Add Enum Fields & Reorder (merged) - Part 3 of 5 sub-phases for complete UsagePoint compliance ## Next Steps (Phase 16d) - Mapper bidirectional updates - Update Entity-to-DTO mappings - Update DTO-to-Entity mappings - Handle all embedded SummaryMeasurement mappings Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR implements Phase 16b of the UsagePoint schema compliance work, adding 3 missing enum fields and reordering all entity fields to match exact ESPI 4.0 XSD sequence. Builds on Phase 16a (PR #83) which added Boolean/String fields.
Phase 16 Strategy
Phase 16 (UsagePoint) is being split into sub-phases:
Changes in Phase 16b
New Enum Classes (domain/common)
AmiBillingReadyKind- AMI billing readiness lifecycle states (7 values)UsagePointConnectedKind- Network connection states (3 values)PhaseCodeKind- Phase identifiers for electrical systems (27 values)Entity Updates (UsagePointEntity)
amiBillingReady(XSD position 5)connectionState(XSD position 7)phaseCode(XSD position 15)uri,kind) as NOT in XSD for Phase 16c reviewDatabase Migrations
Updated all three vendor-specific V2 migrations:
Testing
shouldPersistAndRetrievePhase16bEnumFields()XSD Compliance Achieved
Fields now match exact ESPI 4.0 XSD sequence (espi.xsd:486-613):
Technical Details
Enum Design
fromValue()method for deserialization@Enumerated(EnumType.STRING)Field Ordering
Additive-Only Changes
This PR is 100% additive with zero breaking changes:
Test Results
Related
Next Steps (Phase 16c)
kind,uri)🤖 Generated with Claude Code