org.glassfish.api.admin.progress

Class ProgressStatusBase

java.lang.Object

org.glassfish.api.admin.progress.ProgressStatusBase

All Implemented Interfaces:

ProgressStatus

Direct Known Subclasses:

ProgressStatusImpl, ProgressStatusMirroringImpl

public abstract class ProgressStatusBase
extends Object
implements ProgressStatus

Basic abstract implementation of ProgressStatus.

Author:

mmares

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ProgressStatusBase.ChildProgressStatus

Field Summary

Fields

Modifier and Type	Field and Description
protected Set<ProgressStatusBase.ChildProgressStatus>	children
protected boolean	completed
protected int	currentStepCount
protected String	id
protected String	name
protected ProgressStatusBase	parent
protected int	totalStepCount

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ProgressStatusBase(ProgressStatusBase parent, String id) Construct unnamed ProgressStatus
protected	ProgressStatusBase(String name, int totalStepCount, ProgressStatusBase parent, String id) Construct named ProgressStatus with defined expected count of steps.
protected	ProgressStatusBase(String name, ProgressStatusBase parent, String id) Construct named ProgressStatus.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	allocateStapsForChildProcess(int allocatedSteps)
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.
protected boolean	completeSilently() Complete this ProgressStatus and all sub-ProgressStatuses but does not fire event to parent statuses.
float	computeCompletePortion()
protected float	computeCompleteSteps()
int	computeSumSteps()
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.
ProgressStatus	createChild(String name, int allocatedSteps, int totalStepCount)
protected abstract ProgressStatusBase	doCreateChild(String name, int totalStepCount)
protected ProgressStatusBase	findById(String id) Recursive search for child by id.
protected void	fireEvent(ProgressStatusEvent event) Fires ProgressStatusEvent to parent.
Set<ProgressStatusBase.ChildProgressStatus>	getChildProgressStatuses()
Collection<ProgressStatusBase>	getChildren()
int	getCurrentStepCount()
String	getId() Id is unique for any ProgressStatuses.
String	getName()
ProgressStatusBase	getParrent()
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 the ProgressStatus has been marked as complete via the complete() 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.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

name

protected String name

id

protected String id

totalStepCount

protected int totalStepCount

currentStepCount

protected int currentStepCount

parent

protected ProgressStatusBase parent

completed

protected boolean completed

children

protected Set<ProgressStatusBase.ChildProgressStatus> children

Constructor Detail

ProgressStatusBase

protected ProgressStatusBase(ProgressStatusBase parent,
                  String id)

Construct unnamed ProgressStatus

Parameters:

parent - Parent ProgressStatus

id - Is useful for event transfer

ProgressStatusBase

protected ProgressStatusBase(String name,
                  ProgressStatusBase parent,
                  String id)

Construct named ProgressStatus.

Parameters:

name - of the ProgressStatus implementation is used to identify source of progress messages.

parent - Parent ProgressStatus

id - Is useful for event transfer

ProgressStatusBase

protected ProgressStatusBase(String name,
                  int totalStepCount,
                  ProgressStatusBase parent,
                  String id)

Construct named ProgressStatus with defined expected count of steps.

Parameters:

name - of the ProgressStatus implementation is used to identify source of progress messages.

totalStepCount - How many steps are expected in this ProgressStatus

parent - Parent ProgressStatus

id - Is useful for event transfer

Method Detail

fireEvent

protected void fireEvent(ProgressStatusEvent event)

Fires ProgressStatusEvent to parent.

setTotalStepCount

public void setTotalStepCount(int totalStepCount)

Description copied from interface: ProgressStatus

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 the org.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 in org.glassfish.api.Progress annotation.

Specified by:

setTotalStepCount in interface ProgressStatus

Parameters:

totalStepCount - non-negative value defines denominator for the percentage computation

getTotalStepCount

public int getTotalStepCount()

Description copied from interface: ProgressStatus

Total step count. Used for computing the completion percentage.

Specified by:

