All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.sun.install.products.PkgUnit

java.lang.Object
   |
   +----com.sun.install.products.InstallComponent
           |
           +----com.sun.install.products.InstallLeaf
                   |
                   +----com.sun.install.products.PkgUnit

public class PkgUnit
extends InstallLeaf
implements ResourceResolver

PkgUnit is the logical representation of a Solaris SVR4 "Package". It can be used to install a package onto a system. The underlying methods are based on the Solaris pkgadd command. See the pkgadd(1M) man page for more information on the usage. See the Solaris Tutorial for a complete example of using PkgUnit to install an example product using packages.

An object of this type is designed to fit into the product tree. The product tree is a tree-based representation of a product. The tree is traversed during the install and each leaf installs the piece of the product that is has been tasked to. When a PkgUnit is encountered in the tree, it will run pkgadd with the options that are provided in the constructor.

The PkgUnit class should be configured at build-time. There are several build-time constructors. All of them take some combination of parameters, all of which are described below:

The relative path. At runtime, The wizard looks for your packages at the locations you specified at buildtime, if you do not embed the package into the archive. For example, you you might specify "../pkgs" as a relative path. Then, at runtime, for the package named "SUNWstuf", the package will be located (via pkgadd -d) using "../pkgs/SUNWstuf". You supply this information in your builder.
Note: Embedded Packages. You can embed the package itself into the wizard by calling setEmbedType() with a type other than NO_EMBED. This way, when the wizard archive is built, the package is stored (in package stream form) inside the wizard, along with any admin or response files you provide. See the setEmbedType() method documentation for more information.
The package name. The package name is name of the SVR4 package that this PkgUnit represents. It is used to programatically access the package, and as such should be the same as the top-level directory for the package contents.
The "admin" directory. admin is a generic name for an ASCII file that defines default installation actions (pkgadd -a) by assigning values to installation parameters. For example, it allows you to define how to proceed when your package being installed already exists on the system. You can create your own admin file to use, use a generic default one, or none at all. The directory specified here is searched for an admin file with the same name as the package.
Several sources are queried in order to construct the final admin contents used during the pkgadd invocation. The process is as follows:
- 1. The default /var/sadm/install/admin/webstart file is read and its contents remebered
  -OR-
  if the user specified an alternate admin file via the -a {adminfile} option when invoking the wizard, then this file is read.
- 2. If you supplied an admin file using PkgUnit's constructor, then this file is then read, and any settings in this file NOT in the previously read file from step 1 are inserted.
- 3. Any settings that have not been set from operations 1 and 2 are set now, using their default values:
```
 mail=
 instance=overwrite
 partial=nocheck
 unlevel=nocheck
 idepend=nocheck
 rdepend=nocheck
 space=nocheck
 setuid=nocheck
 conflict=nocheck
 action=nocheck
 basedir=default
 
```
  Note that if the result of steps 1 and 2 result in all of the above settings having a legal value, then none of these defaults are used.
- 4. The result of operations 1, 2, and 3 are stored into the WizardState under the key admin.pkgName. For example, for the package SUNWstuf, the admin file is stored under admin.SUNWstuf. You can retrieve the hashtable representing the admin file from a task with the following code:
```
 Hashtable adminFile = (Hashtable)getTreeManager().callServerObjectMethod(
              getRoute(), "getData", 
		  new String[] {"java.lang.String.class"}, 
		  new Object[] {"admin.{pkgName}"});
 
```
  Your panel could then modify its contents based on user input, and reset it back into the WizardState for use during pkgadd:
```
 getTreeManager().callServerObjectMethod(
        getRoute(), "setData",
        new String[] {"java.lang.String.class", "java.lang.Object.class"},
	   new Object[] {"admin.{pkgName}", adminFile});
 
```
  The resulting contents are written out to disk and used during pkgadd.
