SYNOPSIS

UNIX:

lint4j [-J vmoptions] [-v level] -sourcepath path[:path]* [-classpath path[:path]*] [-exclude packagename]* [-class class[:class]*] packagename+

Windows (Make sure to enclose path arguments in quotes):

lint4j.bat [-J vmoptions] [-home lint4jpath] [-javahome path] [-v level] -sourcepath path[;path]* [-classpath path[;path]*] [-exclude packagename]* [-class class[:class]*] [packagename | filename]+

Description

The program expects one or more package, class or file names that will be analyzed. The options are as follows:

• -J vmoptions - pass additional options to the Java VM, for example -J \"-Xms100M -Xmx200M\" for larger heap size. If present, it must be the first argument.
• -home path - pass the base directory to the lint4j distribution. Optional if an environment variable exists. (Windows only)
• -javahome path - select a java distribution. Optional, if there is a java executable in the path. (Windows only)
• -v level - specify the verbosity of the emitted warnings. Range is from severe (1) to suggestion (5). Default is 3. Optional.
• -sourcepath path - specify the jar file or directory paths which Lint4j will use to scan for source and class files to analyze, e.g. /Users/Shared/src. Several paths can be specified, separated by the ':' character (';' on Windows), e.g. -sourcepath dir1:dir2. Classes and packages found using -sourcepath will be part of the analysis of packages (last arguments) and classes as specified with the -class option.
• -classpath path - specify the paths for all additional classes referenced by the source files, this can be zip files, jar files, or directories. Several paths can be specified, separated by the ':' character (';' on Windows), e.g. -classpath lib/one.jar:lib/two.jar. There is no analysis performed on classes that are loaded via -classpath. Optional.
• -exclude packagename - exclude the given package or package prefix in the analysis, e.g. -exclude java.lang excludes just the java.lang package, whereas -exclude java.lang. excludes all packages including and below java.lang. Optional.
• -class class names to be checked, separated by the ':' character. Class names must be fully qualified. Optional.

Instead of a package name you can specify a wildcard package name such as java.util.*, which would check the package java.util and all of its subpackages. However, general wildcards are currently not implemented, so referencing the javax and java package by specifying java* doesn't work.

Examples

Here is how Lint4j is invoked on its own source (the backslash is necessary to prevent a Unix shell from expanding the wildcard character'*'):

prompt> lint4j -sourcepath src/main -classpath lib/bcel.jar:lib/ant.jar com.jutils.lint4j.\*

Invoking Lint4j on the log4j binary distribution (the backslash is necessary to prevent a Unix shell from expanding the wildcard character'*'):

prompt> lint4j -sourcepath /Users/Shared/lib/log4j.jar org.apache.\*

Invoking Lint4j on two packages in the log4j binary distribution:

prompt> lint4j -sourcepath /Users/Shared/lib/log4j.jar org.apache.log4j org.apache.log4j.spi

Invoking Lint4j on two files from the BCEL 5.1 distribution:

prompt> lint4j -sourcepath . org/apache/bcel/verifier/VerifierFactory.java org/apache/bcel/verifier/Verifier.java

On Windows it looks like this:

prompt> lint4j -sourcepath src/main -classpath "lib/bcel.jar;lib/ant.jar" com.jutils.lint4j.*

The distribution comes with an Ant build file that performs checks on the JDK 1.4 java code base, Tomcat 5, JBoss 3.2, JBoss 4, and on several SUN J2EE examples, such as ecperf, the Adventure Builder, PetStore, and the Smart Ticket applications, plus Unix shell scripts that check the JDK 1.4 java code base, Tomcat 5, and JBoss 3.2, and JBoss 4.

The section about setting Lint4j to audit PetStore contains more tips to speed up the configuration.

Installation

The Ant plugin is enabled by copying the LINT4J_HOME/jars/lint4j.jar to ANT_HOME/lib, or by declaring a task definition such as the following in the build.xml file.

