com.sun.pkg.client
Class ImagePlanProgressTracker

java.lang.Object
  extended by com.sun.pkg.client.ImagePlanProgressTracker

public class ImagePlanProgressTracker
extends java.lang.Object

Callback handler for Image.ImagePlan.execute() to monitor the progress of package add/remove/update operations.

Implemented as an abstract class instead of interface so that future additions of new callback methods won't break existing clients.

Callback Order

The callback methods are invoked in the following sequences:

 startDownloadPhase
 for(each fmri that requires download) {
   startPackageDownload
   for(each file in this fmri that requires download) {
     startFileDownload
     while(transfer is in progress)
       onFileDownloadProgress
     endFileDownload
   }
   endPackageDownload
 }
 endDownloadPhase
 startActions
 startRemovalPhase
 for(each removal action) {
   onRemovalAction
 }
 endRemovalPhase
 startUpdatePhase
 for(each Update action) {
   onUpdateAction
 }
 endUpdatePhase
 startInstallPhase
 for(each Install action) {
   onInstallAction
 }
 endInstallPhase
 

Notes

During download, the actual data transfer is subject to the transport level compression (currently it is tar+gzip, but you shouldn't rely on it.) Therefore, depending on the kind of files you are transferring, the progress of transfer may not be uniform.

Author:
Kohsuke Kawaguchi

Constructor Summary
ImagePlanProgressTracker()
           
 
Method Summary
 void endDownloadPhase()
          Called when all that have to be downloaded are downloaded.
 void endFileDownload(int index, long fileSize)
          Called when a file download is completed.
 void endInstallPhase()
          Called when all that have to be installed are installed.
 void endPackageDownload(Fmri pkg, int totalDownloadFiles)
          Called when downloading for a whole package is completed.
 void endRemovalPhase()
          Called when all that have to be removed are removed.
 void endUpdatePhase()
          Called when all that have to be updated are updated.
 void onFileDownloadProgress(int index, long xferedBytes)
          Called periodically while a file is being downloaded.
 void onInstallAction(Action a)
          Called for each install action, right before it's executed.
 void onRemovalAction(Action a)
          Called for each removal action, right before it's executed.
 void onUpdateAction(Action from, Action to)
          Called for each update action, right before it's executed.
 void startActions(int totalActions)
          Called before the three Action-based phases are started, to notify the total number of actions combined between those three phases.
 void startDownloadPhase(int totalPackages)
          Called when the execution enters the download phase, which is the 1st of the four phases.
 void startFileDownload(int index, long fileSize)
          Called when the execution starts downloading a particular file.
 void startInstallPhase(int totalInstallActions)
          Called when the execution gets to the install phase, where a bunch of new files and directories are installed.
 void startPackageDownload(Fmri pkg, int totalDownloadFiles, long totalDownloadSize)
          Called when the execution starts downloading files for the given package.
 void startRemovalPhase(int totalRemovalActions)
          Called when the execution gets to the removal phase, where a bunch of files and directories are removed.
 void startUpdatePhase(int totalUpdateActions)
          Called when the execution gets to the update phase, where a bunch of files and directories are overwritten/modified.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ImagePlanProgressTracker

public ImagePlanProgressTracker()
Method Detail

startDownloadPhase

public void startDownloadPhase(int totalPackages)
Called when the execution enters the download phase, which is the 1st of the four phases.

To obtain the total number of files to be downloaded during this phase, use Image.ImagePlan.computeTransferFiles(). Similarly, to obtain the total number of bytes to be downloaded, use Image.ImagePlan.computeTransferSize().

Parameters:
totalPackages - Number of packages to be affected. Can be 0. startPackageDownload(Fmri,int,long) ... endPackageDownload(Fmri, int) callbacks are invoked this many number of times. This maybe smaller than the number of packages being affected, because not all packages require downloads.

startPackageDownload

public void startPackageDownload(Fmri pkg,
                                 int totalDownloadFiles,
                                 long totalDownloadSize)
Called when the execution starts downloading files for the given package.

Parameters:
pkg - Fmri that indicates the package being downloaded. Never null.
totalDownloadFiles - Number of files to be downloaded in this package. Always greater than 0. startFileDownload(int,long) ... endFileDownload(int,long)
totalDownloadSize - Combined total number of bytes of all the files to be downloaded. Can be 0.

startFileDownload

public void startFileDownload(int index,
                              long fileSize)
Called when the execution starts downloading a particular file.

Parameters:
index - The index of the current file being downloaded. This goes from 0 to the totalDownloadFiles parameter passed to startPackageDownload(Fmri,int,long).
fileSize - The number of bytes to be downloaded for this file.

onFileDownloadProgress

public void onFileDownloadProgress(int index,
                                   long xferedBytes)
Called periodically while a file is being downloaded.

This method is called repeatedly for the same file if the file is large. Also, no matter how small the file is, this method is called at least once, when the download of the file is finished.

Parameters:
index - The same as the index parameter of the onFileDownloadProgress(int, long).
xferedBytes - The number of bytes transferred thus far. This is within [0,fileSize] where the fileSize is given by the startFileDownload(int, long) callback.

endFileDownload

public void endFileDownload(int index,
                            long fileSize)
Called when a file download is completed. The parameters are the same as startFileDownload(int, long)


endPackageDownload

public void endPackageDownload(Fmri pkg,
                               int totalDownloadFiles)
Called when downloading for a whole package is completed. The parameters are the same as startPackageDownload(Fmri,int,long).


endDownloadPhase

public void endDownloadPhase()
Called when all that have to be downloaded are downloaded.


startActions

public void startActions(int totalActions)
Called before the three Action-based phases are started, to notify the total number of actions combined between those three phases.

This callback enables the implementation to use a single progress bar for the following three phases.

Parameters:
totalActions - Sum of totalXyzActions passed as parameters to startRemovalPhase(int), startUpdatePhase(int), and startInstallPhase(int). Can be 0.

startRemovalPhase

public void startRemovalPhase(int totalRemovalActions)
Called when the execution gets to the removal phase, where a bunch of files and directories are removed.

Parameters:
totalRemovalActions - Number of things to be removed. Can be 0. onRemovalAction(Action) callback is called for this many times.

onRemovalAction

public void onRemovalAction(Action a)
Called for each removal action, right before it's executed.

Parameters:
a - The removal action to be performed. Never null. Do not change the state of this object from the callback.

endRemovalPhase

public void endRemovalPhase()
Called when all that have to be removed are removed.


startUpdatePhase

public void startUpdatePhase(int totalUpdateActions)
Called when the execution gets to the update phase, where a bunch of files and directories are overwritten/modified.

Parameters:
totalUpdateActions - Number of things to be updated. Can be 0. onUpdateAction(Action, Action) callback is called for this many times.

onUpdateAction

public void onUpdateAction(Action from,
                           Action to)
Called for each update action, right before it's executed.

Parameters:
from - Unused. Passed for future extension. Never null.
to - Represents the target of the state transition. Never null.

endUpdatePhase

public void endUpdatePhase()
Called when all that have to be updated are updated.


startInstallPhase

public void startInstallPhase(int totalInstallActions)
Called when the execution gets to the install phase, where a bunch of new files and directories are installed.

Parameters:
totalInstallActions - Number of things to be newly installed. Can be 0. onInstallAction(Action) callback is called for this many times.

onInstallAction

public void onInstallAction(Action a)
Called for each install action, right before it's executed.

Parameters:
a - The install action to be performed. Never null. Do not change the state of this object from the callback.

endInstallPhase

public void endInstallPhase()
Called when all that have to be installed are installed.