[
https://issues.apache.org/jira/browse/GEODE-10503?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jinwoo Hwang updated GEODE-10503:
---------------------------------
Fix Version/s: 2.0.0
> Migrate JLine from 2.x to 3.x for GFSH Terminal Enhancement
> -----------------------------------------------------------
>
> Key: GEODE-10503
> URL: https://issues.apache.org/jira/browse/GEODE-10503
> Project: Geode
> Issue Type: Improvement
> Reporter: Jinwoo Hwang
> Assignee: Jinwoo Hwang
> Priority: Major
> Fix For: 2.0.0
>
>
> h2. Summary
> Upgrade JLine from 2.x to 3.x to modernize GFSH terminal capabilities and
> support Spring Shell 3. This migration enhances command-line editing,
> history, and completion features.
> {*}Impact{*}: GFSH terminal interface | {*}Risk{*}: High | {*}Timeline{*}: 3
> weeks
> ----
> h2. Background
> h3. Why Required
> * {*}Spring Shell 3 dependency{*}: Spring Shell 3.x requires JLine 3.x
> * {*}Modern terminal features{*}: Better Unicode support, improved completion
> * {*}Active maintenance{*}: JLine 2.x is no longer actively maintained
> * {*}Bug fixes{*}: JLine 3.x fixes many terminal handling issues
> h3. Current State
> * {*}Current{*}: JLine 2.x (legacy)
> * {*}Target{*}: JLine 3.x (latest stable)
> * {*}Affected Module{*}: {{geode-gfsh}}
> * {*}Impact{*}: Terminal I/O, command history, tab completion
> ----
> h2. Scope
> h3. *In Scope*
> * Terminal reader/writer integration
> * Command-line editing (cursor movement, cut/paste)
> * Command history management
> * Tab completion rendering
> * ANSI color support
> * Terminal detection and configuration
> * Windows/Unix terminal compatibility
> h3. *Breaking Changes*
> ||Component||JLine 2.x||JLine 3.x||Migration Effort||
> |*Package*|{{jline.*}}|{{org.jline.*}}|🟡 Import updates|
> |*Terminal*|{{ConsoleReader}}|{{LineReader}} + {{Terminal}}|🔴 API rewrite|
> |*Completion*|{{Completer}} interface|{{Completer}} + {{Candidate}}|🟡
> Moderate changes|
> |*History*|{{History}} class|{{History}} interface|🟡 Refactoring needed|
> |*ANSI Colors*|{{AnsiString}}|{{AttributedString}}|🟡 Color code updates|
> |*Configuration*|System properties|{{LineReaderBuilder}}|🟡 Config migration|
> ----
> h2. Implementation Plan
> h3. *Phase 1: Dependency & Setup* (Week 1, Days 1-2)
> * [ ] Update JLine dependency to 3.x in {{DependencyConstraints.groovy}}
> * [ ] Resolve dependency conflicts
> * [ ] Set up feature branch: {{jline-3-migration}}
> * [ ] Create compatibility testing framework
> h3. *Phase 2: Core Terminal Migration* (Week 1-2, Days 3-7)
> * [ ] Replace {{ConsoleReader}} with {{LineReader}}
> * [ ] Migrate {{Terminal}} initialization
> * [ ] Update terminal detection logic
> * [ ] Configure terminal attributes
> * [ ] Migrate input/output streams
> h3. *Phase 3: History & Completion* (Week 2, Days 8-10)
> * [ ] Migrate command history implementation
> * [ ] Update history file handling
> * [ ] Migrate tab completion logic
> * [ ] Update {{Candidate}} generation for completions
> * [ ] Configure completion behavior
> h3. *Phase 4: ANSI & Formatting* (Week 2-3, Days 11-12)
> * [ ] Migrate ANSI color codes to {{AttributedString}}
> * [ ] Update styled output rendering
> * [ ] Configure color schemes
> * [ ] Test color output on different terminals
> h3. *Phase 5: Signal Handling & Advanced Features* (Week 3, Days 13-14)
> * [ ] Migrate signal handlers (Ctrl+C, Ctrl+D)
> * [ ] Update interrupt handling
> * [ ] Configure key bindings
> * [ ] Migrate custom widgets (if any)
> * [ ] Update terminal size detection
> h3. *Phase 6: Testing & Validation* (Week 3, Days 15)
> * [ ] Unit tests for terminal I/O
> * [ ] Integration tests with GFSH commands
> * [ ] Cross-platform testing (Windows, Linux, macOS)
> * [ ] Terminal emulator testing (various terminals)
> * [ ] Performance testing
> *Test Coverage:*
> * Command-line editing (insert, delete, move cursor)
> * History navigation (up/down arrows)
> * Tab completion rendering
> * ANSI color display
> * Multi-byte character support (Unicode)
> * Signal handling (interrupts)
> ----
> h2. Technical Details
> h3.
> h3. Architecture Changes
> h3. Configuration Migration
> h3. Key API Mappings
> ||JLine 2.x||JLine 3.x||Notes||
> |{{ConsoleReader}}|{{LineReader}}|Main interface changed|
> |{{readLine(prompt)}}|{{readLine(prompt)}}|✅ Same method|
> |{{getHistory()}}|{{getHistory()}}|✅ Same method, different impl|
> |{{addCompleter()}}|{{setCompleter()}}|Method name changed|
> |{{CursorBuffer}}|{{Buffer}}|Internal buffer API changed|
> |{{Terminal.getWidth()}}|{{Terminal.getSize().getColumns()}}|Size API changed|
> ----
> h2. Risks & Mitigation
> ||Risk||Impact||Probability||Mitigation||
> |*Terminal compatibility issues*|GFSH unusable on some
> platforms|Medium|Extensive cross-platform testing|
> |*History file format changes*|Lost command history|Low|Migration script for
> history files|
> |*Completion rendering broken*|Poor UX|Medium|Thorough completion testing|
> |*Signal handling differences*|Ctrl+C doesn't work|Low|Test interrupt
> scenarios|
> |*Performance regression*|Slow input response|Low|Benchmark testing|
> |*Unicode issues*|Garbled characters|Medium|Multi-byte character testing|
> ----
> h2. Dependencies
> h3. *Blocked By*
> * Spring Shell 3 migration (directly depends on JLine 3)
> h3. *Blocks*
> * Complete GFSH modernization
> * Spring Framework 6 migration completion
> h3. *Related*
> * Spring Shell 3 migration
> * Jakarta EE 10 migration
> ----
> h2. Success Criteria
> * [ ] JLine 3.x integrated and functional
> * [ ] All terminal operations work (input, output, editing)
> * [ ] Command history preserved and functional
> * [ ] Tab completion rendering correct
> * [ ] ANSI colors display properly
> * [ ] Cross-platform compatibility (Windows, Linux, macOS)
> * [ ] No performance regression
> * [ ] All tests passing
> * [ ] Signal handling (Ctrl+C, Ctrl+D) works
> ----
> h2. Testing Strategy
> h3. *Unit Tests*
> * Terminal initialization
> * Line reading functionality
> * History management
> * Completion rendering
> * ANSI color formatting
> h3. *Integration Tests*
> * Full GFSH session
> * Command execution with JLine
> * History persistence across sessions
> * Tab completion in real scenarios
> h3. *Edge Cases*
> * Very long command lines (> 1000 chars)
> * Multi-byte characters (Chinese, Japanese, emoji)
> * Terminal resize during input
> * Interrupted input (Ctrl+C)
> * End-of-file (Ctrl+D)
> * Paste large text blocks
> ----
> h2. Resources
> * {*}Development{*}: 3 person-weeks (1 developer × 3 weeks)
> * {*}QA{*}: 1 week (cross-platform testing)
> * {*}Total Effort{*}: ~4 person-weeks
> ----
> h2. References
> h3. *Documentation*
> * [JLine 3.x Documentation|https://github.com/jline/jline3/wiki]
> * [JLine 2 to 3 Migration
> Guide|https://github.com/jline/jline3/wiki/Migrating-from-JLine-2.x]
> * [Spring Shell 3 + JLine 3
> Integration|https://docs.spring.io/spring-shell/docs/current/reference/htmlsingle/]
> h3. *Related Issues*
> * Spring Shell 3 Migration
> * Spring Framework 6 Migration
>
> ----
> h2. Migration Checklist
> h3. Pre-Migration
> * [ ] Audit current JLine 2 usage in geode-gfsh
> * [ ] Document custom terminal configurations
> * [ ] Back up command history format
> * [ ] Identify platform-specific code
> h3. Migration
> * [ ] Update dependencies
> * [ ] Migrate ConsoleReader → LineReader
> * [ ] Migrate Terminal initialization
> * [ ] Update Completers
> * [ ] Migrate History handling
> * [ ] Update ANSI/color code
> * [ ] Fix signal handlers
> h3. Post-Migration
> * [ ] Platform testing complete
> * [ ] Performance validated
> * [ ] User documentation updated
> * [ ] Migration guide published
> ----
> h2. Notes
> h3. *Critical Integration Point*
> JLine 3 migration *must be coordinated* with Spring Shell 3 migration, as
> Spring Shell 3 has built-in JLine 3 integration. Consider migrating these
> together.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