<taskdef name="lint4j" classname="com.jutils.lint4j.ant.Lint4jAntTask">
    <classpath><pathelement location="${distdir}/jars/lint4j.jar"/></classpath>
</taskdef>

Lint4j Task Attributes

Attribute	Description	Default	Required
sourcepath	specify the paths that contain the source files for Lint4j to analyze. Several paths can be specified, separated by the ',' character.	Not set	Yes, unless sourcepathRef is used
sourcepathRef	specify the paths that contain the source files for Lint4j to analyze in terms of an Ant reference	Not set	Yes, unless sourcepath is used
classpath	specify the paths for all additional classes referenced by the source files. Several paths can be specified, separated by the ',' character, e.g. classpath="lib/one.jar,lib/two.jar". Classes specified here will not be analyzed.	Not set	No
classpathRef	specify the paths that contain the source files for Lint4j to analyze in terms of an Ant reference	Not set	No
packages	Analyze the classes in the specified packages. The names must be fully qualified, and separated by a comma only (e.g. no whitespace)	Not set	No
classes	Analyzes the given classes. The names must be fully qualified, and separated by a comma only (e.g. no whitespace)	Not set	No
sourcefiles	Analyzes the specified source or class files. The file names may be relative or absolute.	Not set	No
level	the minimum severity level for emitted warnings. Valid range is from 1 (error) to 5 (notice).	3	No
ignorePackages	the package names that should be skipped in the analysis.	Not set	No
exact	Emit only warnings of the same severity as specified by the level argument	false	No

The attributes sourcepath, classpath and sourcefiles are path-like structures, and can also be set via nested <sourcepath>, <classpath> and <sourcefiles> elements, respectively.

The task supports the nested attribute formatters to specify one or more formatters that transform the generated reports into text format.

Attribute	Description	Default	Required
formatters	specify one or more formatters that transform the generated reports into text format	Generated text output to System.out	No

A <formatters> element contains one or more <formatter> elements:

Attribute	Description	Default	Required
toFile	the file name the report is written to	System.out	No
type	the output format. The types "text" and "xml" are currently supported.	No	Yes

Examples

Here is a task snippet from the example ant file that checks the tomcat 5 code base. It checks all classes in org.apache and subpackages that can be found in the sourcepath, and resolving all types against the contents of classpath. The results will be formatted as text, with output going to the console and to the file "/tmp/tomcat5.out"

	
<target name="check-tomcat5" description="Perform checks on Tomcat 5">
  <lint4j ignorePackages="org.apache.tomcat.util.net.puretls,org.apache.coyote.tomcat3,org.apache.ajp.tomcat33"  packages="org.apache.*" level="${lint4j.level}" exact="${lint4j.exact}">
    <sourcepath>
	  <dirset dir="${tomcat5.src.path}">
		<include name="**/src/share" />
		<include name="**/src/java" />
		<exclude name="**/test/**" />
	  </dirset>
	  <pathelement path="${tomcat5.src.path}/jakarta-tomcat-connectors/util/java" />
	  <pathelement path="${tomcat5.src.path}/jakarta-tomcat-connectors/naming/src" />
	  <pathelement path="${tomcat5.src.path}/jakarta-tomcat-connectors/util/loader" />
	</sourcepath>
	<classpath>
	  <fileset dir="/var/tmp/tomcat5-deps/">
		<include name="**/*.jar" />
	  </fileset>
	</classpath>
    <formatters>
      <formatter type="text" />
      <formatter type="text" toFile="/tmp/tomcat5.out"/>
      <formatter type="xml" toFile="/tmp/tomcat5.xml"/>
    </formatters>
  </lint4j>
</target>

The section about setting Lint4j to audit Smart Ticket contains more tips to speed up the configuration of the Ant task.

Lint4j needs a lot of memory for large projects. If the lint4j Ant task runs out of memory, invoke Ant like this to increase the maximum memory size on Unix:

env ANT_OPTS="-Xmx300M" ant mygoal