com.sun.pkg.client

## Class Image

- java.lang.Object
- - com.sun.pkg.client.Image

-     public class Image
      extends java.lang.Object

  An `Image` is a directory tree containing the laid-down contents of a self-consistent graph of Packages.

  An Image has a root path.

  Author:
    trm

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Image.FmriState` An `FmriState` represents the current state of an Fmri within the image.
    `class` | `Image.ImagePlan` An `ImagePlan` takes a list of requested packages, an Image (and its policy restrictions), and returns the set of package operations needed to transform the Image to the list of requested packages.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `IMG_ENTIRE`
    `static int` | `IMG_PARTIAL`
    `static int` | `IMG_USER`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Image(java.io.File path)` Open an Image object for an existing user image based on a File.
    `Image(java.lang.String path)` Create an Image object for an existing user image based on a String

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `completeInstall()`
    `static Image` | `create(java.io.File path, java.lang.String authName, java.net.URL origin)` Creates a new user image at the specified path.
    `java.lang.String[]` | `getAuthorityNames()` Return the authority names defined for this image.
    `java.util.List<Image.FmriState>` | `getInventory(java.lang.String[] pkg_list, boolean all_known)` Get the inventory of packages and their associated state.
    `Manifest` | `getManifest(Fmri fmri)` Get the manifest for a package.
    `java.util.HashMap<java.lang.String,java.lang.String>` | `getMetaData()`
    `java.lang.String` | `getPreferredAuthorityName()`
    `java.io.File` | `getRootDirectory()` Obtain the root directory for this image.
    `int` | `getURLConnectTimeout()`
    `int` | `getURLReadmTimeout()`
    `Fmri` | `getVersionInstalled(java.lang.String pkgName)` Given just the package name (e.g., "SUNWbash"), find the version currently installed in this image, and returns its `Fmri` with the version number.
    `java.util.List<Fmri>` | `getVersionsInstalled(java.util.Collection<java.lang.String> pkgNames)` Plural version of `getVersionInstalled(String)`.
    `void` | `hideMetaDirectory()` Change the permissions on the Image meta data directory so that the directory will be hidden.
    `void` | `installPackages(boolean download, boolean apply, java.util.List<Fmri> pkgs)` Install packages and any required dependencies.
    `void` | `installPackages(boolean download, boolean apply, java.lang.String... pkgNames)`
    `void` | `installPackages(ImagePlanProgressTracker tracker, boolean download, boolean apply, java.lang.String... pkgNames)` Install packages and any required dependencies.
    `void` | `installPackages(java.util.List<Fmri> pkgs)` Install packages and any required dependencies.
    `void` | `installPackages(java.lang.String... pkgNames)` Install packages and any required dependencies.
    `boolean` | `isTherePendingInstall()`
    `Image.ImagePlan` | `makeInstallPlan(java.util.Collection<java.lang.String> pkgNames)` Create an plan for installing packages and any required dependencies.
    `Image.ImagePlan` | `makeInstallPlan(java.util.Collection<java.lang.String> pkgNames, java.lang.String operation)` Create an plan for installing packages and any required dependencies.
    `Image.ImagePlan` | `makeInstallPlan(java.util.List<Fmri> pkgs)` Create an plan for installing packages and any required dependencies.
    `Image.ImagePlan` | `makeInstallPlan(java.lang.String... pkgNames)` Create an plan for installing packages and any required dependencies.
    `Image.ImagePlan` | `makeInstallPlan(java.lang.String[] pkgNames, java.lang.String operation)`
    `Image.ImagePlan` | `makeUninstallPlan(java.util.Collection<Fmri> pkgs)` Create a plan for removing packages.
    `void` | `refreshCatalog(java.lang.String authname)` Call refresh on the Catalog for the given authority.
    `void` | `refreshCatalogs()` Call refresh on all of the Catalogs for this image.
    `void` | `saveConfig()` Save the configuration for the image.
    `void` | `setAuthority(java.lang.String authname, java.net.URL origin, java.lang.String uuid)` Set image authority attributes.
    `void` | `setClientName(java.lang.String clientname)` Set the client name to be used in connections to repositories.
    `static void` | `setDefaultClientName(java.lang.String clientname)` Set the default client name for all Image objects created in this VM.
    `void` | `setMetaData(java.util.HashMap<java.lang.String,java.lang.String> attrs)` If provided this metadata is included in any catalog requests via the X-JPkg-MetaData property on the HTTP GET request.
    `void` | `setProperty(java.lang.String pname, java.lang.String pvalue)` Set image property value.
    `void` | `setProxy(java.net.Proxy p)` Set the proxy to be used by connenctions to repositories.
    `void` | `setURLConnectTimeout(int timeout_ms)`
    `void` | `setURLReadmTimeout(int timeout_ms)`
    `void` | `setVariant(java.lang.String name, java.lang.String value)` Set image variant value.
    `void` | `uninstallPackages(java.util.List<Fmri> pkgs)` Uninstall packages.
    `void` | `uninstallPackages(java.lang.String... pkgNames)` Uninstall packages.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### IMG_ENTIRE

          public static final int IMG_ENTIRE

      See Also:
        Constant Field Values

    - #### IMG_PARTIAL

          public static final int IMG_PARTIAL

      See Also:
        Constant Field Values

    - #### IMG_USER

          public static final int IMG_USER

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Image

          public Image(java.lang.String path)
                throws java.lang.Exception

      Create an Image object for an existing user image based on a String
      Parameters:
        `path` - The path for a file or directory within the image.
      Throws:
        `java.lang.Exception`

    - #### Image

          public Image(java.io.File path)
                throws java.lang.Exception

      Open an Image object for an existing user image based on a File.
      Parameters:
        `path` - A File within the image.
      Throws:
        `java.lang.Exception`
      See Also:
        `create(File, String, URL)`

  - ### Method Detail

    - #### create

          public static Image create(java.io.File path,
                     java.lang.String authName,
                     java.net.URL origin)
                              throws java.lang.Exception

      Creates a new user image at the specified path. The equivalent of "pkg image-create". This method creates a set of metadata necessary for a directory to function as an IPS image.
      Parameters:
        `path` - Directory that will become an image. If no such directory exists, it'll be created.
        `authName` - The name of the initial authority to be added.
        `origin` - The URL of the initial authority.
      Throws:
        `java.lang.Exception`

    - #### getRootDirectory

          public java.io.File getRootDirectory()

      Obtain the root directory for this image.
      Returns:
        the root directory for this image

    - #### hideMetaDirectory

          public void hideMetaDirectory()
                                 throws java.io.IOException

      Change the permissions on the Image meta data directory so that the directory will be hidden.
      Throws:
        `java.io.IOException`

    - #### setProxy

          public void setProxy(java.net.Proxy p)

      Set the proxy to be used by connenctions to repositories.

      The proxy for an Image is initialized to be the return value from SystemInfo.getProxy. This method can be used to set the proxy to some other value or to null if the desire is to use the system defaults.

      Parameters:
        `p` - - the proxy to use

    - #### setClientName

          public void setClientName(java.lang.String clientname)

      Set the client name to be used in connections to repositories.

      The client name is included in the User-Agent header following the image type. The default value is "pkg-java" if setClientName is not called or another value as set by the setDefaultClientName method.

      Parameters:
        `clientname` - the name of the client that is using this image object

    - #### setDefaultClientName

          public static void setDefaultClientName(java.lang.String clientname)

      Set the default client name for all Image objects created in this VM.

      See the setClientName method for information on how the client name value is used.

      Parameters:
        `clientname` - the default value to use for client name

    - #### saveConfig

          public void saveConfig()
                          throws java.io.IOException

      Save the configuration for the image. Adjust the origin in the cfgfile so that it matches that of the current platform as determined by origin_for_* properties. This method writes a new version of the cfgfile.
      Throws:
        `java.io.IOException`

    - #### getPreferredAuthorityName

          public java.lang.String getPreferredAuthorityName()

    - #### getAuthorityNames

          public java.lang.String[] getAuthorityNames()

      Return the authority names defined for this image.
      Returns:
        an array of authority names

    - #### setAuthority

          public void setAuthority(java.lang.String authname,
                          java.net.URL origin,
                          java.lang.String uuid)
                            throws java.io.IOException

      Set image authority attributes. If authname names an authority that currently doesn't exist, it is added to the image. Otherwise, the parameters are used to modify an existing authority.

      When adding an authority, the origin URL is required while uuid may be null. If the uuid is passed as null, a new uuid will be generated and assigned to the authority.

      When modifying an existing authority, the origin and uuid parameters may be passed as nulls. In this case:

      - The existing origin will not be modified.
      - If a uuid is already present, the existing uuid will not be modified.
      - If a uuid is not present, a new uuid will be generated and assigned to the authority.

      Parameters:
        `authname` - - the name of the authority to change
        `origin` - - the origin URL for the authority
        `uuid` - - the UUID for the authority
      Throws:
        `java.lang.IllegalArgumentException` - - if the authority is not currently in the image and origin is null.
        `java.io.IOException`

    - #### setProperty

          public void setProperty(java.lang.String pname,
                         java.lang.String pvalue)

      Set image property value. The saveConfig method must be called to make the property persist.
      Parameters:
        `pname` - - the name of the property to set
        `pvalue` - - the value of the property

    - #### setVariant

          public void setVariant(java.lang.String name,
                        java.lang.String value)

      Set image variant value.
      Parameters:
        `name` - - the name of the variant to set
        `value` - - the value of the variant

    - #### refreshCatalogs

          public void refreshCatalogs()
                               throws java.io.IOException

      Call refresh on all of the Catalogs for this image. This also updates the internal cache used by the Image class to store catalog information.
      Throws:
        `java.io.IOException`

    - #### refreshCatalog

          public void refreshCatalog(java.lang.String authname)
                              throws java.io.IOException

      Call refresh on the Catalog for the given authority. This also updates the internal cache used by the Image class to store catalog information.
      Throws:
        `java.io.IOException`

    - #### getInventory

          public java.util.List<Image.FmriState> getInventory(java.lang.String[] pkg_list,
                                                     boolean all_known)

      Get the inventory of packages and their associated state. The inventory is returned in FmriState objects that consist of an Fmri and the four states for the Fmri. These states are:
      - upgradable A package with a newer version if available in the catalog
      - frozen TBD
      - incorporated The package is part of an incorporation
      - excludes TBD
      *
      Parameters:
        `pkg_list` - Limit the inventory to packages that match entries in the list of package names
        `all_known` - If true, return all package versions. Otherwise only return the most recent version of each package.
      Returns:
        A List of FmriState objects that identify the Fmris that are available for the image.

    - #### makeInstallPlan

          public Image.ImagePlan makeInstallPlan(java.util.Collection<java.lang.String> pkgNames)
                                          throws java.io.IOException,
                                                 com.sun.pkg.client.Constraint.ConstraintException

      Create an plan for installing packages and any required dependencies.
      Parameters:
        `pkgNames` - names of packages to install
      Returns:
        An ImagePlan that will install the packages when executed.
      Throws:
        `java.io.IOException`
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### makeInstallPlan

          public Image.ImagePlan makeInstallPlan(java.util.Collection<java.lang.String> pkgNames,
                                        java.lang.String operation)
                                          throws java.io.IOException,
                                                 com.sun.pkg.client.Constraint.ConstraintException

      Create an plan for installing packages and any required dependencies.
      Parameters:
        `pkgNames` - names of packages to install
        `operation` - identify the operation (install, list, uninstall)
      Returns:
        An ImagePlan that will install the packages when executed.
      Throws:
        `java.io.IOException`
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### makeInstallPlan

          public Image.ImagePlan makeInstallPlan(java.lang.String... pkgNames)
                                          throws java.io.IOException,
                                                 com.sun.pkg.client.Constraint.ConstraintException

      Create an plan for installing packages and any required dependencies.
      Parameters:
        `pkgNames` - names of packages to install
      Returns:
        An ImagePlan that will install the packages when executed.
      Throws:
        `java.io.IOException`
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### makeInstallPlan

          public Image.ImagePlan makeInstallPlan(java.lang.String[] pkgNames,
                                        java.lang.String operation)
                                          throws java.io.IOException,
                                                 com.sun.pkg.client.Constraint.ConstraintException

      Throws:
        `java.io.IOException`
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### makeInstallPlan

          public Image.ImagePlan makeInstallPlan(java.util.List<Fmri> pkgs)
                                          throws java.io.IOException,
                                                 com.sun.pkg.client.Constraint.ConstraintException

      Create an plan for installing packages and any required dependencies.
      Parameters:
        `pkgs` - List of valid Fmris from the image inventory for packages to install.
      Returns:
        An ImagePlan that will install the packages when executed.
      Throws:
        `java.io.IOException`
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### makeUninstallPlan

          public Image.ImagePlan makeUninstallPlan(java.util.Collection<Fmri> pkgs)
                                            throws java.io.IOException

      Create a plan for removing packages.
      Parameters:
        `pkgs` - `Fmri`s to be removed.
      Returns:
        An ImagePlan that will uninstall the packages when executed.
      Throws:
        `java.io.IOException`

    - #### isTherePendingInstall

          public boolean isTherePendingInstall()
                                        throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### completeInstall

          public void completeInstall()
                               throws java.io.IOException,
                                      com.sun.pkg.client.Constraint.ConstraintException

      Throws:
        `java.io.IOException`
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### installPackages

          public void installPackages(java.lang.String... pkgNames)
                               throws java.io.IOException,
                                      com.sun.pkg.client.Constraint.ConstraintException

      Install packages and any required dependencies.

      The catalogs are searched for a matching package for each entry in the pkgNames array. If multiple packages match an entry, the most recent package is installed. If no matching package is found, an IllegalArgumentException is thrown.

      This method is shorthand for:

                makeInstallPlan(pkgNames).execute();

      Parameters:
        `pkgNames` - names of packages to install
      Throws:
        `java.io.IOException`
        `java.lang.IllegalArgumentException` - if a matching package cannot be found
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### installPackages

          public void installPackages(ImagePlanProgressTracker tracker,
                             boolean download,
                             boolean apply,
                             java.lang.String... pkgNames)
                               throws java.io.IOException,
                                      com.sun.pkg.client.Constraint.ConstraintException

      Install packages and any required dependencies.

      The catalogs are searched for a matching package for each entry in the pkgNames array. If multiple packages match an entry, the most recent package is installed. If no matching package is found, an IllegalArgumentException is thrown.

      This method is shorthand for:

                makeInstallPlan(pkgNames).execute();

      Parameters:
        `pkgNames` - names of packages to install
        `download` - boolean variable to trigger download
        `apply` - boolean variable to trigger installtion for downloaded packages
        `tracker` - Progress tracker. May be null.
      Throws:
        `java.io.IOException`
        `java.lang.IllegalArgumentException` - if a matching package cannot be found
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### installPackages

          public void installPackages(boolean download,
                             boolean apply,
                             java.lang.String... pkgNames)
                               throws java.io.IOException,
                                      com.sun.pkg.client.Constraint.ConstraintException

      Throws:
        `java.io.IOException`
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### installPackages

          public void installPackages(java.util.List<Fmri> pkgs)
                               throws java.io.IOException,
                                      com.sun.pkg.client.Constraint.ConstraintException

      Install packages and any required dependencies.

      This method is shorthand for:

                makeInstallPlan(pkgs).execute();

      Parameters:
        `pkgs` - List of valid Fmris from the image inventory for packages to install.
      Throws:
        `java.io.IOException`
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### installPackages

          public void installPackages(boolean download,
                             boolean apply,
                             java.util.List<Fmri> pkgs)
                               throws java.io.IOException,
                                      com.sun.pkg.client.Constraint.ConstraintException

      Install packages and any required dependencies.

      This method is shorthand for:

                makeInstallPlan(pkgs).execute();

      Parameters:
        `pkgs` - List of valid Fmris from the image inventory for packages to install.
        `download` - boolean variable to trigger download
        `apply` - boolean variable to trigger installtion for downloaded packages
      Throws:
        `java.io.IOException`
        `com.sun.pkg.client.Constraint.ConstraintException`

    - #### uninstallPackages

          public void uninstallPackages(java.lang.String... pkgNames)
                                 throws java.io.IOException

      Uninstall packages. The installed package list is searched for a matching package for each entry in the pkgNames array. If no matching package is found, the entry is ignored.
      Parameters:
        `pkgNames` - names of packages to uninstall
      Throws:
        `java.io.IOException`

    - #### uninstallPackages

          public void uninstallPackages(java.util.List<Fmri> pkgs)
                                 throws java.io.IOException

      Uninstall packages.
      Parameters:
        `pkgs` - List of valid Fmris to uninstall.
      Throws:
        `java.io.IOException`

    - #### getManifest

          public Manifest getManifest(Fmri fmri)
                               throws java.io.IOException

      Get the manifest for a package.
      Returns:
        a Manifest
      Throws:
        `java.io.IOException`

    - #### getVersionInstalled

          public Fmri getVersionInstalled(java.lang.String pkgName)
                                   throws java.io.IOException

      Given just the package name (e.g., "SUNWbash"), find the version currently installed in this image, and returns its `Fmri` with the version number.
      Returns:
        null if the package isn't installed.
      Throws:
        `java.io.IOException`

    - #### getVersionsInstalled

          public java.util.List<Fmri> getVersionsInstalled(java.util.Collection<java.lang.String> pkgNames)
                                                    throws java.io.IOException

      Plural version of `getVersionInstalled(String)`.

      If a package specified isn't installed, it'll be just ignored.

      Returns:
        can be empty but never null. Never contains null.
      Throws:
        `java.io.IOException`

    - #### setURLConnectTimeout

          public void setURLConnectTimeout(int timeout_ms)

    - #### getURLConnectTimeout

          public int getURLConnectTimeout()

    - #### setURLReadmTimeout

          public void setURLReadmTimeout(int timeout_ms)

    - #### getURLReadmTimeout

          public int getURLReadmTimeout()

    - #### setMetaData

          public void setMetaData(java.util.HashMap<java.lang.String,java.lang.String> attrs)

      If provided this metadata is included in any catalog requests via the X-JPkg-MetaData property on the HTTP GET request.

    - #### getMetaData

          public java.util.HashMap<java.lang.String,java.lang.String> getMetaData()