org.apache.river.tool

Class ClassDep

java.lang.Object

org.apache.river.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

The command line for running the tool has the form:

 java -jar install_dir/lib/classdep.jar \
      -cp input_classpath processing_options output_options
 

where install_dir is the directory where the River-Internet release is installed. Note that the options for this tool can be specified in any order, and can be intermixed.

The -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 River-Internet release, 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).

directory

This option specifies the root directory of a tree of compiled class files that are considered as root for the dependency checking. This option can be specified zero or more times. The actual behavior depends on whether the -newdirbehavior options is specified. The directory must contain at least one filename separator character and be one of the directories specified in input_classpath, or when the old behavior is effective it can be a subdirectory of one of the directories on the input_classpath. Each class in the tree needs to be in a package that is defined to be "inside" the graph (as described further below).

When the -newdirbehavior options is set the -inroot and -outroot options can be used to include/exclude particular subtrees from the potential set of roots. When the old behavior is effective all classes are considered as root, but can be excluded through the -prune option.

-inroot package-prefix (only valid with -newdirbehavior)

Specifies a package namespace to include when selecting roots from the directory trees. Any classes found in this package or a subpackage of it are considered as root for the dependency checking, unless they are explicitly excluded using -out, -skip or -outroot options. If not specified all found classes are considered roots. This option can be specified zero or more times. Note that the argument to -inroot is a package namespace (delimited by "."), not a directory.

-outroot package-prefix (only valid with -newdirbehavior)

Specifies a package namespace to exclude when selecting roots from the directory trees. Within the directory trees as specified by the rootdir element, any classes that are in the given package or a subpackage of it are not treated as roots. This option can be specified zero or more times. Note that the argument to -outroot is a package namespace (delimited by "."), not a directory.

-prune package-prefix (old behavior only)

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 org.apache.river and net.jini namespaces, then you might specify:

-in com.corp.foo -in org.apache.river -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 (except when the static nested class extends its outer class), 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.

-newdirbehavior

This option causes the utility to select classes, to serve as root for the dependency checking, from the directory argument based on the -inroot and -outroot options specified. When this option is set subdirectories of the specified directory are no longer considered as root for finding classes. When this option is not set, the default, the utility maintains the old behavior with respect to the semantics for the directories passed in and the -prune option must be used. You are advised to set this option as there are some edge cases for which the old behavior won't work as expected, especially when no -in options are set.

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 examples in this section assume you ran the River-Internet release installer with an "Install Set" selection that created the top-level classes directory. Alternatively, if you have compiled from the source code, substitute source/classes for classes in the 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, and would exclude platform classes such as those in jsk-platform.jar.)

 java -jar install_dir/lib/classdep.jar \
      -cp install_dir/classes \
      org.apache.river.reggie.RegistrarProxy org.apache.river.reggie.RegistrarImpl_Stub \
      -in org.apache.river -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. (A more complete example would exclude platform classes such as those in jsk-platform.jar.)

 java -jar install_dir/lib/classdep.jar \
      -cp install_dir/classes \
      install_dir/classes/org/apache/river/reggie \
      -in org.apache.river -in net.jini
 

The following example computes the org.apache.river classes used by a service implementation, and displays the net.jini classes that are immediately referenced by those classes.

 java -jar install_dir/lib/classdep.jar \
      -cp install_dir/classes \
      org.apache.river.reggie.RegistrarImpl \
      -in org.apache.river \
      -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 -jar install_dir/lib/classdep.jar \
      -cp install_dir/classes \
      org.apache.river.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 -jar install_dir/lib/classdep.jar \
      -cp install_dir/classes \
      -in net.jini -out net.jini.core -in org.apache.river \
      install_dir/classes/net/jini -prune net.jini.core \
      -files
 

Author:

Sun Microsystems, Inc.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
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	addInsideRoot(String packagePrefix) Adds an entry into the set of package prefixes for which classes found through the specified root directories will be considered for dependency generation.
void	addOutside(String packagePrefix) Add an entry into the set of package prefixes that will bypassed during dependency checking.
void	addOutsideRoot(String packagePrefix) Adds an entry into the set of package prefixes for which classes found through the specified root directories, and that are part of the inside root namespace, will be skipped as part of the dependency generation.
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 className) 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.
boolean	hasFailed() Indicates whether computing the dependent classes as result of the last call to compute() resulted in one or more failures.
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	setRootDirBehavior(boolean newBehavior) Controls whether the behavior for finding class files in the specified directories, if any, must be based on the old behavior (the default) or the new behavior that solves some of the problems with the old behavior.
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.

Parameters:

cmdLine -

Method Detail

compute

public String[] compute()

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

Whether a failure has occurred during computing the dependent classes can be found out with a call to hasFailed().

Returns:

array containing the dependent classes found in the format as specified by the options passed in

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.

Parameters:

classpath -

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.

Parameters:

files -

addHides

public void addHides(String packagePrefix)

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

Parameters:

packagePrefix -

addInside

public void addInside(String packagePrefix)

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

Parameters:

packagePrefix -

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.

Parameters:

edges -

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.

Parameters:

packagePrefix -

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.

This method has no impact if the new behavior is effective for the interpretation of the root directories for finding class files to include for dependency checking.

Parameters:

packagePrefix -

setRootDirBehavior

public void setRootDirBehavior(boolean newBehavior)

Controls whether the behavior for finding class files in the specified directories, if any, must be based on the old behavior (the default) or the new behavior that solves some of the problems with the old behavior.

Parameters:

newBehavior -

addInsideRoot

public void addInsideRoot(String packagePrefix)

Adds an entry into the set of package prefixes for which classes found through the specified root directories will be considered for dependency generation.

Adding entries without a call to setRootDirBehavior(boolean) with true as the argument will cause compute() to fail.

Parameters:

packagePrefix -

addOutsideRoot

public void addOutsideRoot(String packagePrefix)

Adds an entry into the set of package prefixes for which classes found through the specified root directories, and that are part of the inside root namespace, will be skipped as part of the dependency generation.

Adding entries without a call to setRootDirBehavior(boolean) with true as the argument will cause compute() to fail.

Parameters:

packagePrefix -

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.

Parameters:

packagePrefix -

addSkip

public void addSkip(String packagePrefix)

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

Parameters:

packagePrefix -

addTells

public void addTells(String className)

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.

Parameters:

className -

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.

Parameters:

rootName -

addClasses

public void addClasses(String className)

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

Parameters:

className -

getFiles

public boolean getFiles()

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

Returns:

true or false

getResults

public String[] getResults()

Accessor method for the found dependencies.

Returns:

String[] dependencies

hasFailed

public boolean hasFailed()

Indicates whether computing the dependent classes as result of the last call to compute() resulted in one or more failures.

Returns:

true in case a failure has happened, such as a class not being found, false otherwise

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.

Parameters:

args -

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.