com.ibm.datapower.wamt.clientAPI
Class MacroProgressContainer

java.lang.Object
  extended by com.ibm.datapower.wamt.clientAPI.MacroProgressContainer

public class MacroProgressContainer
extends java.lang.Object

A MacroProgressContainer is a container for multiple ProgressContainers. This class is typically used for ManagedSet operations, since a ManagedSet typical contains multiple Device objects, and long running operations performed on Device are wrapped in a ProgressContainer.

The execution of MacroProgressContainer is considered to have an error if any of the individual ProgressContainer tasks have an error. The execution of a MacroProgressContainer is considered to be complete only when all of ProgressContainer tasks it contains objects are complete.

A MacroProgressContainer may find an exception in any of its nested ProgressContainer objects, or it may have an exception itself. A MacroProgressContainer can wait for all the nested ProgressContainer objects to be complete, and it must wait for itself to be marked complete. However, a MacroProgressContainer doesn't have any steps or step descriptions itself, those come only from the nested ProgressContainer objects.

See Also:
ProgressContainer

Field Summary
static java.lang.String COPYRIGHT_2009_2013
           
static int DEFAULT_SLEEP_MS
          The default time for the sleep interval while polling for update or completion.
 
Method Summary
 void blockAndTrace(java.util.logging.Level level)
          A convenience method for waiting for the tasks to complete and printing the progress of each step for each nested ProgressConatiner.
 java.lang.Object getCorrelator()
          Get the correlator for this MacroProgressContainer.
 int getCurrentStep()
          Get the current step which indicates the progress across the total number of steps in this MacroContainer.
 java.lang.String getCurrentStepDescription()
          Get the description of the most recently updated step across all the nested ProgressContainers.
 java.lang.Exception getError()
          Return the Exception from any of the nested ProgressContainers or from this MacroProgressContainer.
 java.util.Hashtable getFailedTasks()
           
 ProgressContainer[] getProgressContainers()
          Returns the nested ProgressContainers for any returned values or errors.
 int getSleepInterval()
          Gets the interval between checks through all the nested ProgressContainers for any that may have had an update.
 Task getTask()
          Get the Task for which this MacroProgressContainer has been created.
 int getTotalSteps()
          Get the total number of steps across all the nested ProgressContainers.
 boolean hasError()
          Check if any of the nested ProgressContainers or this MacroProgressContainer has an error set.
 boolean hasUpdate()
          Check if any of the nested ProgressContainers has an update.
 boolean isComplete()
          Check if this MacroProgressContainer is complete.
 void setCorrelator(java.lang.Object correlator)
          Set the correlator for this MacroProgressContainer.
 void setFailedTasks(java.util.Hashtable failedTasks)
           
 void setSleepInterval(int ms)
          Sets the interval between checks through all the nested ProgressContainers for any that may have had an update.
 java.lang.String toString()
          Get a String representation of this object for the purpose of debugging or tracing.
 void waitForEnd()
          Block until all of the nested ProgressContainers are complete.
 void waitForUpdate()
          Block until one of the nested ProgressContainers has an update.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_SLEEP_MS

public static final int DEFAULT_SLEEP_MS
The default time for the sleep interval while polling for update or completion.

See Also:
setSleepInterval(int), Constant Field Values

COPYRIGHT_2009_2013

public static final java.lang.String COPYRIGHT_2009_2013
See Also:
Constant Field Values
Method Detail

getSleepInterval

public int getSleepInterval()
Gets the interval between checks through all the nested ProgressContainers for any that may have had an update. For more information about this, see setSleepInterval(int).

Returns:
the interval in milliseconds that it sleeps before checking all the nested ProgressContainers for any that may be updated.
See Also:
setSleepInterval(int), waitForUpdate(), waitForEnd()

setSleepInterval

public void setSleepInterval(int ms)
Sets the interval between checks through all the nested ProgressContainers for any that may have had an update. Since there generally are multiple ProgressContainers involved, there isn't any easy way to block in such a way that waitForUpdate() or waitForEnd() will return if any of them get an update. Because polling must be used, this is how long waitForUpdate() or waitForEnd() method should wait before checking all the ProgressContainers for update or completion. You should pick a value here that is a good balance between responsiveness and consuming too much CPU doing the poll.

Parameters:
ms - the interval between checks through all the nested ProgressContainers for any that may have had an update. If not set explicitly, the default is DEFAULT_SLEEP_MS.
See Also:
getSleepInterval(), waitForUpdate(), waitForEnd()

waitForUpdate

public void waitForUpdate()
                   throws java.lang.InterruptedException
Block until one of the nested ProgressContainers has an update. You can use this method to "block" in a CPU-friendly way to wait until there is an update available. Because there is not a good way to truly block until one of the nested ProgressContainers has an update, this method will poll all the nested ProgressContainers to check for updates, then will sleep for the duration specified by setSleepInterval(int) until the next check.

