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 ClassDep

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

public class ClassDep
extends Object

Tool used to analyze a set of classes and determine on what other classes they directly or indirectly depend. Typically this tool is used to compute the necessary and sufficient set of classes to include in a JAR file, for use in the class path of a client or service, or for use in the codebase of a client or service. The tool starts with a set of "root" classes and recursively computes a dependency graph, finding all of the classes referenced directly by the root classes, finding all of the classes referenced in turn by those classes, and so on, until no new classes are found or until classes that are not of interest are found. The normal output of the tool is a list of all of the classes in the dependency graph. The output from this command can be used as input to the `jar` tool, to create a JAR file containing precisely those classes.

The following items are discussed below:

- Running the Tool
- Processing Options
- Output Options and Arguments
- Examples

### Running the Tool

To run the tool on UNIX platforms:

>      java -cp jsk_install_dir/lib/tools.jar:sdk_install_dir/lib/tools.jar
>           com.sun.jini.tool.ClassDep
>           -cp input_classpath processing_options output_options

To run the tool on Microsoft Windows platforms:

>      java -cp jsk_install_dir\lib\tools.jar;sdk_install_dir\lib\tools.jar
>           com.sun.jini.tool.ClassDep
>           -cp input_classpath processing_options output_options

Note that the options for this tool can be specified in any order, and can be intermixed. The first `-cp` class path value is an argument to the `java` command that executes the `ClassDep` tool, and must include the locations of the two JAR files necessary to execute the tool:

- The `tools.jar` file in the `lib` directory of the Jini(TM) Technology Starter Kit (starter kit) installation directory, jsk_install_dir
- The `tools.jar` file in the `lib` directory of the Java(TM) 2 SDK installation directory, sdk_install_dir

Note that the order of locations in this path does not matter.

The second `-cp` class path value, input_classpath, is an argument to the `ClassDep` tool itself and should include all of the classes that might need to be included in the dependency analysis. Typically this will include all of your application classes, classes from the starter kit, and any other classes on which your classes might depend. It is safe to include more classes than are actually necessary (since the purpose of this tool is, after all, to determine which subset of these classes is actually necessary), but it is not necessary to include any classes that are part of the Java 2 SDK. The class path should be in the form of a list of directories or JAR files, delimited by a colon (":") on UNIX platforms and a semi-colon (";") on Microsoft Windows platforms. The order of locations in the path does not matter. If you use JAR files, any `Class-Path` manifest entries in those JAR files are ignored, so you must include the values of those manifest entries explicitly in the path, or errors may result. For example, if you include `jini-ext.jar` then you should explicitly include `jini-core.jar` as well, because `jini-core.jar` is in the `Class-Path` manifest entry of `jini-ext.jar`.

### Processing Options

The root classes of the dependency graph can be specified by any combination of individual classes and directories of classes. Each of these options can be used any number of times, and are illustrated in the Examples section of this page.

In general, you only need to specify concrete classes as roots, not interface types. When analyzing classes for the class path of an application, you typically need to include the top-level class (the one with the `main` method). When analyzing classes for the codebase of a service, you typically need to include the top-level proxy classes used by the service, any trust verifier classes for those proxies, and any custom entry classes used by the service for lookup service attributes. Also when analyzing classes for the codebase of a service, if the service's proxy can return leases, registration objects, or other proxies, or if your service generates events, and if those objects are only referenced by interface type in the top-level proxy, not by concrete class, then you also need to include the concrete classes of those other objects. In all cases, you typically need to include any stub classes that you generated with the `rmic` tool.

class
  This option specifies the fully qualified name of an individual class to include as a root of the dependency graph. This option can be specified zero or more times. Each class you specify with this option needs to be in a package that is defined to be "inside" the graph (as described further below).

directory
  This option specifies the root directory of a tree of compiled class files, all of which are to be included as roots of the dependency graph. This option can be specified zero or more times. The directory must be one of the directories specified in input_classpath, or a subdirectory of one, and must contain at least one filename separator character. Each class in the tree needs to be in a package that is defined to be "inside" the graph (as described further below).

  The `-prune` option can be used to exclude particular subtrees from the set of roots.

  `-prune` package-prefix
    Specifies a package namespace to exclude when selecting roots from directory trees. Within the directory trees, any classes that are in the given package or a subpackage of it are not treated as roots. Note that this option has no effect on whether the classes in question end up "inside" or "outside" the dependency graph (as defined further below); it simply controls their use as roots. This option can be specified zero or more times. Note that the argument to `-prune` is a package namespace (delimited by "."), not a directory.

  The `-skip` option (described further below) can be used to exclude specific classes from the set of roots.