This approach gives precedence to the user (who must be root), the system administrator, and the creator of the product (you!), in that order.
The "response" file. The response file is generally supplied before installation takes place. The use of this response file prevents any interaction from occurring during installation since the file already contains all of the information the package needs. Unlike the admin file, if you do not specify a response file, then none will be used. Use this carefully, because if your packages require user input, you will need to use a response file so you can write this user input into it for your package installation to proceed without pausing.
Normally you would supply default values in a response file, and then customize these settings during the running of the wizard. The customized response file will then be used during package installation (pkgadd -r). See the pkgask(1M) man page for details on creating the response file. As with the admin file, the response file is available for customization during runtime. The response file is retrievable and editable under the Wizard State data key "response.{pkgname}". For example, for the package named "SUNWstuf", the response file could be edited in a panel with the following example code:
```
     //get the response file from the server
       Hashtable response =
        (Hashtable)getTreeManager().callServerObjectMethod(getRoute(),
               "getData",
               new String[] {"java.lang.String.class"},
               new Object[] {"response.SUNWstuf"});
 

     // user input comes from the text field on this panel.
     // change response file based on it.
       response.put("DOCS_DIR", userInputTextField.getText());


     // set the response file back into the server.
       getTreeManager().callServerObjectMethod(
                getRoute(),
                "setData",
                new String[] {"java.lang.String.class",
                              "java.lang.Object.class"},
                new Object[] {"response.SUNWstuf",
                              response});
 
```
Variable names and keys. Some SVR4 packages can contain parametric variables in their configuration files. These variables must be resolved during installation. For example, a package's pkgmap file might have the following line:
```
 1 f none $USERDIR/Demo1.java 0600 jhf staff 512000 0 909092253
 
```
The USERDIR variable must exist in the installation environment in order for this variable to be resolved. If you specify a table of these name/key pairs, the keys are used to look up values in the wizard state. If a value is found under a particular key, that value is set into the installation environment as NAME=value (by placing this setting in the response file). For example, suppose the above line is in my package's pkgmap file. One of my panels queries the user for this directory and sets the user's answer into the wizard state under they wizard state key "USER_SAYS_HERE". Then I would want to create my PkgUnit with a hastable as follows:
```
 Hashtable h = new Hashtable();
 h.put("USERDIR", "USER_SAYS_HERE");
 PkgUnit p = new PkgUnit(..., h, ....);
 
```
This instructs this PkgUnit to put the variable USERDIR into the installation environment, and set it to the value that is stored in the wizard state under the key "USER_SAYS_HERE".
A special case that occurs is the basedir installation variable. A common setting in the admin file is the basedir setting. This setting automatically gets prepended to the resulting installation locations for all relocatable files in the package during installation (see the pkgadd(1m) manpage). If part or all of your package is relocatable, and you want the user to be able to select a different location to install to, you would use the following variable hashtable entry to do so:
```
 h.put("basedir", "USER_SAYS_HERE");
 
```
while making sure a panel sets the user's desired directory under the wizard state key "USER_SAYS_HERE". The setting would then be placed into the admin file (not the response file, as all other variables are) as
```
 basedir={setting}
 
```
Note that this does not affect non-relocatable files (ones with absolute pathnames in the package's pkgmap).
Automatic and Manual Size Checking. PkgUnit can preprocess your package if it is available at buildtime. This increases performance at runtime by not having to re-read files off of the filesystem and/or calculate sizes. In order to do this, the package must be located at the same relative location you specified using the relativeDir argument. There are two settings for the sizeCheck argument:
- PkgUnit.BUILD_TIME - The necessary files are read and saved in the wizard. They are never read again. Sizes are calculated for the package as well.
- PkgUnit.RUN_TIME - No preprocessing takes place. The package does not have to be available at buildtime.
Instead of specifying one of the above settings, a destination table of sizes can be supplied to manually enumerate the size of the package. This is useful if the locations are fixed and known and will never change. This is not usually used for fully relocatable packages.
For example, suppose my package contained two files named myfile1 and myfile2, each 20k in size, that always installed into /etc and /usr/lib, respectively. I could create a hashtable and use this for my PkgUnit constructor:
```
 Hashtable h = new Hashtable();
 h.put("/etc", new Long(20));
 h.put("/usr/lib", new Long(20));
 PkgUnit p = new PkgUnit(..., h, ...);
 
```
The package's pkgmap file is never consulted for size information.
Note that you can specify either manual or automatic size calculations, but not both.

SVR4 Packages can also be installed using an alternate root (see the pkgadd(1M) manpage for more information). This is useful when installing an application onto a client machine that gets its root filesystem from a remote machine. Users installing your product can specify this directory when running the wizard. For example, suppose John Q. User wants to install your app onto a client filesystem that existed at /export/root/pronto. They would execute the wizard as follows:

 # java installWizard -R /export/root/pronto

This would install the files onto the client filesystem located at /export/root/proto. pkgadd would also update the package database on the client filesystem and any other files it needed to.

BUILD_TIME: Indicates to PkgUnit that it should calculate its size requirements at build time (i.e.
DEFAULT_ADMIN: Specifies default rules
GZIP_PKGSTREAM_EMBED: Constant indicating package has already by streamed via pkgtrans, and further, it is has been compressed with the gzip compression algorithm.
NO_EMBED: Constant indicating package should not be embedded into wizard.
PKG_EMBED: Constant indicating package is in filesystem form, and should be embedded into the wizard as a standard package stream.
PKGSTREAM_BUFFER_SIZE: Buffer size used during pkgtrans execution and reading.
PKGSTREAM_EMBED: Constant indicating package is already in the standard pkgtrans stream format, and should be embedded into the wizard as such.
PKGTRANS: Constant indicating location of pkgtrans utility.
RUN_TIME: Indicates to PkgUnit that it should calculate its size requirements at run time (i.e.
SUID_MODE: Mode mask for an suid file

PkgUnit(): Create a pkgadd Unit with no parameters.
PkgUnit(String, String): Create a Solaris Package Unit with the given name and path.
PkgUnit(String, String, String, String): Create a Solaris Package Unit with the given name, path, response file directory, and admin file directory.
PkgUnit(String, String, String, String, Hashtable): Create a Solaris Package Unit with the given name, path, response file directory, admin file directory, and manual size information.
PkgUnit(String, String, String, String, Hashtable, Hashtable): Create a Solaris Package Unit with the given name, path, response file directory, admin file directory, table of variable/setting pairs, and manual size information.
PkgUnit(String, String, String, String, Hashtable, int): Create a Solaris Package Unit with the given name, path, response file directory, admin file directory, variable/setting values, and preprocessing directive.

addRuntimeResources(Vector): Add the runtime resources required by this class.
closeArchiveStream(): Closes stream that accesses the embedded package.
getArchiveStream(): Gets a stream pointing to the streamed package which is inside the wizard archive.
getCollection(): Generates a collection for this wizard.
getDestinationTable(Hashtable, String, String): Creates the destination table out of a pre-processed pathname listing, an alternate root, and a directory.
getInstallLocation(): Form the install location based on the installDirKey and a possible relative path.
getStream(): Gets a stream that the package stream data can be read from (at buildtime).
getStreamSize(): Gets the size of the stream that the streamed package can be read from.
initialize(WizardState): Initialize this PkgUnit.
install(WizardState): Install (pkgadd) the package.
isInstallable(WizardState): Determine if this package is installable.
isUninstallable(WizardState): Determine if this package is unInstallable.
main(String[]): Shows size information for a package.
readPkgMap(String, Hashtable): Reads the pkgmap of an SVR4 package, and returns the resulting table of relative directory names and the total size of all files in those directories that are contained in the pkgmap.
refresh(Vector, String): Update this Package.
resolveResource(String, String, byte[]): Resolves resources for this wizard (namely the admin/response files, and the package data itself, in the case of an embedded package).
setEmbedName(String): Sets the name of the compressed file to store.
setEmbedType(int): Informs the wizard to archive the package within the wizard, instead of relying on the package to exist at runtime outside the wizard archive.
setRunPkgAsk(boolean): Sets a flag that indicates whether or not pkgask should be executed.
toString(): Represent this object as a string.
uninstall(WizardState): Uninstall (pkgrm) the package.

PKGTRANS

 public static final String PKGTRANS

Constant indicating location of pkgtrans utility.

NO_EMBED

 public static final int NO_EMBED

Constant indicating package should not be embedded into wizard. Used with setEmbedType().

PKG_EMBED

 public static final int PKG_EMBED

Constant indicating package is in filesystem form, and should be embedded into the wizard as a standard package stream. This assumes the existance of /usr/bin/pkgtrans. (pkgtrans is used to convert the package to a package stream). Used with setEmbedType().

PKGSTREAM_EMBED

 public static final int PKGSTREAM_EMBED

Constant indicating package is already in the standard pkgtrans stream format, and should be embedded into the wizard as such. Used with setEmbedType().

GZIP_PKGSTREAM_EMBED

 public static final int GZIP_PKGSTREAM_EMBED

Constant indicating package has already by streamed via pkgtrans, and further, it is has been compressed with the gzip compression algorithm. It will be stored in the wizard in gzip compressed form. Upon invocation of pkgadd, a GZIPInputStream will be used to decompress the package stream during pkgadd invocation.

Note: This is merely for convenience, if your packages are not compressed, you do not have to do anything, they will automatically be compressed if PKG_EMBED is issued to setEmbedType(). Used with setEmbedType().

PKGSTREAM_BUFFER_SIZE

 public static final int PKGSTREAM_BUFFER_SIZE

Buffer size used during pkgtrans execution and reading.

BUILD_TIME

 public static final int BUILD_TIME

Indicates to PkgUnit that it should calculate its size requirements at build time (i.e. when the wizard archive is created).

RUN_TIME

 public static final int RUN_TIME

Indicates to PkgUnit that it should calculate its size requirements at run time (i.e. when the wizard archive is executed). The time it takes for the wizard to run is increased.

DEFAULT_ADMIN

 public static final String DEFAULT_ADMIN

Specifies default rules

SUID_MODE

 public static final int SUID_MODE

Mode mask for an suid file

PkgUnit

 public PkgUnit()

Create a pkgadd Unit with no parameters. Not very useful. Must exist for serialization of an object of this type.

PkgUnit

 public PkgUnit(String relativePath,
                String pkgName)

Create a Solaris Package Unit with the given name and path. No response file is used, the default admin files are used, and the sizes are calculated at runtime. See the top of this document for more information.

Parameters:: relativePath - The path to find the package at build/runtime; pkgName - The name of the package.

PkgUnit

 public PkgUnit(String relativePath,
                String pkgName,
                String adminDir,
                String responseDir)

Create a Solaris Package Unit with the given name, path, response file directory, and admin file directory. The package sizes are calculated at runtime. See the top of this document for more information.

Parameters:: relativePath - The path to find the package at build/runtime; pkgName - The name of the package.; adminDir - The relative directory where the admin file for this package lives.; responseDir - The relative directory where the response file for this package lives.

PkgUnit

 public PkgUnit(String relativePath,
                String pkgName,
                String adminDir,
                String responseDir,
                Hashtable variables,
                int sizeCheck)

Create a Solaris Package Unit with the given name, path, response file directory, admin file directory, variable/setting values, and preprocessing directive. See the top of this document for more information.

Parameters:: relativePath - The path to find the package at build/runtime; pkgName - The name of the package.; adminDir - The relative directory where the admin file for this package lives.; responseDir - The relative directory where the response file for this package lives.; variables - A table of variable name/key settings. Each key is looked up in the WizardState, and if a value is found, that value is set into the installation environment using the corresponding variable name. from the table.; sizeCheck - When to gather size information for this package.

PkgUnit

 public PkgUnit(String relativePath,
                String pkgName,
                String adminDir,
                String responseDir,
                Hashtable destinationTable)

Create a Solaris Package Unit with the given name, path, response file directory, admin file directory, and manual size information. See the top of this document for more information.

Parameters:: relativePath - The path to find the package at build/runtime; pkgName - The name of the package.; adminDir - The relative directory where the admin file for this package lives.; responseDir - The relative directory where the response file for this package lives.; destinationTable - a table of hard-coded destinations for this package.

PkgUnit

 public PkgUnit(String relativePath,
                String pkgName,
                String adminDir,
                String responseDir,
                Hashtable variables,
                Hashtable destinationTable)

Create a Solaris Package Unit with the given name, path, response file directory, admin file directory, table of variable/setting pairs, and manual size information. the top of this document for more information.

Parameters:: relativePath - The path to find the package at build/runtime; pkgName - The name of the package.; adminDir - The relative directory where the admin file for this package lives.; responseDir - The relative directory where the response file for this package lives.; variables - A table of variable name/key settings. Each key is looked up in the WizardState, and if a value is found, that value is set into the installation environment using the corresponding variable name. from the table.; destinationTable - a table of hard-coded destinations for this package.

setRunPkgAsk

 public void setRunPkgAsk(boolean runPkgAsk)

Sets a flag that indicates whether or not pkgask should be executed. If you set this to true, your package should contain a request script that will be executed to generate the response file when the package is installed. The request script must be non-interactive (e.g. should not stop and ask users questions).

Parameters:: runPkgAsk - If true, pkgask will be executed.

setEmbedType

 public void setEmbedType(int type)

Informs the wizard to archive the package within the wizard, instead of relying on the package to exist at runtime outside the wizard archive.

Parameters:

type - The type of embedding to use. Currently, the following types are supported:

NO_EMBED: This is the default, which is to not embed the wizard within the archive.
PKG_EMBED: This means that your package is currently in filesystem format (e.g. in a directory structure). Your package will be converted into a package stream via /usr/bin/pkgtrans, stored into the wizard archive, and decompressed at runtime.
PKGSTREAM_EMBED: Similiar to PKG_EMBED, except your package must already be in stream format (i.e. a single file).
GZIP_PKGSTREAM_EMBED: Similar to PKG_EMBED, except your package must already be in stream format (i.e. a single file). Furthermore, your package stream file must have been gzipped. The file will be stored in the wizard archive, and decompressed via the java.util.zip.GZIPInputStream utility class.

setEmbedName

 public void setEmbedName(String name)

Sets the name of the compressed file to store. Defaults to "[pkgname].pkgstream" or "[pkgname].pkgstream.gz" for gzipped package streams. This gets called automatically when setEmbedType() is called, to set the default name for each type.

Parameters:: name - The filename of the (possibly) compressed, streamed package, located at the relativePath passed in the constructor.

getCollection

 public ResourceCollection getCollection()

Generates a collection for this wizard. It must be currently set to a particular embedded type (via setEmbedType()) before this method is called.

Returns:: The resource collection consisting of the files required to embed this package into the wizard archive.

resolveResource

 public ResourceInputStream resolveResource(String section,
                                            String name,
                                            byte extData[])

Resolves resources for this wizard (namely the admin/response files, and the package data itself, in the case of an embedded package).

Parameters:: section - The section name of the resource to be resolved; name - The name of the resource to be resolved; extData - The extra data for this resource, if any.
Returns:: A stream that the resource can be read from

getStreamSize

 protected long getStreamSize() throws IOException

Gets the size of the stream that the streamed package can be read from.

Returns:: the size of the stream that the streamed package can be read from.

getStream

 protected InputStream getStream() throws IOException

Gets a stream that the package stream data can be read from (at buildtime).

Returns:: A stream that the package can be read from (at buildtime).

getArchiveStream

 protected ResourceInputStream getArchiveStream() throws IOException

Gets a stream pointing to the streamed package which is inside the wizard archive.

Returns:: A stream pointing to the streamed package which is inside the wizard archive.

closeArchiveStream

 protected void closeArchiveStream() throws IOException

Closes stream that accesses the embedded package. Should be called after each getArchiveStream() (after processing the stream).

getInstallLocation

 public String getInstallLocation()

Form the install location based on the installDirKey and a possible relative path. Althernate root is not considered in this method.

Returns:: The location this FileUnit will install to
Overrides:: getInstallLocation in class InstallComponent

install

 public boolean install(WizardState state)

Install (pkgadd) the package. This is the most important method this class overrides from InstallLeaf. This actually does the install, and reports the progress by using a ProgressTimer. It first lays down the admin and response files into the system temporary directory, and then executes pkgadd with the appropriate parameters.

Parameters:: state - The wizard state this component belongs to
Returns:: true, if the installation was sucessful, false otherwise
Overrides:: install in class InstallComponent

uninstall

 public boolean uninstall(WizardState state)

Uninstall (pkgrm) the package. The same admin file is used as was used during install. In addition, the -n flag is passed to pkgrm to avoid interaction. The package is first checked using pkginfo to verify its existance.

Parameters:: state - The wizard state this component belongs to
Returns:: true if the removal of this package was sucessful, false otherwise
Overrides:: uninstall in class InstallComponent

isInstallable

 public boolean isInstallable(WizardState state)

Determine if this package is installable. Several sanity checks are run here:

Relative path is valid
A valid pkginfo file can be found

Parameters:: state - The wizard state this component belongs to
Returns:: true, if this is a valid, installable SVR4 package, false otherwise.

isUninstallable

 public boolean isUninstallable(WizardState state)

Determine if this package is unInstallable. Until uninstall is implemented, this method always returns false

Parameters:: state - The wizard state this component belongs to
Returns:: true, if this component is able to be removed, false otherwise

toString

 public String toString()

Represent this object as a string.

Returns:: A textual representation of this component, consisting of it's name and runtime install destination.
Overrides:: toString in class InstallComponent

initialize

 public boolean initialize(WizardState state)

Initialize this PkgUnit. This method reads in the meta-files for this package (admin, response files) and parses them. It also collects locale and architecture information about the package.

Parameters:: wizardState - The wizardstate this component belongs to
Returns:: true, if this PkgUnit was able to parse its meta files (pkginfo, response, admin), false otherwise.
Overrides:: initialize in class InstallComponent

refresh

 public boolean refresh(Vector targets,
                        String sharedPoolKey)

Update this Package. For the PkgUNit, the pkgmap is re-read and size re-calculated based on any new directory information.

Parameters:: targets - The target properties (set via setProperty()) to update.; sharedPoolKey - The key to use during the shared pool verification.
Returns:: true if the refresh was sucessful, falseotherwise.
Overrides:: refresh in class InstallComponent

getDestinationTable

 public static Hashtable getDestinationTable(Hashtable sizeTable,
                                             String alternateRoot,
                                             String newDirectory)

Creates the destination table out of a pre-processed pathname listing, an alternate root, and a directory.

Parameters:: sizeTable - the pre-processed table of directories and their sizes, in Longs. The table can contain both relative and absolute pathnames/; alternateRoot - The directory to prepend to all entries in the table, whether the entries are relative or absolute.; newDirectory - The direcectory to prepend to the relative paths that are present in the table.
Returns:: The new table of processed pathnames and sizes.

readPkgMap

 public static Hashtable readPkgMap(String path,
                                    Hashtable env)

Reads the pkgmap of an SVR4 package, and returns the resulting table of relative directory names and the total size of all files in those directories that are contained in the pkgmap.

Parameters:: path - The full path to the pkgmap file to read; env - The environment to resolve variables from. If a pkgmap entry has a parametric variable, this environment is searched to resolve the variable, recursively.
Returns:: The resulting table of relative and absolute paths, along with the size (in a Long) representing the total of all files to be placed in that directory.

addRuntimeResources

 public void addRuntimeResources(Vector resourceVector)

Add the runtime resources required by this class.

Parameters:: resourceVector - The vector containing all of the required resources for this class
Overrides:: addRuntimeResources in class InstallLeaf

main

 public static void main(String args[])

Shows size information for a package.

usage: java PkgUnit

Parameters:: args - The arguments to the class

All Packages  Class Hierarchy  This Package  Previous  Next  Index