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

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

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