What is it?
It is a library that allows the parameter names of non-private methods and constructors to be accessed at runtime. Normally this information is dropped by the compiler. In effect, methods like 'doSometing(mypkg.Person toMe)' currently look like 'doSomething(mypkg.Person ???)' to people using Java's reflection to inspect methods.
To date parameter name access has not been very useful to Java application developers, but with the advent of advanced scripting languages and web action frameworks for the JVM it is of increasing importance to be able to leverage a method's parameter names. Scripting languages like Groovy & JRuby, web action frameworks like Waffle and VRaptor (that verge on the tranparent) and the compelling Grails. SOAP and REST designs could also benefit.
ParaNamer allows you to generate and use parameter name info for versions of Java prior to JDK 7.0. Parameter name access was scheduled for JDK 6.0, bit slipped as the development team ran out of time to implement it. It seems unlikely that it will ship with JDK 7.0 either.
Paranamer is Open Source, and licensed as BSD. It is compatible with commercial/proprieatry, GPL, Apache use.
Accessing Parameter Name data
There is a method called 'lookupParameterNames' that returns an array of strings for a method or constructor.
Method method = Foo.class.getMethod(...);
Paranamer paranamer = new CachingParanamer();
String[] parameterNames = paranamer.lookupParameterNames(method)
The method throws a ParameterNamesNotFoundException if no parameter names are found.
Instead of handling that exception, you could determine if parameter name data is available, but first calling areParameterNamesAvailable().
ParaNamer does not have any runtime jar dependencies while looking up parameter info previously generated that's been zipped into a jar.
DefaultParanamer
DefaultParanamer tries to read parameter name data from an extra static field on the class. This field need to be added after compilation of the class, and before you put the resulting classes in a jar.
The static field essentially looks like -
private static final String __PARANAMER_DATA = "v1.0 \n"
+ "<init> \n"
+ "<init> com.foo.Bar bar \n"
+ "toString \n"
+ "setName java.lang.String,java.lang.String givenName,familyName \n";
+ "setDateOfBirth int,int,int day,month,year \n";
Clearly the method's source needs to be analysed and lines added per method to that __PARANAMER_DATA field. See below.
BytecodeReadingParanamer
If generating meta data for parameter names at compile time is not for you, try class BytecodeReadingParanamer as a runtime only solution. This uses a cut down forked and cut-down version of ASM to extract debug information from a class at runtime. As it happens this is the fallback implementation for CachingParanamer when DefaultParanamer reports that there is no meta data for a class.
CachingParanamer
CachingParanamer stores the results of each parameter name lookup, so that second and subsequent invocations will be far quicker.
Its also interesting to note that CachingParanamertries tries to use DefaultParanamer and BytecodeReadingParanamer. The latter is a fallback strategy if the former cannot find parameter name data.
Creating Parameter Name data and Adding it to .class files
Optional Generation of Parameter Name data with Ant
This for DefaultParanamer of course.
You need to download:
- latest paranamer jar
- latest paranamer-generator jar
- latest paranamer-ant jar
- latest qdox jar (1.8 or above)
<taskdef name="paranamer"
classname="com.thoughtworks.paranamer.ant.ParanamerGeneratorTask"/>
<paranamer sourceDirectory="src/java" outputDirectory="target/classes"/>
Classes are changed to have an extra static String member variable that contains the member functions and their parameter names. Be sure to zip them up in to you final jar.
Optional Generation of Parameter Name data with Maven 2
For Maven, it is simpler. Just add this to the
<build><plugins> section of your pom.xml:
<plugin>
<groupId>com.thoughtworks.paranamer</groupId>
<artifactId>paranamer-maven-plugin</artifactId>
<executions>
<execution>
<id>run</id> <!-- id is optional -->
<configuration>
<sourceDirectory>${project.build.sourceDirectory}</sourceDirectory>
<outputDirectory>${project.build.outputDirectory}</outputDirectory>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions> <dependencies> <!-- if some of parameter names you need to retain are held in pre-existing jars, they need to be added to the classpath -->
<dependency>
<groupId>some-artifact-group</groupId>
<artifactId>some-artifact</artifactId>
<version>1.0</version>
</dependency>
</dependencies>
</plugin>
The classes in the ultimate jar file will automatically be made with parameter name data.
Using Paranamer in your application without depending on Paranamer's jar
There are already too many jar's for day to day Java development
right? Simply consume the runtime paranamer jar into your project's jar using the Maven2 'shade' plugin.
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
<configuration>
<shadedArtifactId>artifact-shaded</shadedArtifactId>
<relocations>
<relocation>
<pattern>com.thoughtworks.paranamer</pattern>
<shadedPattern>com.yourcompany.yourapp.paranamer</shadedPattern>
</relocation>
</relocations>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
How Paranamer works
What if a parameter names changes?
The general answer to this question is that you should not ship something to third parties where they are going to hard-core your parameter names into their application. For you own in-house stuff, accessing parameter names is harmless. You should be able to ripple though the source code of even large applications, and change say "badSpeeldWord" to "badlySpelledWorld" if you need to.
In a later version we may store previous parameter names too. It won't be
be magic, you'll have to code the previous parameter names in your
source with a doclet tag. The lookup mechanism will change too.
It will likely leverage a doclet tag.
Paranamer's Future
ParaNamer will go away in the future when Java gets Reflection
access to Method parameter names. That should look like:
Method method = Foo.class.getMethod(....)
String[] parameterNames = method.getParameterNames();
But for now, we are thinking of the following directions :-
- Plugins for Intellij IDEA, Eclipse, NetBeans to make parameter name data as part of their compilation processes
- Storage and retrieval of previous parameter names
Projects using it
MandragoraOval - Object Validation Framework,
PicoContainer - Dependency Injection Framework,
PicoContainer Web-Remoting,
VRaptor - Web Framework,
Waffle - Web Framework
Releases
Release 1.4 - May 9 2009
Release 1.3 - Feb 22 2009
Release 1.2 - Feb 2 2009
Release 1.1.7 - Jan 20 2009
Release 1.1.6 - Dec 22 2008
Release 1.1.5 - Aug 14 2008
Release 1.1.4 - Jun 19 2008
Release 1.1.3 - May 16 2008
Release 1.1.2 - Mar 16 2008
Release 1.1.1 - Nov 28 2007
Release 1.1 - Oct 14 2007
Release 1.0.1 - Jul 07 2007
Release 1.0 - Jul 01 2007
Project Information
The unit tests for Paranamer illustrate some more way to use it: http://svn.paranamer.codehaus.org/paranamer/trunk/paranamer/src/test/com/thoughtworks/paranamer/ParanamerExampleTestCase.java
Developers, Maven 2 repository, lists, sites are detailed
here:
http://xircles.codehaus.org/projects/paranamer
Released Jar files here:
http://repository.codehaus.org/com/thoughtworks/paranamer/
Snapshot Jar files here:
http://snapshots.repository.codehaus.org/com/thoughtworks/paranamer/