See Also:
ProgressContainer.waitForUpdate(), hasUpdate()

waitForEnd

public void waitForEnd()
                throws java.lang.InterruptedException
Block until all of the nested ProgressContainers are complete. You can use this method to "block" in a CPU-friendly way to wait until completion is reached. Because there is not a good way to truly block until all of the nested ProgressContainers are complete, this method will poll all the nested ProgressContainers to check for completion, then will sleep for the duration specified by setSleepInterval(int) until the next check.

See Also:
ProgressContainer.waitForEnd(), isComplete()

hasUpdate

public boolean hasUpdate()
Check if any of the nested ProgressContainers has an update.

Returns:
true if any of the nested ProgressContainers has an update, false otherwise.
See Also:
waitForUpdate(), ProgressContainer.hasUpdate()

getTotalSteps

public int getTotalSteps()
Get the total number of steps across all the nested ProgressContainers. This should be the sum of the total tasks in each ProgressContainer.

Returns:
the total number of steps across all the nested ProgressContainers.
See Also:
ProgressContainer.getTotalSteps(), getCurrentStep()

getTask

public Task getTask()
Get the Task for which this MacroProgressContainer has been created. With this Task object, you can retrieve metadata about this macro task.

Returns:
the Task for which this MacroProgressContainer has been created.
See Also:
ProgressContainer.getTask()

getCurrentStep

public int getCurrentStep()
Get the current step which indicates the progress across the total number of steps in this MacroContainer. This should be the sum of the current steps across all the nested ProgressContainers.

Returns:
the current step which indicates the progress across the total number of steps in this MacroContainer.
See Also:
getTotalSteps(), ProgressContainer.getCurrentStep(), getCurrentStepDescription()

getCurrentStepDescription

public java.lang.String getCurrentStepDescription()
Get the description of the most recently updated step across all the nested ProgressContainers.

Returns:
the description of the most recently updated step across all the nested ProgressContainers.
See Also:
getCurrentStep(), ProgressContainer.getCurrentStepDescription()

isComplete

public boolean isComplete()
Check if this MacroProgressContainer is complete. For this to be true, all the nested ProgressContainers must be complete, and this MacroProgressContainer must have been marked complete also.

Returns:
true if this MacroProgressContainer is complete, false otherwise.
See Also:
ProgressContainer.isComplete(), waitForEnd()

hasError

public boolean hasError()
Check if any of the nested ProgressContainers or this MacroProgressContainer has an error set.

Returns:
true if any of the nested ProgressContainers or this MacroProgressContainer has an error set, false otherwise.
See Also:
ProgressContainer.hasError(), getError()

getError

public java.lang.Exception getError()
Return the Exception from any of the nested ProgressContainers or from this MacroProgressContainer.

Returns:
Exception from any of the nested ProgressContainers or from this MacroProgressContainer. If no error has been encountered, this value will be null. If this MacroProgressContainer has an error, that value will be returned before checked the nested ProgressContainers. If more than one nested ProgressContainer has an error, the first one found will be returned.
See Also:
hasError(), ProgressContainer.getError()

setCorrelator

public void setCorrelator(java.lang.Object correlator)
Set the correlator for this MacroProgressContainer. This is a value which can be optionally set and retrieved by the caller to store a value that may help correlate this task to other items that the caller cares about. The manager does not look at this correlator, it is for use only by the caller. The default value of the correlator is null.

Parameters:
correlator - a user-defined value. It does not affect the correlator for any of the nested ProgressContainers.
See Also:
getCorrelator(), ProgressContainer.setCorrelator(Object)

getCorrelator

public java.lang.Object getCorrelator()
Get the correlator for this MacroProgressContainer. The correlator is a non-functional place for the caller to attach any object they want. For more details, see setCorrelator(Object).

Returns:
the correlator for this MacroProgressContainer.
See Also:
setCorrelator(Object), ProgressContainer.getCorrelator()

toString

public java.lang.String toString()
Get a String representation of this object for the purpose of debugging or tracing.

Overrides:
toString in class java.lang.Object
Returns:
a String representation of this object for the purpose of debugging or tracing.

getProgressContainers

public ProgressContainer[] getProgressContainers()
Returns the nested ProgressContainers for any returned values or errors.


setFailedTasks

public void setFailedTasks(java.util.Hashtable failedTasks)

getFailedTasks

public java.util.Hashtable getFailedTasks()

blockAndTrace

public void blockAndTrace(java.util.logging.Level level)
A convenience method for waiting for the tasks to complete and printing the progress of each step for each nested ProgressConatiner. It will wait for an update, and for each step in each of the nested ProgressConatiners print the step number and description. When the each task completes successfully it will print that. If any of the task end abnormally it will print the Exception that caused the problem. None of the nested ProgressContainers return objects using this method.

Parameters:
level - the log level at which to generate the text messages


© Copyright IBM Corp. 2006, 2010 All Rights Reserved.