Starting with the root classes, a dependency graph is constructed by examining the compiled class file for a class, finding all of the classes it references, and then in turn examining those classes. The extent of the graph is determined by which packages are defined to be "inside" the graph and which are defined to be "outside" the graph. If a referenced class is in a package that is defined to be outside the graph, that class is not included in the graph, and none of classes that it references are examined. All of the root classes must be in packages that are defined to be "inside" the graph.

The inside and outside packages are specified by using the following options. Each of these options may be specified zero or more times. Some variations are illustrated in the Examples section of this page.

`-in` package-prefix
  Specifies a namespace of "inside" packages. Any classes in this package or a subpackage of it are included in the dependency graph (and hence are to be included in your JAR file), unless they are explicitly excluded using `-out` or `-skip` options. This option can be specified zero or more times. If no `-in` options are specified, the default is that all packages are considered to be inside packages. Note that the argument to `-in` is a namespace, so none of its subpackages need to be specified as an argument to `-in`.

  If you use this option, you will likely need to use it multiple times. For example, if your application classes are in the `com.corp.foo` namespace, and you also use some classes in the `com.sun.jini` and `net.jini` namespaces, then you might specify:

      -in com.corp.foo -in com.sun.jini -in net.jini

`-out` package-prefix
  Specifies a namespace of "outside" packages. Any classes in this package or a subpackage of it are excluded from the dependency graph (and hence are to be excluded from your JAR file). This option can be specified zero or more times. If you specify `-in` options, then each `-out` namespace should be a subspace of some `-in` namespace. Note that the argument to `-out` is a namespace, so none of its subpackages need to be specified as an argument to `-out`.

  If you use this option, you will likely need to use it multiple times. For example, if you do not specify any `-in` options, then all packages are considered inside the graph, including packages defined in the Java 2 SDK that you typically want to exclude, so you might exclude them by specifying:

      -out java -out javax

  As another example, if you have specified `-in com.corp.foo` but you don't want to include any of the classes in the `com.corp.foo.test` or `com.corp.foo.qa` namespaces in the dependency graph, then you would specify:

      -out com.corp.foo.test -out com.corp.foo.qa

`-skip` class
  Specifies the fully qualified name of a specific class to exclude from the dependency graph. This option allows an individual class to be considered "outside" without requiring the entire package it is defined in to be considered outside. This option can be specified zero or more times.

`-outer`
  By default, if a static nested class is included in the dependency graph, all references from that static nested class to its immediate lexically enclosing class are ignored, to avoid inadvertent inclusion of the enclosing class. (The default is chosen this way because the compiled class file of a static nested class always contains a reference to the immediate lexically enclosing class.) This option causes all such references to be considered rather than ignored. Note that this option is needed very infrequently.

### Output Options and Arguments

The following options and arguments determine the content and format of the output produced by this tool. These options do not affect the dependency graph computation, only the information displayed in the output as a result of the computation. Most of these options may be specified multiple times. Some variations are illustrated in the Examples section of this page.

`-edges`
  By default, the classes which are included in the dependency graph are displayed in the output. This option specifies that instead, the classes which are excluded from the dependency graph, but which are directly referenced by classes in the dependency graph, should be displayed in the output. These classes form the outside "edges" of the dependency graph.

  For example, you might exclude classes from the Java 2 SDK from the dependency graph because you don't want to include them in your JAR file, but you might be interested in knowing which classes from the Java 2 SDK are referenced directly by the classes in your JAR file. The `-edges` option can be used to display this information.

`-show` package-prefix
  Displays the classes that are in the specified package or a subpackage of it. This option can be specified zero or more times. If no `-show` options are specified, the default is that all classes in the dependency graph are displayed (or all edge classes, if `-edges` is specified). Note that the argument to `-show` is a namespace, so none of its subpackages need to be specified as an argument to `-show`.

  For example, to determine which classes from the Java 2 SDK your application depends on, you might not specify any `-in` options, but limit the output by specifying:

      -show java -show javax

