Skip to main content

New enhancements to Admin Command framework in Glassfish 4.0

Posted by bhaktimehta on June 13, 2013 at 9:26 AM PDT

Glassfish 4.0 is released. This is the reference implementation for Java EE 7 and focusses on HTML 5 and improving developer productivity. You can download the bits from here https://glassfish.java.net/download.html

Apart from the Java EE 7 support in GlassFish 4.0 there have been numerous other areas where Glassfish 4 has provided lots of improvements and innovation
Martin Mares , Chris Kasso and I have been working on the Admin Command Framework.
These are some new enhancements that were added to Glassfish 4.0.

o Support for Progress status using Server Sent Events
o Job Management support

Support for Progress status in commands using Server Sent Events.


This section will cover the newly introduced @Progress annotation. We will walk through the basic usages of Progress API.
Next we will see how ServerSentEvents fits in with the Progress API.

Progress API in Glassfish 4.0


Consider some long running commands say start-cluster. It would be useful to be notified about the progress of the command as it is executing.
To facilitate support for Progress status in AdminCommands a new annotation @Progress is added.

Any command which wants to use the Progress status API can be annotated with @Progress
The ProgressStatus object can be obtained from the AdminCommandContext.
The Progress API can be used to specify the total steps for execution. Once the total steps are known the percentage can be computed.
Additionally the ProgressStatus API takes a message that can be added as the command progresses like Installing, Parsing... etc.
As the command is executing, the progress can be updated by specifying the steps and the message to be sent to the client.

@Progress
public class SomeCommand implements AdminCommand {

  public void execute(AdminCommandContext context) {

       ProgressStatus ps = context.getProgressStatus();
       ps.setTotalStepCount(3);
       ...
       ..
       ps.progress(1, "Parsing files..");

The above snippet shows the @Progress annotation on the command. It also demonstrates how to get the ProgressStatus object from the AdminCommandContext.
It shows how to use the ProgressStatus.progress() method to specify the number of steps taken and a message to be emitted.
Here is the Progress Status API which command developers can read for detailed information. http://grepcode.com/file/maven.java.net/content/groups/promoted/org.glas...

Using ServerSentEvents to emit progress


Server-Sent Events (SSE) is a technology for providing push notifications from servers to clients once an initial client connection has been established.
For our case of long running commands which emits progress as it executes, the server can continuously sending the progress using Server Sent Events API.

Definition of a ManagedJob


Any command which has progress information in it ie annotated with @Progress or which is run with --detach (See section below) option is known as a ManagedJob. Each job has a job id associated with it.
You can query the status of a ManagedJob using list-jobs command.

How it fits together


1. When a managed job is executed in GlassFish the REST client will open an SSE connection with header Accept: text/event-stream.
2. The command gets executed on a dedicated thread pool which is provided by the JobManager.
3. Once the channel of communication is established all the progress feedback is sent as Server Sent Events and the channel is kept open to keep sending progress as it occurs.
4. The Response is closed when the command finishes execution.


The above figure shows the interaction between the Server and the command which is annotated with @Progress executed by the client.
The progress is sent via SSE and finally the ActionReport is sent once the command finishes execution.

Job Management commands


These are newer commands which are introduced
  • detach option to commands
  • attach command
  • list-jobs command
  • configure-managed-jobs

detach option to commands


Any command can be run with --detach option. This will give a job id associated with the command and the job is run in the background.
You can then lookup the job using the list-jobs command. (Similar to the jobs command in Unix)
You can later attach to the job using the attach command with the job id too and see the progress.

attach command


The following image shows a sample command started by the client which emits progress status information.
1. Client 1 starts the sample command which has some progress information
2. The server executes the command and sends the progress to the client using ServerSentEvents.

You can open another terminal for Client 2 and
attach to the same job and see the same progress updates on both the clients.


Fig 1. Multiple clients attaching to get progress via Server Sent Events.

Bboth the terminals Client1 and Client2 are both getting the same set of progress related Server Sent Events at the same time. Even if one client kills using Ctrl C the other will still see the updates.

list-jobs


The list-jobs command can provide information regarding the jobs.
It lists the job id, the name, the time the job was started, the state and the Exitcode.
Here is a sample output of list-jobs command
asadmin list-jobs
NAME                         JOB ID   TIME                                STATE                EXIT CODE   USER 
sample-command1   1            2013-02-05 14:11:24   COMPLETED   SUCCESS     admin

You can even run list-jobs with a single job id

asadmin list-jobs 1
NAME                         JOB ID   TIME                                STATE                EXIT CODE   USER 
sample-command1   1            2013-02-05 14:11:24   COMPLETED   SUCCESS     admin

Using curl to get the data of the list-jobs
This will get the information of all jobs 
curl  -vSs -H 'X-Requested-By foo' -X GET http://localhost:4848/management/jobs

This will get the information of job whose id is 1
curl  -vSs -H 'X-Requested-By foo' -X GET http://localhost:4848/management/jobs/id/1

configure-manage-jobs command


The configure-managed-jobs command is used to clean up these ManagedJobs. By default the job retention period is 24 hours. But using this command you can specify how long you want to keep the jobs.

How you can contribute

Download GlassFish 4.0 from https://glassfish.java.net/download.html and try the newer features.
Java EE 7 tutorial is here http://docs.oracle.com/javaee/7/tutorial/doc/home.htm
You can file bugs using this link https://java.net/jira/browse/GLASSFISH
Provide feedback at users@glassfish.dev.java.net.

AttachmentSize
image.png83.96 KB
sse.png31.8 KB