Debian Codegraph @

paranamer-distribution/src/site/content/index.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <title>Introduction</title>
5 </head>
6 <body>
7
8 <h1>What is it?</h1>
9 <p>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 '<span
10 style="font-family: monospace;">doSometing(mypkg.Person <strong>toMe</strong>)</span>'
11 currently look like '<span style="font-family: monospace;">doSomething(mypackage.Person
12 <strong>???</strong>)</span>' to people using Java's reflection to inspect methods.&nbsp; </p>
13 <p>To
14 date parameter name access has not been very useful to Java application developers, but
15 with the advent of advanced scripting languages and web action
16 frameworks for the JVM it is of increasing importance to be able to
17 leverage a method's parameter names. Scripting languages like <a
18 href="http://groovy.codehaus.org/">Groovy</a> &amp; <a
19 href="http://jruby.codehaus.org/">JRuby</a>, web action frameworks
20 like <a href="http://waffle.codehaus.org">Waffle</a> and <a href="#"
21 title="http://www.vraptor.org/">VRaptor</a> (that verge on the
22 transparent) and the compelling <a href="http://grails.codehaus.org/">Grails</a>. SOAP and REST designs could also benefit.</p>
23 <p>ParaNamer allows you to generate and use parameter name info for
24 versions of Java prior to JDK 5.0 and above.
25 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.</p>
26 <p>Paranamer is Open Source, and licensed as BSD. It is compatible with commercial/proprietary, GPL, Apache use.<br>
27 </p>
28 <h1>Accessing Parameter Name data</h1>
29 <p>There is a
30 method called <span class="code-object">'lookupParameterNames</span>' that returns an array of strings for a method or constructor.</p>
31 <div class="code">
32 <div class="codeHeader"><b>MySomethingOrOther.java</b></div>
33 <div class="codeContent">
34 <pre class="code-java">
35 Method method = Foo.class.getMethod(...);<br>
36 Paranamer paranamer = new DefaultParanamer();<br>
37 String[] parameterNames = paranamer.lookupParameterNames(method) // throws ParameterNamesNotFoundException if not found<br>
38 // or ...<br>
39 parameterNames = paranamer.lookupParameterNames(method, false) // will return null if not found
40 </pre>
41 </div>
42 </div>
43 </p>
44 <p>ParaNamer does not have any runtime jar dependencies while looking
45 up parameter info previously generated that's been zipped into a jar.</p>
46 <h2>DefaultParanamer</h2>
47 <p>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 zip the resulting classes in a jar. </p>
48 <p>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:</p>
49 <div class="code">
50 <div class="codeContent">
51 <pre class="code-java"> private static final String __PARANAMER_DATA = "v1.0 \n"<br> + "&lt;init&gt; com.example.PeopleService peopleService \n"<br> + "setName java.lang.String,java.lang.String givenName,familyName \n";<br> + "setDateOfBirth int,int,int day,month,year \n";</pre></div>
52 </div>
53 <p>Clearly the method's source needs to be analysed and lines added per
54 method to that __PARANAMER_DATA field.&nbsp;&nbsp; See below.</p>
55 <h2>BytecodeReadingParanamer</h2>
56 <p>If generating meta data for parameter names at compile time
57 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.</p>
58 <p>As it happens Groovy classes loaded through <a href="http://groovy.codehaus.org/Embedding+Groovy">parseClass</a> are compatible with Paranamer. That said, <a href="http://groovy.codehaus.org/api/groovy/lang/GroovyClassLoader.html">GroovyClassLoader</a> does not make the bytecode available by default after loading. Take a look at the way this was <a href="http://github.com/jbehave/jbehave-core/blob/master/jbehave-groovy/src/main/java/org/jbehave/core/configuration/groovy/BytecodeGroovyClassLoader.java">solved by the JBehave team</a>.</p>
59 <h2>AnnotationParanamer</h2>
60 <p>AnnotationParanamer uses the @Named annotation from JSR 330 and extracts names pertinent to parameters from that.</p>
61 <div class="code">
62 <div class="codeContent">
63 <pre class="code-java">
64 public static class Something {
65 public void doSomething(@Named("usedName") String ignoredName) {
66 }
67 }
68 </pre></div>
69 </div>
70 <p>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).</p>
71 <p>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 ann instanceof Named;' and 'return ((Named) ann).value();' respectively.</p>
72 <p>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.</p>
73 <h2>CachingParanamer</h2>
74 <p>CachingParanamer stores the results of each parameter name lookup, so that second and subsequent invocations will be far quicker. Pass in another Paranamer implementation via constructor so that the CachingParanamer can defer to it for cache misses.</p>
75 <h2>AdaptiveParanamer</h2>
76 <p>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.</p>
77 <h1>Generating Parameter Name Data for DefaultParanamer</h1>
78 <p>This is only needed for DefaultParanamer as BytecodeReadingParanamer relies on the presence of a debug table in bytecode. It is also only a solution for Java source, as Groovy source is not compatible with the underlying technologies.</p>
79 <h2>With Ant<br>
80 </h2>
81 <p>You need to download:</p>
82 <ul>
83 <li><a
84 href="http://repository.codehaus.org/com/thoughtworks/paranamer/paranamer/">latest
85 paranamer jar</a></li>
86 <li><a
87 href="http://repository.codehaus.org/com/thoughtworks/paranamer/paranamer-generator/">latest
88 paranamer-generator jar</a></li>
89 <li><a
90 href="http://repository.codehaus.org/com/thoughtworks/paranamer/paranamer-ant/">latest
91 paranamer-ant jar</a></li>
92 <li><a href="http://repo1.maven.org/maven2/qdox/qdox/">latest
93 qdox jar</a> (1.8 or above)</li>
94 </ul>
95 and declare in your Ant script the following after &lt;javac/&gt;
96 (remember to add to the taskdef classpath all the above jars):
97 <br><br>
98 <div class="code">
99 <div class="codeContent"><pre class="code-xml"> &lt;taskdef name="paranamer" <br> classname="com.thoughtworks.paranamer.ant.ParanamerGeneratorTask"/&gt;<br> &lt;paranamer sourceDirectory="src/java" outputDirectory="target/classes"/&gt;<br></pre>
100 </div>
101 </div>
102 <p>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.<br>
103 </p>
104 <h2>With Maven2 or Maven3</h2>
105 For Maven, configuration is simpler. Just add this to the build/plugins section of your pom.xml:
106 <br>
107 <br>
108 <div class="code">
109 <div class="codeContent"><pre style="margin-left: 16px;">&lt;plugin&gt;<br>&nbsp;&nbsp;&nbsp; &lt;groupId&gt;com.thoughtworks.paranamer&lt;/groupId&gt;<br>&nbsp;&nbsp;&nbsp; &lt;artifactId&gt;paranamer-maven-plugin&lt;/artifactId&gt;<br>&nbsp;&nbsp; &nbsp;&lt;executions&gt;<br>&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;execution&gt;<br>&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;id&gt;run&lt;/id&gt; &lt;!-- id is optional --&gt;<br>&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;configuration&gt;<br>&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;sourceDirectory&gt;${project.build.sourceDirectory}&lt;/sourceDirectory&gt;<br>&nbsp; &nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;outputDirectory&gt;${project.build.outputDirectory}&lt;/outputDirectory&gt;<br>&nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;/configuration&gt;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;<br> &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;goals&gt;<br>&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;goal&gt;generate&lt;/goal&gt;<br>&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;/goals&gt;<br>&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;/execution&gt;<br>&nbsp;&nbsp;&nbsp; &lt;/executions&gt;
110 &nbsp;&nbsp;&nbsp; &lt;dependencies&gt;
111 &lt;!-- if some of parameter names you need to retain are held in pre-existing jars, they need to be added to the classpath --&gt;<br> &lt;dependency&gt;<br> &lt;groupId&gt;some-artifact-group&lt;/groupId&gt;<br> &lt;artifactId&gt;some-artifact&lt;/artifactId&gt;<br> &lt;version&gt;1.0&lt;/version&gt;<br> &lt;/dependency&gt;<br> &lt;/dependencies&gt;<br>&lt;/plugin&gt;</pre>
112 </div>
113 </div>
114 <br>
115 The classes in the ultimate jar file will automatically be made with parameter name data.<br>
116 <h2>Using Paranamer in your application without depending on Paranamer's jar</h2>
117 <p>Many people feel there are already too many jars required for day to day Java development. If you feel this way, simply consume the main paranamer jar into your project's jar using the <a href="http://maven.apache.org/plugins/maven-shade-plugin/">Maven2 shade plugin</a>.<br>
118 </p>
119 <div class="code">
120 <div class="codeHeader"><b>Put in your POM.xml file</b></div>
121 <div class="codeContent"><pre class="code-java"><span
122 class="code-object"> &lt;build&gt;<br> &lt;plugins&gt;<br> &lt;plugin&gt;<br> &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;<br> &lt;artifactId&gt;maven-shade-plugin&lt;/artifactId&gt;<br> &lt;executions&gt;<br> &lt;execution&gt;<br> &lt;phase&gt;package&lt;/phase&gt;<br> &lt;goals&gt;<br> &lt;goal&gt;shade&lt;/goal&gt;<br> &lt;/goals&gt;<br> &lt;configuration&gt;<br> &lt;shadedArtifactId&gt;artifact-shaded&lt;/shadedArtifactId&gt;<br> &lt;relocations&gt;<br> &lt;relocation&gt;<br> &lt;pattern&gt;com.thoughtworks.paranamer&lt;/pattern&gt;<br> &lt;shadedPattern&gt;com.yourcompany.yourapp.paranamer&lt;/shadedPattern&gt;<br> &lt;/relocation&gt;<br> &lt;/relocations&gt;<br> &lt;/configuration&gt;<br> &lt;/execution&gt;<br> &lt;/executions&gt;<br> &lt;/plugin&gt;<br> &lt;/plugins&gt;<br> &lt;/build&gt;<br> </span><br></pre>
123 </div>
124 </div>
125
126 <h1>Frequently Asked Questions</h1>
127
128 <h2>What if a parameter names changes?</h2>
129 <p>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 &quot;badSpeeldWord&quot; to &quot;badlySpelledWorld&quot; if you need to.</p>
130 <p>In a later version we may store previous parameter names too. It won't be
131 be magic, you'll have to code the previous parameter names in your
132 source with a doclet tag. The lookup mechanism will change too.
133 It will likely leverage a doclet tag.<br>
134 </p>
135 <h1>Paranamer's Future</h1>
136 <p>Paranamer will go away in the future when Java gets Reflection
137 access to Method parameter names. That should look like:<br>
138 </p>
139 <div class="code">
140 <div class="codeContent"><pre style="margin-left: 16px;"
141 class="code-java">Method method = Foo.class.getMethod(....)<br>String[] parameterNames = method.getParameterNames();<br></pre>
142 </div>
143 <p>But for now, we are thinking of the following directions :-</p>
144 <ol>
145 <li>Plugins for Intellij IDEA, Eclipse, NetBeans to make
146 parameter name data as part of their compilation processes</li>
147 <li>Storage and retrieval of previous parameter names</li>
148 </ol>
149 </div>
150
151 <h1>Projects using it</h1>
152 <a href="http://mandragora.sourceforge.net">Mandragora</a><br>
153 <a href="http://oval.sourceforge.net/">Oval - Object Validation Framework</a>,<br>
154 <a href="http://picocontainer.org/">PicoContainer - Dependency Injection Container</a>,<br>
155 <a href="http://picocontainer.org/web/remoting">PicoContainer Web-Remoting</a>,<br>
156 <a href="http://vraptor.org/">VRaptor - Web Framework</a>,<br>
157 <a href="http://waffle.codehaus.org/">Waffle - Web Framework</a><br>
158 <a href="http://jbehave.codehaus.org/">JBehave - BDD tests for Java</a><br>
159
160 <h1>Debug Releases</h1>
161 <p>Release 2.2 and onwards have a debug release associated with them. These are compiled against the full ASM jar and require it as a transitive dependency. The non debug releases compile against a cut down fork of the bytecode reading ASM. This advice only affects the BytecodeReadingParanamer implementation.</p>
162
163 <h1>Releases</h1>
164 <p>Release 2.3 - Oct 19 2010</p>
165 <p>Release 2.2.1 - Jun 22 2010</p>
166 <p>Release 2.2 - Jan 2 2010 (all after this are JDK 5.0 and above only)</p>
167 <p>Release 2.1 - Sep 6 2009 (last version that is compatible with JDK 1.4)</p>
168 <p>Release 2.0 - Jul 10 2009</p>
169 <p>Release 1.5 - May 19 2009</p>
170 <p>Release 1.4 - May 9 2009</p>
171 <p>Release 1.3 - Feb 22 2009</p>
172 <p>Release 1.2 - Feb 2 2009</p>
173 <p>Release 1.1.7 - Jan 20 2009</p>
174 <p>Release 1.1.6 - Dec 22 2008</p>
175 <p>Release 1.1.5 - Aug 14 2008</p>
176 <p>Release 1.1.4 - Jun 19 2008</p>
177 <p>Release 1.1.3 - May 16 2008</p>
178 <p>Release 1.1.2 - Mar 16 2008</p>
179 <p>Release 1.1.1 - Nov 28 2007</p>
180 <p>Release 1.1 - Oct 14 2007</p>
181 <p>Release 1.0.1 - Jul 07 2007</p>
182 <p>Release 1.0 - Jul 01 2007</p>
183
184 <h1>Project Information</h1>
185 <p>The unit tests for Paranamer illustrate some more way to use it: <a href="https://github.com/paul-hammant/paranamer/tree/master/paranamer/src/test/com/thoughtworks/paranamer">https://github.com/paul-hammant/paranamer/tree/master/paranamer/src/test/com/thoughtworks/paranamer</a>
186 </p>
187 <p>Developers, Maven 2 repository, lists, sites are detailed
188 here:<br>
189 &nbsp;&nbsp;&nbsp;<a
190 href="http://xircles.codehaus.org/projects/paranamer">http://xircles.codehaus.org/projects/paranamer</a><br>
191 Latest Released Jar file here (auto-download): <br>
192 &nbsp;&nbsp;&nbsp;<a
193 href="https://nexus.codehaus.org/service/local/artifact/maven/redirect?r=releases&g=com.thoughtworks.paranamer&a=paranamer&v=2.3">https://nexus.codehaus.org/service/local/artifact/maven/redirect?r=releases&g=com.thoughtworks.paranamer&a=paranamer&v=2.3</a>
194 <br>
195 </p>
196 </body>
197 </html>