net.sf.jode.bytecode
Class ClassPath

java.lang.Object
  net.sf.jode.bytecode.ClassPath

public class ClassPath
extends Object

A path in which class files are searched for. Class files can be loaded from several different locations, these locations can be:

• A local directory.
• A local jar or zip file
• A URL (unified resource location), pointing to a directory
• A URL pointing to a jar or zip file.
• A Jar URL (see JarURLConnection), useful if the jar file is not packed correctly.
• The reflection URL reflection:/. This is a special location, which fills the ClassInfo with the information from the java reflection API. Obviously it can't load any files nor the full bytecode. It only loads declarations of classes. If a security manager is present, it can only load public declarations.

We use standard java means to find a class file: package correspond to directories and the class file must have the .class extension. For example if the class path points to /home/java, the class java.lang.Object is loaded from /home/java/java/lang/Object.class. Of course you can write your own ClassPath.Locations that break this rule. A class path can have another ClassPath as fallback. If ClassInfo.loadInfo is called and the class isn't found the fallback ClassPath is searched instead. This repeats until there is no further fallback. The fallback is not used when listing classes or files. The main method for creating classes is getClassInfo(java.lang.String). The other available methods are useful to find other files in the ClassPath and to get a listing of all available files and classes. A ClassPath handles some IOExceptions and SecurityExceptions skipping the path that produced them.

Version:

1.1

Author:

Jochen Hoenicke

Nested Class Summary

static class

ClassPath.Location A location is a single component of the ClassPath.

Field Summary

static char

altPathSeparatorChar We need a different pathSeparatorChar, since ':' (used for UNIX systems) is also used as protocol separator in URLs.

Constructor Summary

ClassPath(ClassPath.Location[] locs)
Creates a new class path for the given path.

ClassPath(ClassPath.Location[] locs, ClassPath fallback)
Creates a new class path for the given path.

ClassPath(String path)
Creates a new class path for the given path.

ClassPath(String[] paths)
Creates a new class path for the given path.

ClassPath(String[] paths, ClassPath fallback)
Creates a new class path for the given path.

ClassPath(String path, ClassPath fallback)
Creates a new class path for the given path.

Method Summary

static ClassPath.Location	createLocation(String path) Creates a location for a given path component.
boolean	existsClass(String classname) Checks, if a class with the given name exists somewhere in this path.
boolean	existsFile(String filename) Checks, if a file with the given name exists somewhere in this path.
ClassInfo	getClassInfo(String classname) Creates a new class info for a class residing in this search path.
ClassInfo	getClassInfoFromStream(InputStream stream) Creates a new class info from an input stream containing the bytecode.
List<String>	getClassPath()
InputStream	getFile(String filename) Searches for a file in the class path.
boolean	isDirectory(String filename) Searches for a filename in the class path and tells if it is a directory.
boolean	isPackage(String fqn) Searches for a filename in the class path and tells if it is a package.
Enumeration	listClassesAndPackages(String packageName) Get a list of all classes and packages in the given package.
Enumeration	listFiles(String dirName) Get a list of all files in a given directory.
String	toString() Returns a string representation of this classpath.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

altPathSeparatorChar

public static final char altPathSeparatorChar

We need a different pathSeparatorChar, since ':' (used for UNIX systems) is also used as protocol separator in URLs.
We currently allow both pathSeparatorChar and altPathSeparatorChar and decide if it is a protocol separator by context. This doesn't always work, so use altPathSeparator, or better yet the ClassPath(String[]) or ClassPath(Location[]) constructors.

See Also:

Constant Field Values

Constructor Detail

ClassPath

public ClassPath(String[] paths,
                 ClassPath fallback)

Creates a new class path for the given path. See the class description for more information, which kind of paths are supported. When a class or a file is not found in the class path the fallback is used.

Parameters:

paths - An array of paths.

fallback - The fallback classpath.

ClassPath

public ClassPath(String[] paths)

Creates a new class path for the given path. See the class description for more information, which kind of paths are supported.

Parameters:

paths - An array of paths.

ClassPath

public ClassPath(ClassPath.Location[] locs,
                 ClassPath fallback)

Creates a new class path for the given path. When a class or a file is not found in the class path the fallback is used.

Parameters:

locs - An array of locations.

fallback - The fallback classpath.

ClassPath

public ClassPath(ClassPath.Location[] locs)

