Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.jini.tool
Class JarWrapper

    java.lang.Object
      com.sun.jini.tool.JarWrapper

public class JarWrapper
extends Object

A tool for generating "wrapper" JAR files. A wrapper JAR file contains a `Class-Path` manifest attribute listing a group of JAR files to be loaded from a common codebase. It may also, depending on applicability and selected options, contain a JAR index file, a preferred class list and/or a `Main-Class` manifest entry for the grouped JAR files.

The following items are discussed below:

- Applicability
- Command line options
- Logging
- Examples for running JarWrapper

### Applicability

The `JarWrapper` tool is applicable in the following deployment situations, which may overlap:

- If a codebase contains multiple JAR files which declare preferred resources, `JarWrapper` can be used to produce a wrapper JAR file with a combined preferred list. Preferred resources are described in the documentation for the `net.jini.loader.pref` package.

- If a codebase contains multiple JAR files and requires integrity protection, `JarWrapper` can be used to produce a wrapper JAR file with a `Class-Path` attribute that uses HTTPMD URLs. HTTPMD URLs are described in the documentation for the `net.jini.url.httpmd` package.

- If an application or service packaged as an executable JAR file refers to classes specified at deployment time (e.g., via a `Configuration`) which are not present in the JAR file or its `Class-Path`, `JarWrapper` can be used to produce a wrapper JAR file which includes the extra classes in its `Class-Path` while retaining the original `Main-Class` declaration; the wrapper JAR file can then be executed in place of the original JAR file.

### Logging

`JarWrapper` uses the `Logger` named `com.sun.jini.tool.JarWrapper` to log information at the following logging levels:

`com.sun.jini.tool.JarWrapper`
Level | Description
--- | ---
`WARNING` | Generated JAR index entries that do not end in `".jar"`
`FINE` | Names of processed source JAR files and output wrapper JAR file
`FINER` | Processing of `Main-Class` and `Class-Path` attributes, and presence of preferred lists and JAR indexes
`FINEST` | Processing and compilation of preferred lists and JAR indexes

### Examples for running JarWrapper

`JarWrapper` can be run directly from the command line or can be invoked programmatically using the `wrap` method.

An example of running directly from the command line is:

>      % java -classpath install_dir/lib/tools.jar com.sun.jini.tool.JarWrapper
>             -httpmd=MD5 wrapper.jar base_dir src1.jar src2.jar

where install_dir is the directory where the starter kit is installed. This command line would result in the creation of a wrapper JAR file, `wrapper.jar`, in the current working directory, whose contents would be based on the source JAR files `src1.jar` and `src2.jar` (as well as any other JAR files referenced transitively through their `Class-Path` attributes or JAR indexes). The paths for `src1.jar` and `src2.jar`, as well as any transitively referenced JAR files, would be resolved relative to the `base_dir` directory. The `Class-Path` attribute of `wrapper.jar` would use HTTPMD URLs with MD5 digests.

The equivalent programmatic invocation of `JarWrapper` would be:

>      JarWrapper.wrap("wrapper.jar", "base_dir", new String[]{ "src1.jar", "src2.jar" }, "MD5", true);

Since:
  2.0

Method Summary
`static void` | `main(String[] args)` Generates a wrapper JAR file for the specified JAR files.
`static void` | `wrap(String destJar, String baseDir, String[] srcJars, String httpmdAlg, boolean index)` Generates a wrapper JAR file based on the provided values in the same manner as described in the documentation for `main(java.lang.String[])`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### main

    public static void main(String[] args)

  Generates a wrapper JAR file for the specified JAR files. The command line arguments are:

       [ options ] dest-jar base-dir src-jar [ src-jar ...]

  The dest-jar argument specifies the name of the wrapper JAR file to generate. The base-dir argument specifies the base directory from which to locate source JAR files to wrap. The src-jar arguments are non-absolute URLs to "top-level" source JAR files relative to base-dir; they also constitute the basis of the `Class-Path` attribute included in the generated wrapper JAR file. JAR files not present in the command line but indirectly referenced via JAR index or `Class-Path` entries in source JAR files will themselves be used as source JAR files, and will appear alongside the top-level source JAR files in the `Class-Path` attribute of the wrapper JAR file in depth-first order, with JAR index references appearing before `Class-Path` references. This utility does not modify any source JAR files.

  If any of the top-level source JAR files contain preferred resources (as indicated by a preferred list in the JAR file), then a preferred list describing resource preferences across all source JAR files will be included in the wrapper JAR file. The preferred list of a top-level source JAR file is interpreted as applying to that JAR file along with all JAR files transitively referenced by it through JAR index or `Class-Path` entries, excluding JAR files that have already been encountered in the processing of preceding top-level JAR files. If a given top-level source JAR file does not contain a preferred list, then all resources contained in it and its transitively referenced JAR files (again, excluding those previously encountered) are considered not preferred. Preferred lists are described further in the documentation for `PreferredClassLoader`.

  If any of the top-level source JAR files declare a `Main-Class` manifest entry, then the wrapper JAR file will include a `Main-Class` manifest entry whose value is that of the first top-level source JAR file listed on the command line which defines a `Main-Class` entry.

  Supported options for this tool include:

  `-verbose`
    Sets the level of the `com.sun.jini.tool.JarWrapper` logger to `Level.FINER`.

  `-httpmd[=algorithm]`
    Use (relative) HTTPMD URLs in the `Class-Path` attribute of the generated wrapper JAR file. The default is to use HTTP URLs. Digests for HTTPMD URLs are calculated using the given algorithm, or MD5 if none is specified.

  `-noindex`
    Do not include a JAR index in the generated wrapper JAR file. The default is to compile an index based on the contents of the source JAR files.

### wrap

    public static void wrap(String destJar,
                            String baseDir,
                            String[] srcJars,
                            String httpmdAlg,
                            boolean index)
                     throws IOException

  Generates a wrapper JAR file based on the provided values in the same manner as described in the documentation for `main(java.lang.String[])`. The only difference between this method and `main` is that it receives its values as explicit arguments instead of in a command line, and indicates failure by throwing an exception.

  Parameters:
    `destJar` - name of the wrapper JAR file to generate
    `baseDir` - base directory from which to locate source JAR files to wrap
    `srcJars` - list of top-level source JAR files to process
    `httpmdAlg` - name of algorithm to use for generating HTTPMD URLs, or `null` if plain HTTP URLs should be used
    `index` - if `true`, generate a JAR index; if `false`, do not generate one
  Throws:
    `IOException` - if an I/O error occurs while processing source JAR files or generating the wrapper JAR file
    `IllegalArgumentException` - if the provided values are invalid
    `NullPointerException` - if `destJar`, `baseDir`, `srcJars`, or any element of `srcJars` is `null`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved