com.sun.pkg.client

# Package com.sun.pkg.client

Provides for client-side access to the Image Packaging System (IPS) for Java clients.

See: Description

- Class Summary
  Class | Description
  --- | ---
  AbstractFileAction | Common part between `DirAction` and `FileAction`, which stems from the fact that they both involve in an object in a directory that has the same set of metadata.
  Action | An `Action` is the base class for all actions that are contained within packages.
  DependAction | A `DependAction` is an action that represents a dependency from one package to another.
  DirAction | A `DirAction` is an action that represents a directory within the image.
  FileAction | A `FileAction` is an action that represents a file within the image.
  Fmri | An `Fmri` is an identifier for a package.
  Image | An `Image` is a directory tree containing the laid-down contents of a self-consistent graph of Packages.
  Image.FmriState | An `FmriState` represents the current state of an Fmri within the image.
  ImagePlanProgressTracker | Callback handler for `Image.ImagePlan.execute()` to monitor the progress of package add/remove/update operations.
  LicenseAction | A `LicenseAction` is a file action that represents a license file within the image.
  LinkAction | A `LinkAction` is an action that represents a symbolic link within the image.
  Manifest | A `Manifest` is a list of actions within a package.
  SetAction | A `SetAction` is an action that represents package attribute.
  SystemInfo | `SystemInfo` provides access to system information related to the pkg(5) Java API.
  Variant |
  Version | A `Version` represents the version part of an IPS package FMRI.
  Version.DotSequence | The `DotSequence` class represents the x.y.z parts of a Version object.

- Enum Summary
  Enum | Description
  --- | ---
  DependAction.Type | Type of dependency.
  SystemInfo.UpdateCheckFrequency |

## Package com.sun.pkg.client Description

Provides for client-side access to the Image Packaging System (IPS) for Java clients. The primary class for using this API is the `Image` class.

## Usage Examples

This section contains some examples of how to use this API to accomplish some typical tasks.

### Install the most recent version of a given package

The objective of this example is to install the most recent version of the "foo" package into the image rooted at "bar" in the user's home directory.

        File dir = new File(System.getProperty("user.home"), "bar");
        Image img = new Image(dir);
        String pkgs[] = {"foo"};
        img.installPackages(pkgs);

### Check to see if a given package is installed

The objective of this example is to determine whether the "foo" package has been installed into the image. This example uses the Image object from the previous example.

        List list = img.getInventory(pkgs, false);
        if (list.size() > 0) {
            System.out.println("package foo is installed");
        }

### Update the packages in an image

The objective of this example is to print a list of the packages that have available updates in the image and then install those updates. This example uses the Image object from the previous example.

        List list2 = img.getInventory(null, false);
        ArrayList pkgs2 = new ArrayList();
        for (Image.FmriState fs : list2) {
          if (fs.upgradable) {
            pkgs2.add(fs.fmri.getName());
          }
        }
        img.installPackages(pkgs2.toArray(new String[0]));

### Display the license for a package before installing it

This example shows how to access the license(s) for a package or set of packages that are to be installed.

        File dir = new File(System.getProperty("user.home"), "bar");
        Image img = new Image(dir);
        String pkgs[] = {"foo"};
        Image.ImagePlan ip = img.makeInstallPlan(pkgs);
        StringBuffer licenseText = new StringBuffer();
        for (Fmri f : ip.getProposedFmris()) {
            Manifest m = img.getManifest(f);
            List<LicenseAction> lla = m.getActionsByType(LicenseAction.class);
            for (LicenseAction la : lla) {
                licenseText.append("===== ").append(la.getName()).append(" =====\n");
                licenseText.append("\n");
                licenseText.append(lla.getText());
                licenseText.append("\n\n");
            }
        }
        System.out.println(licenseText);
        ip.execute();

## Logging

The pkg Java API generates log information to the com.sun.pkg.client Logger. The following code can be used to manipulate the properties of this logger before calling the various methods of the API:

         Logger cl = Logger.getLogger("com.sun.pkg.client");
         cl.setLevel(Level.FINER);

## Limitations

The pkg Java API is not (yet) a complete implementation of the client side capabilities of the Image Packaging System. Here is a partial list of the limitations of the API. The number in parenthesis is the issue that is tracking completion of that feature.

- No support for being able to cancel an install
- No support for search (pkg search)
- No support for image properties (pkg set-property)
- No support for managing authorities
- No image verify support (pkg verify)
- No support for accessing the contents of an image (pkg contents)
- The following actions are not supported: driver, user, group, legacy, hardlink
- The "preserve" tag on an action is ignored
- No support for exclude dependencies (not available in pkg(5) either)
- No support for variants or facets
- No check for action duplicates in packages that are being installed
- No removal of implicitly created directories during package removal
- No support for ZFS boot environments
- No support for package rename records in catalogs
- No support for operational history

## Related Documentation

For overviews, tutorials, examples, guides, and tool documentation, please see:

- OpenSolaris pkg website
- Update Center Toolkit website