GlassFish - World's first Java EE 7 Application Server


Admin Command Progress Design Spec (v0.1)

This document captures the design for the Admin Command Progress feature to be used by long running commands.

Note: This is an initial version of the design doc and thus does not capture much design yet.

1.0 Design Areas

The following enumerates areas where some level of design is required in order to implement this feature.

# Name Description
1.0 Client side (asadmin) How do we need to evolve the client side CLI framework to handle long-running commands. Do we use polling, comet style techniques, or some alternative.
1.1 Client side (REST) How will the REST interface need to evolve to retrieve on-going status from long running commands?
1.2 asadmin CLI How will the asadmin CLI need to change to support sync and async commands as well as support the ability to retrieve status from async long running commands?
1.3 Command replication How will the existing command replication mechanism in the DAS need to be modified to properly support reporting progress back to the client for the replicated commands? The initial commands targeted for progressization do not use the replication code so no work may be required here for the initial implementation.
1.4 DAS progress store For async commands (if supported) it will be necessary for a service in the DAS to maintain progress in a store until the progress is retrieved or expires. The service will need to manage the lifecycle of this store. The general feeling is this store should hold progress in non-persistent storage.
1.4.1 Progress store characteristics How does the contents of the store expire? How do we limit the amount of progress maintained for a specific command. How is the progress status reaped? How do we expose configuration of these characteristics?
1.5 Server side command impl A mechanism needs to be provided to allow a command implementation to indicate it is long running (e.g. use an annotation?). A mechanism needs to be provided to allow the command impl to return results (and overall progress indication) in a piecemeal format. This may have impact on the threading model for command execution.

Other considerations:

  • If we choose to support the async (disconnected) command mode what are the security implications of other users viewing the progress of commands?
  • Follow up with the IDE folks to understand how the interact with the REST interface.
  • Proxies: Will they cache partial results of an open HTTP Request?
  • Proxies: Will they close an HTTP Request after a period of time if no traffic has been generated?

2.0 Scenarios

  • Synchronous (asadmin does not return until the command completes)
    • Command completes normally (successfully or with error)
    • Connection lost before command completes (some progress may have been delivered to the user)
  • Asynchronous, progress tracking ID returned. (asadmin returns after options/operand have been validated)
    • Status for completed command retrieved at a future time.
    • Status for an executing command is retrieved (e.g. progress status to-date)
    • Status for a failed command is retrieved (e.g. the command completed but it indicated failure)
    • Status for a completed command is retrieved but the progress ID has expired.
    • Status for the executing command begins to expire in the store prior to the command completing.

3.0 CLI

3.1 CLI - Progress Representation

  • How should the CLI represent the progress for a command.
    • Example 1 (as a percentage):
      • 30%: Progress status text...
      • 50%: Progress status text...
      • 80%: Progress status text...
    • Example 2 (as a ratio):
      • 1/35: Progress status text...
      • 5/35: Progress status text...
      • 25/35: Progress status text...
    • Example 3 (if we know no progress text will be provided but ratio/percent metadata will be available - represent the progress in place if a TTY is available):
      • 30% -> 40% -> 50% or 1/35 -> 2/35 -> 3/35
    • Example 1 and 2 could also update the text in place. TBD.

3.2 CLI - Async Support

  • In the async mode what status is returned:
    • if the command has not completed yet.
    • if the command has completed.
    • if the results we are retrieving have expired.
  • CLI to list unexpired/unretrieved command status: list-command-status
  • CLI to list progress of specific command: show-command-status 1234

If we are going to allow async commands to run there will likely be a need to stop/kill a long running async command. In the existing asadmin implementation if a user ctrl-C's asadmin the server side command continues to execute. At this point in time we don't feel there is a need to provide a mechanism to kill async mode long running commands (e.g. stop-command 1234).

4.0 Misc

  • Phasing of features
    • Phase 1: Support for synchronous progress status. This limits the amount of new CLI that needs to be introduced in 3.2
    • Phase 2: Support for asynchronous progress status (i.e. asadmin disconnects from the command execution).

5.0 References