`-hide` package-prefix
  Specifies a namespace of packages which should not be displayed. Any classes in this package or a subpackage of it are excluded from the output. This option can be specified zero or more times. If you specify `-show` options, then each `-hide` namespace should be a subspace of some `-show` namespace. Note that the argument to `-hide` is a namespace, so none of its subpackages need to be specified as an argument to `-hide`.

  For example, to determine which non-core classes from the `net.jini` namespace you use, you might specify:

      -show net.jini -hide net.jini.core

`-files`
  By default, fully qualified class names are displayed, with package names delimited by ".". This option causes the output to be in filename format instead, with package names delimited by filename separators and with ".class" appended. For example, using this option on Microsoft Windows platforms would produce output in the form of `com\corp\foo\Bar.class` instead of `com.corp.foo.Bar`. This option should be used to generate output suitable as input to the `jar` tool.

  For more information on the `jar` tool, see:

  - http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/jar.html
  - http://java.sun.com/j2se/1.4/docs/tooldocs/windows/jar.html
  - http://java.sun.com/j2se/1.4/docs/guide/jar/jar.html

`-tell` class
  Specifies the fully qualified name of a class for which dependency information is desired. This option causes the tool to display information about every class in the dependency graph that references the specified class. This information is sent to the error stream of the tool, not to the normal output stream. This option can be specified zero or more times. If this option is used, all other output options are ignored, and the normal class output is not produced. This option is useful for debugging.

### Examples

The following example computes the classes required for a codebase JAR file, starting with a smart proxy class and a stub class as roots, and displays them in filename format. (A more complete example would include additional roots for leases, registrations, events, and lookup service attributes.)

>      java -cp jsk_install_dir/lib/tools.jar:sdk_install_dir/lib/tools.jar
>           com.sun.jini.tool.ClassDep
>           -cp jsk_install_dir/source/vob/jive/classes
>           com.sun.jini.reggie.RegistrarProxy com.sun.jini.reggie.RegistrarImpl_Stub
>           -in com.sun.jini -in net.jini
>           -files

The following example computes the classes required for a classpath JAR file, starting with all of the classes in a directory as roots, and displays them in class name format.

>      java -cp jsk_install_dir/lib/tools.jar:sdk_install_dir/lib/tools.jar
>           com.sun.jini.tool.ClassDep
>           -cp jsk_install_dir/source/vob/jive/classes
>           jsk_install_dir/source/vob/jive/classes/com/sun/jini/reggie
>           -in com.sun.jini -in net.jini

The following example computes the `com.sun.jini` classes used by a service implementation, and displays the `net.jini` classes that are immediately referenced by those classes.

>      java -cp jsk_install_dir/lib/tools.jar:sdk_install_dir/lib/tools.jar
>           com.sun.jini.tool.ClassDep
>           -cp jsk_install_dir/source/vob/jive/classes
>           com.sun.jini.reggie.RegistrarImpl
>           -in com.sun.jini
>           -edges
>           -show net.jini

The following example computes all of the classes used by a service implementation that are not part of the Java 2 SDK, and displays the classes that directly reference the class `java.awt.Image`.

>      java -cp jsk_install_dir/lib/tools.jar:sdk_install_dir/lib/tools.jar
>           com.sun.jini.tool.ClassDep
>           -cp jsk_install_dir/lib/reggie.jar
>           com.sun.jini.reggie.RegistrarImpl
>           -out java -out javax
>           -tell java.awt.Image

The following example computes all of the classes to include in `jini-ext.jar` and displays them in filename format. Note that both `-out` and `-prune` options are needed for the `net.jini.core` namespace; `-out` to exclude classes from the dependency graph, and `-prune` to prevent classes from being used as roots.

>      java -cp jsk_install_dir/lib/tools.jar:sdk_install_dir/lib/tools.jar
>           com.sun.jini.tool.ClassDep
>           -cp jsk_install_dir/source/vob/jive/classes
>           -in net.jini -out net.jini.core -in com.sun.jini
>           jsk_install_dir/source/vob/jive/classes/net/jini -prune net.jini.core
>           -files

Constructor Summary
`ClassDep()` No argument constructor.
`ClassDep(String[] cmdLine)` Constructor that takes command line arguments and fills in the appropriate fields.