Creates a new class path for the given path.

Parameters:

locs - An array of locations.

ClassPath

public ClassPath(String path,
                 ClassPath fallback)

Creates a new class path for the given path. See the class description for more information, which kind of paths are supported.

Parameters:

path - One or more paths. They should be separated by the altPathSeparatorChar or pathSeparatorChar, but the latter is deprecated since it may give problems for UNIX machines.

See Also:

ClassPath(String[] paths)

ClassPath

public ClassPath(String path)

Creates a new class path for the given path. See the class description for more information, which kind of paths are supported.

Parameters:

path - One or more paths. They should be separated by the altPathSeparatorChar or pathSeparatorChar, but the latter is deprecated since it may give problems for UNIX machines.

See Also:

ClassPath(String[] paths)

Method Detail

createLocation

public static ClassPath.Location createLocation(String path)
                                         throws IOException,
                                                SecurityException

Creates a location for a given path component. See the class comment which path components are supported.

Parameters:

path - the path component.

Returns:

a location corresponding to the class.

Throws:

NullPointerException - if path is null.

IOException - if an io exception occured while accessing the path component.

SecurityException - if a security exception occured while accessing the path component.

getClassInfo

public ClassInfo getClassInfo(String classname)

Creates a new class info for a class residing in this search path. This doesn't load the class immediately, this is done by ClassInfo.loadInfo. It is no error if class doesn't exists.
ClassInfos are guaranteed to be unique, i.e. if you have two ClsssInfo objects loaded from the same class path with the same classname they will always be identical. The only exception is if you use setName() or getClassInfoFromStream() and explicitly overwrite a previous class.

Parameters:

classname - the dot-separated full qualified name of the class. For inner classes you must use the bytecode name with $, e.g. java.util.Map$Entry.

Throws:

IllegalArgumentException - if class name isn't valid.

getClassPath

public List<String> getClassPath()

getClassInfoFromStream

public ClassInfo getClassInfoFromStream(InputStream stream)
                                 throws IOException,
                                        ClassFormatException

Creates a new class info from an input stream containing the bytecode. This method is useful if you don't know the class name or if you have the class in an unusual location. The class is fully loaded (ClassInfo.ALL) when you use this method.
If a class with the same name was already created with getClassInfo() it will effectively be removed from the class path, although references to it may still exists elsewhere.

Parameters:

stream - the input stream containing the bytecode.

Returns:

the ClassInfo representing this class.

Throws:

IOException - if an io exception occurs.

ClassFormatException - if bytecode isn't valid.

existsClass

public boolean existsClass(String classname)

Checks, if a class with the given name exists somewhere in this path.

Parameters:

classname - the class name.

Throws:

IllegalArgumentException - if class name isn't valid.

existsFile

public boolean existsFile(String filename)

Checks, if a file with the given name exists somewhere in this path.

Parameters:

filename - the file name.

See Also:

existsClass(java.lang.String)

getFile

public InputStream getFile(String filename)
                    throws IOException

Searches for a file in the class path.

Parameters:

filename - the filename. The path components should be separated by "/".

Returns:

An InputStream for the file.

Throws:

IOException

isDirectory

public boolean isDirectory(String filename)

Searches for a filename in the class path and tells if it is a directory.

Parameters:

filename - the filename. The path components should be separated by "/".

Returns:

true, if filename exists and is a directory, false otherwise.

isPackage

public boolean isPackage(String fqn)

Searches for a filename in the class path and tells if it is a package. This is the same as isDirectory, but takes dot separated names.

Parameters:

fqn - the full qualified name. The components should be dot separated.

Returns:

true, if filename exists and is a package, false otherwise.

See Also:

isDirectory(java.lang.String)

listFiles

public Enumeration listFiles(String dirName)

Get a list of all files in a given directory.

Parameters:

dirName - the directory name. The path components must be separated by "/".

Returns:

An enumeration with all files/directories in the given directory. If dirName doesn't denote a directory it returns null.

listClassesAndPackages

public Enumeration listClassesAndPackages(String packageName)

Get a list of all classes and packages in the given package.

Parameters:

packageName - a dot-separated package name.

Returns:

An enumeration with all class/subpackages in the given package. If package doesn't denote a package it returns null.

toString

public String toString()

Returns a string representation of this classpath.

Overrides:

toString in class Object

Returns:

a string useful for debugging purposes.