getTotalStepCount in interface ProgressStatus

Returns:

total step count. Negative for undefined value.

getRemainingStepCount

public int getRemainingStepCount()

Description copied from interface: ProgressStatus

Remaining count of steps to complete this progress.
totalStepCount - currentStepCount - allocated step count

Specified by:

getRemainingStepCount in interface ProgressStatus

Returns:

negative value for undefined totalStepCount. 0 value for completed progress.

progress

public void progress(int steps,
            String message,
            boolean spinner)

Description copied from interface: ProgressStatus

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.

Specified by:

progress in interface ProgressStatus

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

public void progress(int steps,
            String message)

Description copied from interface: ProgressStatus

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.

Specified by:

progress in interface ProgressStatus

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

public void progress(int steps)

Description copied from interface: ProgressStatus

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%.

Specified by:

progress in interface ProgressStatus

Parameters:

steps - the number of steps taken. Negative steps will reduce the completion percentage. Never to non-negative value.

progress

public void progress(String message)

Description copied from interface: ProgressStatus

Indicate progress occurred. The completion percentage (if computable) will be displayed.

Specified by:

progress in interface ProgressStatus

Parameters:

message - to be displayed by the client.

setCurrentStepCount

public void setCurrentStepCount(int stepCount)

Description copied from interface: ProgressStatus

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.

Specified by:

setCurrentStepCount in interface ProgressStatus

Parameters:

stepCount - new stepCount value. Negative is normalized to 0 greater than the total step count is normalized to the total step count

complete

public void complete(String message)

Description copied from interface: ProgressStatus

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. If this method is not invoked prior to the command completing the CLI framework will implicitly invoke complete() for the ProgressStatus associated with the command.

Specified by:

complete in interface ProgressStatus

Parameters:

message - to be displayed to the user.

completeSilently

protected boolean completeSilently()

Complete this ProgressStatus and all sub-ProgressStatuses but does not fire event to parent statuses.

complete

public void complete()

Description copied from interface: ProgressStatus

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. If this method is not invoked prior to the command completing the CLI framework will implicitly invoke complete() for the ProgressStatus associated with the command.

Specified by:

complete in interface ProgressStatus

isComplete

public boolean isComplete()

Description copied from interface: ProgressStatus

Returns true if the ProgressStatus has been marked as complete via the complete() method.

Specified by:

isComplete in interface ProgressStatus

Returns:

if this progress was completed

doCreateChild

protected abstract ProgressStatusBase doCreateChild(String name,
                               int totalStepCount)

allocateStapsForChildProcess

protected void allocateStapsForChildProcess(int allocatedSteps)

createChild

public ProgressStatus createChild(String name,
                         int allocatedSteps,
                         int totalStepCount)

createChild

public ProgressStatus createChild(String name,
                         int allocatedSteps)

Description copied from interface: ProgressStatus

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.

Specified by:

createChild in interface ProgressStatus

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

public ProgressStatus createChild(int allocatedSteps)

Description copied from interface: ProgressStatus

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] 
 

Specified by:

createChild in interface ProgressStatus

Parameters:

allocatedSteps - the number of progress steps the parent is allocating to the child.

getCurrentStepCount

public int getCurrentStepCount()

computeCompleteSteps

protected float computeCompleteSteps()

computeCompletePortion

public float computeCompletePortion()

computeSumSteps

public int computeSumSteps()

toString

public String toString()

Overrides:

toString in class Object

getChildren

public Collection<ProgressStatusBase> getChildren()

getChildProgressStatuses

public Set<ProgressStatusBase.ChildProgressStatus> getChildProgressStatuses()

getId

public String getId()

Description copied from interface: ProgressStatus

Id is unique for any ProgressStatuses. It is mainly used for remote communication.

Specified by:

getId in interface ProgressStatus

getName

public String getName()

getParrent

public ProgressStatusBase getParrent()

findById

protected ProgressStatusBase findById(String id)

Recursive search for child by id.