README.md

Method Parameter Name Access for Java*

versions PRIOR TO Java 7.0 8.0

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(mypackage.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 transparent) 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 5.0 and above. Parameter name access was scheduled for JDK 6.0, but was cancelled at a late stage as the spec-lead suggested the development team ran out of time to implement it. It is sadly not shipping in JDK 7.0 either. Sun also had misgivings about the appropriateness of the this change to Java. It was felt that applications could end up depending on parameter names, and that they essentially became part of constructor/method signatures and could never be changed if you wanted to be backwards compatible. The view of the authors of Paranamer is that you should be aware that parameter names may change between releases, and code to not depend on them.

Paranamer is Open Source, and licensed as BSD, and first created in in July 2006. It is compatible with commercial/proprietary, GPL, BSD, and Apache (or any open/free source) use.

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 public 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 the following. You really do not need to know this unless your going to make something compatible with Paranamer:

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.

AdaptiveParanamer

Give it a list of Paranamer implementations to try in turn for parameter names. In its default constructor it has BytecodeReadingParanamer and DefaultParanamer in that order.

JavadocParanamer

Pulls its parameter names from a Javadoc zip/jar (named in the constructor). Courtesy of Sam Halliday

AnnotationParanamer takes a delegate paranamer instance as an optional constructor arg. This will allow constructors and methods to only partly leverage @Named, with other parameters having non-annotated parameter names (the via say DefaulParanamer or BytecodeReadingParanamer).

If you have an alternate annotation to @Named, then you can specify that in a subclass of AnnotationParanamer that overrides two methods isNamed and getNamedValue. Your overridden methods should do the equivalent of 'return an instance of Named' and return ((Named) ann).value(); respectively.

If you are using @Named from JSR 330, you will need it in your classpath of course. In Maven terms, Paranamer is built with the javax.atinject module as an optional dependency.

CachingParanamer

CachingParanamer stores the results of each parameter name lookup, so that second and subsequent invocations will be far quicker.

There's a subclass of CachingParanamer called CachingParanamer.WithoutWeakReferences. It does not use a WeakHashMap as an internal implementation. If you're great with profiling of applications under load, you might be able to justify use of this implementation for your particular app.

AdaptiveParanamer

AdaptiveParanamer is designed for using a series of Paranamer implementations together. The first supplied is asked if it can supply parameter name data for a constructor/method. If it cannot, then the next one is asked and so on. The default constructor for this uses DefaultParanamer with ByteCodeReadingParanamer as its contingency.

Feeding DefaultParanamer

Generating __PARANAMER_DATA with Ant

This for DefaultParanamer usage of course, as BytecodeReadingParanamer does not need it.

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.

Other Modules

paranamer-ant - Ant tasks

paranamer-maven-plugin - a Maven plugin (as shown above)

Paranamer's Future

The need for Paranamer will go away when JEP-118 lands as part of Java8. Despite that, we intend to maintain the library so that it continues to work.