[
https://issues.apache.org/jira/browse/UNOMI-879?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Serge Huber updated UNOMI-879:
------------------------------
Description:
This proposal suggests replacing our current disparate Karaf shell commands
with a unified CRUD command system that would provide a consistent,
maintainable, and extensible interface for all Unomi objects. This
architectural improvement would offer significant benefits for both developers
and operators.
h3. Current Pain Points:
1. Inconsistent command patterns across different object types
2. Significant code duplication in command implementations
3. Varying parameter names and behaviors
4. Scattered documentation and help text
5. High maintenance overhead
6. Steep learning curve for new users
h3. Proposed Solution:
A unified command structure:
{noformat}
unomi:crud <operation> <type> [id] [options]
Operations:
- create: Create new object from JSON file
- read: Display object details
- update: Update existing object from JSON
- delete: Remove an object
- list: Display objects in table format
- help: Show object type documentation
Options:
--file (-f): JSON file for create/update
--csv: Output in CSV format
--max-entries (-n): Maximum items to display
{noformat}
h3. Example Usage Would Be:
{noformat}
# List all rules
unomi:crud list rule
# Show rule details
unomi:crud read rule rule_id
# Create new rule
unomi:crud create rule --file new_rule.json
# Update existing rule
unomi:crud update rule rule_id --file updated_rule.json
# Delete rule
unomi:crud delete rule rule_id
# Get help for rule properties
unomi:crud help rule
{noformat}
h3. Intelligent Auto-completion Features:
The unified command system implements rich context-aware auto-completion to
enhance user productivity:
1. Operation Auto-completion:
{noformat}
unomi:crud [TAB]
Completions: create, read, update, delete, list, help
{noformat}
2. Object Type Auto-completion:
{noformat}
unomi:crud list [TAB]
Completions: rule, segment, profile, event, action, property, apikey, schema,
scope, tenant
{noformat}
3. Object ID Auto-completion:
{noformat}
unomi:crud read rule [TAB]
Completions: [dynamically shows available rule IDs]
{noformat}
4. Property Name Auto-completion:
For JSON editing, provides context-aware property name suggestions:
* Rules:
{noformat}
{
"item[TAB]
Completions: itemId, name, description, condition, actions, priority, metadata
{noformat}
* Segments:
{noformat}
{
"item[TAB]
Completions: itemId, name, description, condition, scope, metadata
{noformat}
5. Property Value Auto-completion:
Context-sensitive value suggestions for specific properties:
* API Key Types:
{noformat}
"keyType": "[TAB]
Completions: PUBLIC, PRIVATE
{noformat}
* Event Types:
{noformat}
"eventType": "[TAB]
Completions: view, login, sessionCreated, profileUpdated, sessionReassigned,
updateProperties, formSubmitted, click, download, search,
videoStarted, videoCompleted
{noformat}
* Condition Types:
{noformat}
"condition": {
"type": "[TAB]
Completions: booleanCondition, profilePropertyCondition,
sessionPropertyCondition,
eventPropertyCondition, pastEventCondition, matchAllCondition,
notCondition, orCondition, andCondition
{noformat}
6. Dynamic Value Completion:
* Tenant IDs: Auto-completes available tenant identifiers
* Scope IDs: Auto-completes available scope identifiers
* Profile IDs: Auto-completes recently updated profile identifiers
* Schema IDs: Auto-completes installed JSON schema identifiers
7. Smart Filtering:
* All completions are filtered based on the current input prefix
* Shows only relevant completions based on the current context
* Supports case-insensitive matching where appropriate
8. Help Integration:
* Property help text is context-aware and shows:
- Required properties with descriptions
- Optional properties with descriptions
- Valid values and formats
- Examples where applicable
This comprehensive auto-completion system would:
* Reduce user errors
* Speed up command composition
* Provide inline documentation
* Guide users through complex object structures
* Maintain consistency across all object types
h3. Expected Benefits:
1. Consistency and Usability:
* Single command pattern for all object types
* Consistent parameter naming and behavior
* Unified help system and documentation
* Reduced learning curve for new users
2. Code Maintainability:
* Expected ~75% reduction in command-related code
* Centralized error handling
* Shared pagination and filtering logic
* Common JSON handling for all object types
3. Enhanced Features:
* Built-in CSV output support
* Consistent table formatting
* Property auto-completion
* Rich help documentation for each object type
h3. Proposed Implementation:
1. Core Components:
* CrudCommand interface: Would define CRUD operations
* BaseCrudCommand: Would provide common implementation
* UnomiCrudCommand: Would handle main command routing
* Type-specific implementations (e.g., RuleCrudCommand, ProfileCrudCommand)
2. Key Features:
* OSGi service-based architecture
* Dynamic command registration
* JSON-based object serialization
* Flexible output formatting
3. Integration Points:
* Persistence service integration
* Security service integration
* Transaction handling
* Event system integration
h3. Testing Strategy:
1. Unit Tests:
* Core command functionality
* Object serialization/deserialization
* Error handling
* Parameter validation
2. Integration Tests:
* End-to-end command execution
* Service integration
* Transaction handling
* Security integration
h3. Migration Plan:
1. Phase 1:
* Implement core framework
* Convert one object type as proof of concept
* Gather feedback from team
2. Phase 2:
* Convert remaining object types
* Keep old commands temporarily
* Update documentation
3. Phase 3:
* Deprecate old commands
* Remove old command code
* Finalize documentation
h3. Success Metrics:
1. Code Quality:
* Reduction in code lines
* Improved test coverage
* Reduced duplicate code
* Fewer bug reports
2. User Experience:
* Reduced command learning time
* Fewer user errors
* Improved help system usage
* Positive user feedback
h3. Risks and Mitigation:
Learning Curve:
* Comprehensive documentation
* Interactive help system
* Example-driven guides
* Gradual migration
This unified approach would significantly improve the maintainability and
usability of Unomi's shell interface while providing a solid foundation for
future extensions.
was:
This proposal suggests replacing our current disparate Karaf shell commands
with a unified CRUD command system that would provide a consistent,
maintainable, and extensible interface for all Unomi objects. This
architectural improvement would offer significant benefits for both developers
and operators.
h3. Current Pain Points:
1. Inconsistent command patterns across different object types
2. Significant code duplication in command implementations
3. Varying parameter names and behaviors
4. Scattered documentation and help text
5. High maintenance overhead
6. Steep learning curve for new users
h3. Proposed Solution:
A unified command structure:
{noformat}
unomi:crud <operation> <type> [id] [options]
Operations:
- create: Create new object from JSON file
- read: Display object details
- update: Update existing object from JSON
- delete: Remove an object
- list: Display objects in table format
- help: Show object type documentation
Options:
--file (-f): JSON file for create/update
--csv: Output in CSV format
--max-entries (-n): Maximum items to display
{noformat}
h3. Example Usage Would Be:
{noformat}
# List all rules
unomi:crud list rule
# Show rule details
unomi:crud read rule rule_id
# Create new rule
unomi:crud create rule --file new_rule.json
# Update existing rule
unomi:crud update rule rule_id --file updated_rule.json
# Delete rule
unomi:crud delete rule rule_id
# Get help for rule properties
unomi:crud help rule
{noformat}
h3. Expected Benefits:
1. Consistency and Usability:
* Single command pattern for all object types
* Consistent parameter naming and behavior
* Unified help system and documentation
* Reduced learning curve for new users
2. Code Maintainability:
* Expected ~75% reduction in command-related code
* Centralized error handling
* Shared pagination and filtering logic
* Common JSON handling for all object types
3. Enhanced Features:
* Built-in CSV output support
* Consistent table formatting
* Property auto-completion
* Rich help documentation for each object type
h3. Proposed Implementation:
1. Core Components:
* CrudCommand interface: Would define CRUD operations
* BaseCrudCommand: Would provide common implementation
* UnomiCrudCommand: Would handle main command routing
* Type-specific implementations (e.g., RuleCrudCommand, ProfileCrudCommand)
2. Key Features:
* OSGi service-based architecture
* Dynamic command registration
* JSON-based object serialization
* Flexible output formatting
3. Integration Points:
* Persistence service integration
* Security service integration
* Transaction handling
* Event system integration
h3. Testing Strategy:
1. Unit Tests:
* Core command functionality
* Object serialization/deserialization
* Error handling
* Parameter validation
2. Integration Tests:
* End-to-end command execution
* Service integration
* Transaction handling
* Security integration
h3. Migration Plan:
1. Phase 1:
* Implement core framework
* Convert one object type as proof of concept
* Gather feedback from team
2. Phase 2:
* Convert remaining object types
* Keep old commands temporarily
* Update documentation
3. Phase 3:
* Deprecate old commands
* Remove old command code
* Finalize documentation
h3. Success Metrics:
1. Code Quality:
* Reduction in code lines
* Improved test coverage
* Reduced duplicate code
* Fewer bug reports
2. User Experience:
* Reduced command learning time
* Fewer user errors
* Improved help system usage
* Positive user feedback
h3. Risks and Mitigation:
Learning Curve:
* Comprehensive documentation
* Interactive help system
* Example-driven guides
* Gradual migration
This unified approach would significantly improve the maintainability and
usability of Unomi's shell interface while providing a solid foundation for
future extensions.
> Unified CRUD Command System: Streamlining Shell Operations with a Consistent
> Interface
> --------------------------------------------------------------------------------------
>
> Key: UNOMI-879
> URL: https://issues.apache.org/jira/browse/UNOMI-879
> Project: Apache Unomi
> Issue Type: Sub-task
> Affects Versions: unomi-3.0.0
> Reporter: Serge Huber
> Assignee: Serge Huber
> Priority: Major
> Fix For: unomi-3.0.0
>
>
> This proposal suggests replacing our current disparate Karaf shell commands
> with a unified CRUD command system that would provide a consistent,
> maintainable, and extensible interface for all Unomi objects. This
> architectural improvement would offer significant benefits for both
> developers and operators.
> h3. Current Pain Points:
> 1. Inconsistent command patterns across different object types
> 2. Significant code duplication in command implementations
> 3. Varying parameter names and behaviors
> 4. Scattered documentation and help text
> 5. High maintenance overhead
> 6. Steep learning curve for new users
> h3. Proposed Solution:
> A unified command structure:
> {noformat}
> unomi:crud <operation> <type> [id] [options]
> Operations:
> - create: Create new object from JSON file
> - read: Display object details
> - update: Update existing object from JSON
> - delete: Remove an object
> - list: Display objects in table format
> - help: Show object type documentation
> Options:
> --file (-f): JSON file for create/update
> --csv: Output in CSV format
> --max-entries (-n): Maximum items to display
> {noformat}
> h3. Example Usage Would Be:
> {noformat}
> # List all rules
> unomi:crud list rule
> # Show rule details
> unomi:crud read rule rule_id
> # Create new rule
> unomi:crud create rule --file new_rule.json
> # Update existing rule
> unomi:crud update rule rule_id --file updated_rule.json
> # Delete rule
> unomi:crud delete rule rule_id
> # Get help for rule properties
> unomi:crud help rule
> {noformat}
> h3. Intelligent Auto-completion Features:
> The unified command system implements rich context-aware auto-completion to
> enhance user productivity:
> 1. Operation Auto-completion:
> {noformat}
> unomi:crud [TAB]
> Completions: create, read, update, delete, list, help
> {noformat}
> 2. Object Type Auto-completion:
> {noformat}
> unomi:crud list [TAB]
> Completions: rule, segment, profile, event, action, property, apikey, schema,
> scope, tenant
> {noformat}
> 3. Object ID Auto-completion:
> {noformat}
> unomi:crud read rule [TAB]
> Completions: [dynamically shows available rule IDs]
> {noformat}
> 4. Property Name Auto-completion:
> For JSON editing, provides context-aware property name suggestions:
> * Rules:
> {noformat}
> {
> "item[TAB]
> Completions: itemId, name, description, condition, actions, priority, metadata
> {noformat}
> * Segments:
> {noformat}
> {
> "item[TAB]
> Completions: itemId, name, description, condition, scope, metadata
> {noformat}
> 5. Property Value Auto-completion:
> Context-sensitive value suggestions for specific properties:
> * API Key Types:
> {noformat}
> "keyType": "[TAB]
> Completions: PUBLIC, PRIVATE
> {noformat}
> * Event Types:
> {noformat}
> "eventType": "[TAB]
> Completions: view, login, sessionCreated, profileUpdated, sessionReassigned,
> updateProperties, formSubmitted, click, download, search,
> videoStarted, videoCompleted
> {noformat}
> * Condition Types:
> {noformat}
> "condition": {
> "type": "[TAB]
> Completions: booleanCondition, profilePropertyCondition,
> sessionPropertyCondition,
> eventPropertyCondition, pastEventCondition, matchAllCondition,
> notCondition, orCondition, andCondition
> {noformat}
> 6. Dynamic Value Completion:
> * Tenant IDs: Auto-completes available tenant identifiers
> * Scope IDs: Auto-completes available scope identifiers
> * Profile IDs: Auto-completes recently updated profile identifiers
> * Schema IDs: Auto-completes installed JSON schema identifiers
> 7. Smart Filtering:
> * All completions are filtered based on the current input prefix
> * Shows only relevant completions based on the current context
> * Supports case-insensitive matching where appropriate
> 8. Help Integration:
> * Property help text is context-aware and shows:
> - Required properties with descriptions
> - Optional properties with descriptions
> - Valid values and formats
> - Examples where applicable
> This comprehensive auto-completion system would:
> * Reduce user errors
> * Speed up command composition
> * Provide inline documentation
> * Guide users through complex object structures
> * Maintain consistency across all object types
> h3. Expected Benefits:
> 1. Consistency and Usability:
> * Single command pattern for all object types
> * Consistent parameter naming and behavior
> * Unified help system and documentation
> * Reduced learning curve for new users
> 2. Code Maintainability:
> * Expected ~75% reduction in command-related code
> * Centralized error handling
> * Shared pagination and filtering logic
> * Common JSON handling for all object types
> 3. Enhanced Features:
> * Built-in CSV output support
> * Consistent table formatting
> * Property auto-completion
> * Rich help documentation for each object type
> h3. Proposed Implementation:
> 1. Core Components:
> * CrudCommand interface: Would define CRUD operations
> * BaseCrudCommand: Would provide common implementation
> * UnomiCrudCommand: Would handle main command routing
> * Type-specific implementations (e.g., RuleCrudCommand, ProfileCrudCommand)
> 2. Key Features:
> * OSGi service-based architecture
> * Dynamic command registration
> * JSON-based object serialization
> * Flexible output formatting
> 3. Integration Points:
> * Persistence service integration
> * Security service integration
> * Transaction handling
> * Event system integration
> h3. Testing Strategy:
> 1. Unit Tests:
> * Core command functionality
> * Object serialization/deserialization
> * Error handling
> * Parameter validation
> 2. Integration Tests:
> * End-to-end command execution
> * Service integration
> * Transaction handling
> * Security integration
> h3. Migration Plan:
> 1. Phase 1:
> * Implement core framework
> * Convert one object type as proof of concept
> * Gather feedback from team
> 2. Phase 2:
> * Convert remaining object types
> * Keep old commands temporarily
> * Update documentation
> 3. Phase 3:
> * Deprecate old commands
> * Remove old command code
> * Finalize documentation
> h3. Success Metrics:
> 1. Code Quality:
> * Reduction in code lines
> * Improved test coverage
> * Reduced duplicate code
> * Fewer bug reports
> 2. User Experience:
> * Reduced command learning time
> * Fewer user errors
> * Improved help system usage
> * Positive user feedback
> h3. Risks and Mitigation:
> Learning Curve:
> * Comprehensive documentation
> * Interactive help system
> * Example-driven guides
> * Gradual migration
> This unified approach would significantly improve the maintainability and
> usability of Unomi's shell interface while providing a solid foundation for
> future extensions.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