Method Summary
`void` | `addClasses(String className)` Add an entry into the set of classes that dependencies are going to be computed on.
`void` | `addHides(String packagePrefix)` Add an entry into the set of package prefixes that are to remain hidden from processing.
`void` | `addInside(String packagePrefix)` Add an entry into the working set of package prefixes that will make up the working domain space.
`void` | `addOutside(String packagePrefix)` Add an entry into the set of package prefixes that will bypassed during dependency checking.
`void` | `addPrune(String packagePrefix)` Add an entry into the set of package prefixes that will be skipped as part of the dependency generation.
`void` | `addRoots(String rootName)` Add an entry into the set of directories to look under for the classes that fall within the working domain space as defined by the intersection of the following sets: inside,outside,prune,show, and hide.
`void` | `addShow(String packagePrefix)` Add an entry into the set of package prefixes that we want to display.
`void` | `addSkip(String packagePrefix)` Add an entry into the set of classes that should be skipped during dependency generation.
`void` | `addTells(String packagePrefix)` Add an entry in to the set of classes whose dependents that lie with the inside set are listed.
`String[]` | `compute()` Method that takes the user provided switches that logically define the domain in which to look for dependencies.
`boolean` | `getFiles()` If true classnames will be separated using File.separator, else it will use dots.
`String[]` | `getResults()` Accessor method for the found dependencies.
`static void` | `main(String[] args)` Command line interface for generating the list of classes that a set of classes depends upon.
`void` | `setClassPath(String classpath)` Set the classpath to use for finding our class definitions.
`void` | `setEdges(boolean edges)` Determines whether to include package references that lie outside the declared set of interest.
`void` | `setFiles(boolean files)` Determines how to print out the fully qualified class names.
`void` | `setupOptions(String[] args)` Convenience method for initializing an instance with specific command line arguments.
`static void` | `usage()` Print out the usage for this utility.

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

Constructor Detail

### ClassDep

    public ClassDep()

  No argument constructor. The user must fill in the appropriate fields prior to asking for the processing of dependencies.

### ClassDep

    public ClassDep(String[] cmdLine)

  Constructor that takes command line arguments and fills in the appropriate fields. See the description of this class for a list and description of the acceptable arguments.

Method Detail

### compute

    public String[] compute()

  Method that takes the user provided switches that logically define the domain in which to look for dependencies.

### usage

    public static void usage()

  Print out the usage for this utility.

### setClassPath

    public void setClassPath(String classpath)

  Set the classpath to use for finding our class definitions.

### setFiles

    public void setFiles(boolean files)

  Determines how to print out the fully qualified class names. If `true` it will use `File.separator`, else `.`'s will be used. If not set the default is `false`.

### addHides

    public void addHides(String packagePrefix)

  Add an entry into the set of package prefixes that are to remain hidden from processing.

### addInside

    public void addInside(String packagePrefix)

  Add an entry into the working set of package prefixes that will make up the working domain space.

### setEdges

    public void setEdges(boolean edges)

  Determines whether to include package references that lie outside the declared set of interest.

  If true edges will be processed as well, else they will be ignored. If not set the default will be `false`.

  Note: These edge classes must included in the classpath for this utility.

### addOutside

    public void addOutside(String packagePrefix)

  Add an entry into the set of package prefixes that will bypassed during dependency checking. These entries should be subsets of the contents on the inside set.

### addPrune

    public void addPrune(String packagePrefix)

  Add an entry into the set of package prefixes that will be skipped as part of the dependency generation.

### addShow

    public void addShow(String packagePrefix)

  Add an entry into the set of package prefixes that we want to display. This applies only to the final output, so this set should be a subset of the inside set with edges, if that was indicated.

### addSkip

    public void addSkip(String packagePrefix)

  Add an entry into the set of classes that should be skipped during dependency generation.

### addTells

    public void addTells(String packagePrefix)

  Add an entry in to the set of classes whose dependents that lie with the inside set are listed. This in the converse of the rest of the utility and is meant more for debugging purposes.

### addRoots

    public void addRoots(String rootName)

  Add an entry into the set of directories to look under for the classes that fall within the working domain space as defined by the intersection of the following sets: inside,outside,prune,show, and hide.

### addClasses

    public void addClasses(String className)

  Add an entry into the set of classes that dependencies are going to be computed on.

### getFiles

    public boolean getFiles()

  If true classnames will be separated using File.separator, else it will use dots.

### getResults

    public String[] getResults()

  Accessor method for the found dependencies.

### setupOptions

    public void setupOptions(String[] args)

  Convenience method for initializing an instance with specific command line arguments. See the description of this class for a list and description of the acceptable arguments.

### main

    public static void main(String[] args)

  Command line interface for generating the list of classes that a set of classes depends upon. See the description of this class for a list and description of the acceptable arguments.

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