com.thoughtworks.paranamer
Class JavadocParanamer

java.lang.Object
  extended by 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:-

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:-

Author:
Samuel Halliday, ThinkTank Maths Limited

Field Summary
 
Fields inherited from interface com.thoughtworks.paranamer.Paranamer
EMPTY_NAMES, NO_PARAMETER_NAMES_FOR_CLASS, NO_PARAMETER_NAMES_FOR_CLASS_AND_MEMBER, NO_PARAMETER_NAMES_LIST, PARAMETER_NAMES_FOUND
 
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
 int areParameterNamesAvailable(Class clazz, String constructorOrMethodName)
          Determine if the parameter names are available.
 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 -
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

areParameterNamesAvailable

public int areParameterNamesAvailable(Class clazz,
                                      String constructorOrMethodName)
Description copied from interface: Paranamer
Determine if the parameter names are available.

Known issues:

Use of this method is discouraged.

Specified by:
areParameterNamesAvailable in interface Paranamer
Parameters:
clazz - the name of the class to which the method or constructor belongs.
constructorOrMethodName - the base name of the Method or Constructor. If a request is being made for the constructor, this should be "<init>".
Returns:
An int encoding the parameter names availability.

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.
Returns:
A list of the parameter names.


Copyright © 2010. All Rights Reserved.