ImagePlanProgressTracker

com.sun.pkg.client

## Class ImagePlanProgressTracker

- java.lang.Object
- - 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

    Constructors
    Constructor and Description
    `ImagePlanProgressTracker()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.