Interface ProgressStatus
-
- All Superinterfaces:
Serializable
- All Known Subinterfaces:
CommandProgress
- All Known Implementing Classes:
CommandProgressImpl
,ProgressStatusBase
,ProgressStatusImpl
,ProgressStatusMirroringImpl
public interface ProgressStatus extends Serializable
API for providing information about work progress inAdminCommand
implementations.Progress is represented by two attributes:
steps
- an integer value which represents units of
progress (a.k.a. steps) taken during command execution to show progress.
Should not be greater than * message
- A progress message to be sent to the client.
totalStepCount
(if defined).Because
AdminCommand
can execute otherAdminCommand
and command execution on a cluster triggers the replication process theProgressStatus
can have child ProgressStatus objects. AnyProgressStatus
can be used independently without knowledge of the parent'sProgressStatus
.
Any child ProgressStatus objects can be named by its creator. Thename
is mainly used in connection with themessage
attribute to define its context.Usage:
First inject a
ProgressStatus
into anAdminCommand
implementation.
Optionally pass the total step count or name to provide context of the progress (if the name is not provided it defaults to the command's name).@Progress private ProgressStatus ps;
@Progress(totalStepCount=10, name="deploy")
Total step count can also be set via this method. This overrides the count if it was previously set (possibly via the @Progress annotation).
setTotalStepCount(int totalStepCount);
The primary use of
tatalStepCount
is as the denominator for computing the completion percentage as reported in the commands progress report:percent complete = current step count / total step count * 100
The total step count can be changed after being set but may result in the completion percentage jumping (forward or backwards).
If the total step count is not set then a completion percentage will not be available.
The
progress()
methods are used to move progress forward (or backwards). The current step count will be incremented by the number of steps indicated.progress(String message, int steps); progress(String message); progress(int steps);
The version of progress that only takes a message will cause a new message to be displayed but will not change the completion percentage.
It is possible to set the current step count to a specific value, for example when an error occurs and the command must repeat a set of operations.
setCurrentStepCount(int stepCount);
This will likely result in the overall completion percentage jumping when the next progress() message is generated.
Any ProgressStatus can be completed using methods
complete(String message); complete();
Indicates the command is complete and no further progress status will be delivered. Subsequent invocations of progress() will be ignored. This method also invokes
complete()
on all child ProgressStatus objects.It is also possible to create a child ProgressStatus with independent logic used to determine progress. The parent
ProgressStatus
is not visible to the child ProgressStatus object and the child can progress somewhat independently from the parent's progress. But generally the parent should not complete its progress before the children have completed.createChild(String name, int allocatedSteps); createChild(int allocatedSteps);
The name allocated to the child is used in the progress status output to define context of the
message
.. 80%: [parent name:[child name:[...]] message
The allocatedSteps parameter represents the subset of steps from the parent's allocation that will be given to the child to complete.
- Author:
- mmares
- See Also:
org.glassfish.api.Progress
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
complete()
Indicates the command is complete and no further progress status will be delivered.void
complete(String message)
Indicates the command is complete and no further progress status will be delivered.ProgressStatus
createChild(int allocatedSteps)
Create a child ProgressStatus object which can be used independently by a command's subroutine or sub-commands.ProgressStatus
createChild(String name, int allocatedSteps)
Create a child ProgressStatus object which can be used independently by a command's subroutine or sub-commands.String
getId()
Id is unique for any ProgressStatuses.int
getRemainingStepCount()
Remaining count of steps to complete this progress.
totalStepCount - currentStepCount - allocated step count
int
getTotalStepCount()
Total step count.boolean
isComplete()
Returns true if theProgressStatus
has been marked as complete via thecomplete()
method.void
progress(int steps)
Indicate progress occurred.void
progress(int steps, String message)
Indicates progress occurred.void
progress(int steps, String message, boolean spinner)
Indicates progress occurred.void
progress(String message)
Indicate progress occurred.void
setCurrentStepCount(int stepCount)
This allows the current step count to be changed to a specific value, for example when an error occurs and the command must repeat a set of operations.
This will likely result in the overall completion percentage jumping when the next progress() message is generated.void
setTotalStepCount(int totalStepCount)
Number of steps necessary to complete the operation.
-
-
-
Method Detail
-
setTotalStepCount
void setTotalStepCount(int totalStepCount)
Number of steps necessary to complete the operation. Value is used to determine percentage of work completed. This method can be used to override the totalStepCount if it was established via theorg.glassfish.api.Progress
annotation. The total step count is used as the denominator for computing the completion percentage as reported in the command's progress output:percent complete = current step count / total step count * 100
Note the above formula is a bit more complex when child ProgressStatus objects are in use.The total step count can be changed after being set but may result in the completion percentage jumping (forward or backwards).
If the total step count is not set then a completion percentage will not be available.
It can be also set during injection using
totalStepCount
parameter inorg.glassfish.api.Progress
annotation.- Parameters:
totalStepCount
- non-negative value defines denominator for the percentage computation
-
getTotalStepCount
int getTotalStepCount()
Total step count. Used for computing the completion percentage.- Returns:
- total step count. Negative for undefined value.
-
getRemainingStepCount
int getRemainingStepCount()
Remaining count of steps to complete this progress.
totalStepCount - currentStepCount - allocated step count
- Returns:
- negative value for undefined totalStepCount. 0 value for completed progress.
-
progress
void progress(int steps, String message, boolean spinner)
Indicates progress occurred. The steps taken will be used to reduce the remaining step count. If the number of steps taken exceeds the total step count the current step count will be normalized to the total step count. This avoids the completion percentage ever exceeding 100%. The message will be sent to the client along with the completion percentage if it can be computed.- Parameters:
steps
- the number of steps taken. Negative steps will reduce the completion percentage. Never to non-negative value.message
- to be displayed by the client.spinner
-true
starts showing the spinner. It will be active until next progress.
-
progress
void progress(int steps, String message)
Indicates progress occurred. The steps taken will be used to reduce the remaining step count. If the number of steps taken exceeds the total step count the current step count will be normalized to the total step count. This avoids the completion percentage ever exceeding 100%. The message will be sent to the client along with the completion percentage if it can be computed.- Parameters:
steps
- the number of steps taken. Negative steps will reduce the completion percentage. Never to non-negative value.message
- to be displayed by the client.
-
progress
void progress(int steps)
Indicate progress occurred. The existing (prior) progress message, if available will be reused. If the number of steps taken exceeds the total step count the current step count will be normalized to the total step count. This avoids the completion percentage ever exceeding 100%.- Parameters:
steps
- the number of steps taken. Negative steps will reduce the completion percentage. Never to non-negative value.
-
progress
void progress(String message)
Indicate progress occurred. The completion percentage (if computable) will be displayed.- Parameters:
message
- to be displayed by the client.
-
setCurrentStepCount
void setCurrentStepCount(int stepCount)
This allows the current step count to be changed to a specific value, for example when an error occurs and the command must repeat a set of operations.
This will likely result in the overall completion percentage jumping when the next progress() message is generated. If child ProgressStatus objects exist care must be taken when changing the step count value to account for steps allocated to children. Generally the current step count should not be advanced beyond the number of steps allocated to child ProgressStatus objects.- Parameters:
stepCount
- newstepCount
value. Negative is normalized to 0 greater than the total step count is normalized to the total step count
-
complete
void complete(String message)
Indicates the command is complete and no further progress status will be delivered. Subsequent invocations of progress() will be ignored. This method also invokescomplete()
on all child ProgressStatus objects. If this method is not invoked prior to the command completing the CLI framework will implicitly invokecomplete()
for the ProgressStatus associated with the command.- Parameters:
message
- to be displayed to the user.
-
complete
void complete()
Indicates the command is complete and no further progress status will be delivered. Subsequent invocations of progress() will be ignored. This method also invokescomplete()
on all child ProgressStatus objects. If this method is not invoked prior to the command completing the CLI framework will implicitly invokecomplete()
for the ProgressStatus associated with the command.
-
isComplete
boolean isComplete()
Returns true if theProgressStatus
has been marked as complete via thecomplete()
method.- Returns:
- if this progress was completed
-
createChild
ProgressStatus createChild(String name, int allocatedSteps)
Create a child ProgressStatus object which can be used independently by a command's subroutine or sub-commands.
The name allocated to the child is used in the progress status output:
80%: [parent name:[child name: message]]
The allocatedSteps parameter represents the subset of steps from the parent's allocation that will be given to the child to complete. When the child has completed all its steps it will have progressed the parent's allocated steps.
Example: Suppose the parent sets its TotalStepCount to 100 and allocates 25 steps to a child. The child sets its TotalStepCount to 100. Then for every 4 steps the child progresses it will move the parent's progress 1 step given the parent only allocated a total of 25 steps to the child but the child has a total step count of
100: 100/25 = 4
child steps are equivalent to 1 parent step. Note: care must be taken when allocating steps to children. The number of steps allocated to all children of the parent must not exceed the parent's total step count. Doing so may results in erroneous completion percentages.- Parameters:
name
- to be associated with the child ProgressStatus. This name appears in the progress sent to the client. If the name is an empty string a name for this child will not be included in the message.allocatedSteps
- the number of progress steps the parent is allocating to the child.
-
createChild
ProgressStatus createChild(int allocatedSteps)
Create a child ProgressStatus object which can be used independently by a command's subroutine or sub-commands.
This version does not take a name and therefor a child name will not be use in any messages generated from this ProgressStatus object.80%: [parent name: message]
- Parameters:
allocatedSteps
- the number of progress steps the parent is allocating to the child.
-
getId
String getId()
Id is unique for any ProgressStatuses. It is mainly used for remote communication.
-
-