com.sun.pkg.client
Class Image

java.lang.Object
  extended by 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
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
static int IMG_ENTIRE
           
static int IMG_PARTIAL
           
static int IMG_USER
           
 
Constructor Summary
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
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.lang.String getPreferredAuthorityName()
           
 java.io.File getRootDirectory()
          Obtain the root directory for this image.
 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(java.util.List<Fmri> pkgs)
          Install packages and any required dependencies.
 void installPackages(java.lang.String... pkgNames)
          Install packages and any required dependencies.
 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.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 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 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 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. For adding an authority, the origin URL is required. For an existing authority, the origin or uuid parameters may be null and in that case the value for the attribute is not changed.

NOTE: setting the uuid is effective only if a uuid attribute is already there

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

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: *

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.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.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 - Fmris to be removed.
Returns:
An ImagePlan that will uninstall the packages when executed.
Throws:
java.io.IOException

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(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

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