ASSIGNMENT 1 - NURAIMAN DANIAL BIN MOHD ZAKI (22004858)

[nuraimandanial]

Refactoring and Type-Safety Improvements for REST SSE Item State Builder. (org.openhab.core.io.rest.sse)

Addressed Issue (1 mark)

The implementation addresses several maintainability and reliability issues within the SseItemStateEventBuilder and related REST/SSE components:

• Nullability violations under @NonNullByDefault, causing mismatches between @Nullable and @NonNull types.
• Complex, inconsistent, and difficult-to-maintain formatting and transformation logic.
• Lack of clear structural documentation, leading to confusion for future maintainers.
• Unhandled edge cases in unit conversion, transformation service lookup, and formatting.

These issues previously reduced code clarity, safety, and long-term maintainability.

What has been Reengineered (1.5 marks)

1. Strengthened Type-Safety and Null Handling

   • Implemented correct handling for nullable QuantityType<?>, DecimalType, and general State objects.
   • Enforced strict non-null guarantees in methods interacting with item states and display-state generation.
   • Added safe fallback behaviour when transformations, unit parsing, or conversions fail.

2. Refactored Formatting, Transformation, and Display-State Pipeline

   • Extracted monolithic logic into well-defined helper methods:
     • applyTransformationPattern()
     • applyFormattingPattern()
     • matchStateOption()
   • Implemented a clearer step-by-step process for computing a human-friendly display state.
   • Improved handling of malformed patterns, missing transformation services, and undefined values.

3. Improved Documentation and Code Readability

   • Added Javadoc for code clarity and understanding.
   • Applied consistent structure, naming, and spacing to improve readability.
   • Simplified nested conditionals and reduced repeated logic.

4. Modernization and Cleanup

   • Aligned code styles with the rest of the openHAB codebase for long-term maintainability.
   • Removed redundant blocks

Reengineering Strategy or Approach Used (1.5 marks)

Preventive Refactoring Strategy

The changes were applied to ensure long-term maintainability, not only to fix current issues. The approach focuses on preventing future nullability failures and improving code extensibility.

Impact of Changes (1 mark)

Positive Outcomes

• Compilation is now fully consistent with openHAB's null-safety rules.
• Reduced runtime error risk involving quantity conversions and transformation failures.
• Significantly improved maintainability through clearer code structure and documentation.

Compatibality

• Future enhancement to item display-state handling will be easier and safer to implement.