com.thoughtworks.paranamer
Class JavadocParanamer

java.lang.Object
  com.thoughtworks.paranamer.JavadocParanamer

All Implemented Interfaces:

Paranamer

public class JavadocParanamer
extends Object
implements Paranamer

Implementation of Paranamer which can access Javadocs at runtime to extract parameter names of methods. Works with:-

• Javadoc in zip file
• Javadoc in directory
• Javadoc at remote URL

Future implementations may be able to take multiple sources, but this version must be instantiated with the correct location of the Javadocs for the package you wish to extract the parameter names. Note that if a zip archive contains multiple "package-list" files, the first one will be used to index the packages which may be queried.

Note that this does not perform any caching of entries (except what it finds in the package-list file, which is very lightweight)... every lookup will involve a disc hit. If you want to speed up performance, use a CachingParanamer.

Implementation note: the constructors of this implementation let the client know if I/O problems will stop the recovery of parameter names. It might be preferable to suppress exceptions and simply return NO_PARAMETER_NAMES_LIST.

TODO: example use code

Known issues:-

• Only tested with Javadoc 1.3 - 1.6
• Doesn't handle methods that declare the generic type as a parameter (rare use case)
• Some "erased" generic methods fail, e.g. File.compareTo(File), which is erased to File.compareTo(Object).
• URL implementation is really slow
• Doesn't support nested classes (due to limitations in the Java 1.4 reflection API)

Author:

Samuel Halliday, ThinkTank Maths Limited

Field Summary

Fields inherited from interface com.thoughtworks.paranamer.Paranamer

EMPTY_NAMES

Constructor Summary

JavadocParanamer(File archiveOrDirectory)
Construct a Javadoc reading implementation of Paranamer using a local directory or zip archive as a source.

JavadocParanamer(URL url)

Method Summary

String[]	lookupParameterNames(AccessibleObject methodOrConstructor) Lookup the parameter names of a given method.
String[]	lookupParameterNames(AccessibleObject methodOrConstructor, boolean throwExceptionIfMissing) Lookup the parameter names of a given method.

Methods inherited from class java.lang.Object

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

Constructor Detail

JavadocParanamer

public JavadocParanamer(File archiveOrDirectory)
                 throws IOException

Construct a Javadoc reading implementation of Paranamer using a local directory or zip archive as a source.

Parameters:

archiveOrDirectory - either a zip archive of Javadocs or the base directory of Javadocs.

Throws:

IOException - if there was an error when reading from either the archive or the package-list file.

FileNotFoundException - if the archive, directory or package-list file does not exist.

NullPointerException - if any parameter is null

IllegalArgumentException - If the given parameter is not a file or directory or if it is a file but not a javadoc zip archive.

JavadocParanamer

public JavadocParanamer(URL url)
                 throws IOException

Parameters:

url - The URL of the JavaDoc

Throws:

IOException - if there was a problem connecting to the remote Javadocs

FileNotFoundException - if the url does not have a /package-list

NullPointerException - if any parameter is null

Method Detail

lookupParameterNames

public String[] lookupParameterNames(AccessibleObject methodOrConstructor)

Description copied from interface: Paranamer

Lookup the parameter names of a given method.

Specified by:

lookupParameterNames in interface Paranamer

Parameters:

methodOrConstructor - the Method or Constructor for which the parameter names are looked up.

Returns:

A list of the parameter names.

lookupParameterNames

public String[] lookupParameterNames(AccessibleObject methodOrConstructor,
                                     boolean throwExceptionIfMissing)

Description copied from interface: Paranamer

Lookup the parameter names of a given method.

Specified by:

lookupParameterNames in interface Paranamer

Parameters:

methodOrConstructor - the Method or Constructor for which the parameter names are looked up.

throwExceptionIfMissing - whether to throw an exception if no Paranamer data found (versus return null).

Returns:

A list of the parameter names.