Admin Command Progress Status One Pager (template version 1.92)
1. Introduction 1.1. Project/Component Working Name: Admin Command Progress Status 1.2. Name(s) and e-mail address of Document Author(s)/Supplier: Chris Kasso: chris.kasso@oracle.com 1.3. Date of This Document: 04/22/2011 2. Project Summary 2.1. Project Description: Long running admin commands do not have a mechanism to provide ongoing progress as they work to complete the task. This feature provides such a mechanism. 2.2. Risks and Assumptions:
- A long running command may run for hours before completing.
- Several long running commands may be active simultaneously.
Note any risks, and assumptions that must be considered along with the proposal. Include technical risks. 3. Problem Summary 3.1. Problem Area: If the user has defined a large cluster it may take a significant amount of time to start the instances which are associated with the cluster. Similarly deploying a large application to a cluster may take a significant amount of time. Providing on-going progress updates during these operations reassures the user that the operation is proceeding. 3.2. Justification: The primary justification is to provide a better user experience. 4. Technical Description: 4.1. Details: TBD. Several approaches are under investigation. The requirements for this feature will provide an overview of the functionality that is being considered. The design considerations and approach is covered in the
Admin Command Progress Design Spec. This feature can be implemented in multiple phases. The first phase would include the ability for long running commands to provide on-going progress as they execute. The asadmin client would remain connected (as it does today) for the duration of the command execution. The second phase of this project will provide for the ability of the asadmin client to disconnect from the long running command. The user would be provided with the ability to later query for status by reconnecting to the DAS. The user would also be able to query the DAS for a list of long running commands that have available status to be retrieved. This feature will have impact on the Admin Console, IDE's and the REST implementation. For 3.2 it is likely only phase 1 will be implemented. The final decision is pending final resources and cost estimates for other 3.2 requirements. 4.2. Bug/RFE Number(s):
4.3. In Scope:
- Support for a select set of existing remote commands:
- New IAAS based long running commands.
4.4. Out of Scope:
- Support for local commands.
4.5. Interfaces: Interfaces may be commands, files, directory structure, ports,
DTD/Schema, tools, APIs, CLIs, etc.
Note: In lieu of listing the interfaces in the one pager, providing
a link to another specification which defines the interfaces
is acceptable. 4.5.1 Public Interfaces In phase 1 it may be necessary for the implementation of a command to indicate it may be long running command through a new annotation. The command's implementation would likely interact with new methods of the existing ActionReport interface or a new object would be used as the channel to return progress reports. The output format of the CLI will change for long running commands - if a TTY is available and the --terse option is not specified. The REST interface will need to be changed to accommodate accessing progress reports. In phase 2 (if implemented) a new sub-command option would be introduced to support async mode - that is the command does not wait for the results. New sub-commands would be introduced to query available command results (and the status of the executing command) as well retrieve the results from the DAS. In phase 2 we would introduce new configuration for the DAS which controls the lifecycle of the progress store including how much progress information should be maintained and its expiry information. Phase 1 public interfaces:
- Interface: TBD: @ProgressStatus
- Comment: Indicates the command will run in a independent thread and provide ongoing progress reports.
- Interface: TBD: ProgressReport interface
- Comment: Provide a mechanism for a command to return ongoing progress status.
4.5.2 Private Interfaces List private interfaces which are externally observable.
4.5.3 Deprecated/Removed Interfaces: No interfaces will be removed as part of this project. 4.6. Doc Impact: Phase 1: Minimal impact to user documentation as no new commands or options will be added. Existing long running commands for start-cluster and deploy will provide additional progress feedback during operation. The additional feedback may not be provide in certain modes of operation (e.g. --terse). It is likely the Admin Console will be modified to represent progress for long running commands. These changes may potentially impact existing documentation. To the extent that we provide developer documentation about how to implement a command it would be necessary to add additional documentation to cover how a command implementation would provide feedback during an operation. The new progress mechanism would also likely impact any REST interface documentation related to commands that provide progress status. Phase 2: An async or disconnected mode version of asadmin would be supported. This would offer a new asadmin option to indicate the command should disconnect after launching the operation. A discussion of the two modes would need to be provided. New subcommands would be provided to access progress status maintained in the DAS. New DAS configuration options would be provided to allow the admin to customize the amount of unretrieved progress status the DAS will maintain as well as the expiry period for that content. 4.7. Admin/Config Impact: How will this change impact the administration of the product? Phase 1 does not modify how the product is administered. If phase 2 is implemented we would introduce new configuration to control the lifecycle and expiry of progress maintained by the DAS. New CLI would be added to support this. The Console should be modified to graphically represent (e.g. progress bar) progress generated from long running commands. 4.8. HA Impact: This feature has no impact on high availability. A challenge for this feature is handling the case for long running commands which use the command replication framework to distribute the command to running instances in a cluster. If a long running command uses the replication facility we will need to determine a mechanism to provide progress for each of the replicated commands. 4.9. I18N/L10N Impact: As a byproduct of this feature certain commands (e.g. deploy, start-cluster) will introduce new strings in order to provide progress status. Those strings will require l10n. 4.10. Packaging, Delivery & Upgrade: 4.10.1. Packaging This feature will reuse existing packages. No new IPS packages will be required. 4.10.2. Delivery The feature has no impact on product delivery or installation. 4.10.3. Upgrade and Migration: This feature has no impact on upgrade or migration. 4.11. Security Impact: If phase 2 is implemented we need to address the implications of a different user with asadmin privileges accessing the progress status of a command executed by a different user. Depending on the final design there may be security impact between the client the DAS in regards to how the connection is managed to retrieve progress from a long running command. How does this proposal interact with security-related APIs or interfaces? Does it rely on any Java policy or platform user/permissions implication? If the feature exposes any new ports, Or any similar communication points which may have security implications, note these here. 4.12. Compatibility Impact While CLI output is generally considered an unstable interface the introduction of additional progress feedback would change an existing command's CLI output (deploy, start-cluster). Scripts which currently consume this output may break. If the command is invoked with the --terse option the output would not include progress status. TBD: if the CLI has no associated TTY then we could consider not providing progress status. There may be similar impact for users using the REST interface. 4.13. Dependencies: An internal dependency is a dependency on a project, module,
component or product that is within the GlassFish project.
An external dependency is a dependency on a project, component
or product that resides outside of the GlassFish project. 4.13.1 Internal Dependencies TBD. List all internal dependencies this proposal has on other
software. Include component version requirements if necessary. 4.13.2 External Dependencies TBD - likely none. List all external dependencies this proposal has on other
software. Indicate if the software is open source, what
license terms the software is released under and the version
of the software that is being consumed by this project. 4.14. Testing Impact: How will the new feature(s) introduced by this project be tested?
Do tests exist from prior releases (e.g. v2) that can be reused?
Will new tests need to be written? Can they be automated? Indicate which milestones from the current schedule the project
will be:
- Initially integrated (may not be feature complete)
- Feature complete (ready for handoff to QA)
- At production quality level
| Comment ID |
Location |
Comment |
| PMD-001 |
4.6. Doc Impact |
All examples in the man pages, Quick Start Guide, Administration Guide, and Application Deployment Guide that include the affected subcommands will have to be updated to show the current output from these subcommands. The documentation plan for this feature ought to itemize the required changes. |
| PMD-002 |
4.6. Doc Impact |
Detailed instructions for extending the asadmin utility are already provided in the product documentation. These instructions will have to be updated to explain how to enable a subcommand to provide progress feedback.The documentation plan for this feature ought to itemize the required changes. |
| PMD-003 |
4.6. Doc Impact |
The REST interface documentation does not describe REST interfaces for individual subcommands and, therefore, might not be affected by this feature. If any changes are necessary, the documentation plan for this feature ought to itemize the changes. |
 Posted by pauldavies at May 09, 2011 17:24
|
|
