| 1 |
/* |
| 2 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
| 3 |
* |
| 4 |
* Copyright (c) 2010-2011 Oracle and/or its affiliates. All rights reserved. |
| 5 |
* |
| 6 |
* The contents of this file are subject to the terms of either the GNU |
| 7 |
* General Public License Version 2 only ("GPL") or the Common Development |
| 8 |
* and Distribution License("CDDL") (collectively, the "License"). You |
| 9 |
* may not use this file except in compliance with the License. You can |
| 10 |
* obtain a copy of the License at |
| 11 |
* http://glassfish.java.net/public/CDDL+GPL_1_1.html |
| 12 |
* or packager/legal/LICENSE.txt. See the License for the specific |
| 13 |
* language governing permissions and limitations under the License. |
| 14 |
* |
| 15 |
* When distributing the software, include this License Header Notice in each |
| 16 |
* file and include the License file at packager/legal/LICENSE.txt. |
| 17 |
* |
| 18 |
* GPL Classpath Exception: |
| 19 |
* Oracle designates this particular file as subject to the "Classpath" |
| 20 |
* exception as provided by Oracle in the GPL Version 2 section of the License |
| 21 |
* file that accompanied this code. |
| 22 |
* |
| 23 |
* Modifications: |
| 24 |
* If applicable, add the following below the License Header, with the fields |
| 25 |
* enclosed by brackets [] replaced by your own identifying information: |
| 26 |
* "Portions Copyright [year] [name of copyright owner]" |
| 27 |
* |
| 28 |
* Contributor(s): |
| 29 |
* If you wish your version of this file to be governed by only the CDDL or |
| 30 |
* only the GPL Version 2, indicate your decision by adding "[Contributor] |
| 31 |
* elects to include this software in this distribution under the [CDDL or GPL |
| 32 |
* Version 2] license." If you don't indicate a single choice of license, a |
| 33 |
* recipient has the option to distribute your version of this file under |
| 34 |
* either the CDDL, the GPL Version 2 or to extend the choice of license to |
| 35 |
* its licensees as provided above. However, if you add GPL Version 2 code |
| 36 |
* and therefore, elected the GPL Version 2 license, then the option applies |
| 37 |
* only if the new code is made subject to such option by the copyright |
| 38 |
* holder. |
| 39 |
*/ |
| 40 |
package com.sun.jersey.wadl.resourcedoc; |
| 41 |
|
| 42 |
import java.io.BufferedOutputStream; |
| 43 |
import java.io.File; |
| 44 |
import java.io.FileOutputStream; |
| 45 |
import java.io.OutputStream; |
| 46 |
import java.io.StringWriter; |
| 47 |
import java.lang.reflect.Array; |
| 48 |
import java.lang.reflect.Field; |
| 49 |
import java.net.MalformedURLException; |
| 50 |
import java.net.URL; |
| 51 |
import java.net.URLClassLoader; |
| 52 |
import java.util.ArrayList; |
| 53 |
import java.util.Arrays; |
| 54 |
import java.util.Collection; |
| 55 |
import java.util.HashMap; |
| 56 |
import java.util.Iterator; |
| 57 |
import java.util.List; |
| 58 |
import java.util.Map; |
| 59 |
import java.util.Map.Entry; |
| 60 |
import java.util.logging.Level; |
| 61 |
import java.util.logging.Logger; |
| 62 |
import java.util.regex.Matcher; |
| 63 |
import java.util.regex.Pattern; |
| 64 |
|
| 65 |
import javax.xml.bind.JAXBContext; |
| 66 |
import javax.xml.bind.Marshaller; |
| 67 |
import javax.xml.namespace.QName; |
| 68 |
|
| 69 |
import org.apache.xml.serialize.OutputFormat; |
| 70 |
import org.apache.xml.serialize.XMLSerializer; |
| 71 |
|
| 72 |
import com.sun.javadoc.AnnotationDesc; |
| 73 |
import com.sun.javadoc.ClassDoc; |
| 74 |
import com.sun.javadoc.DocErrorReporter; |
| 75 |
import com.sun.javadoc.MemberDoc; |
| 76 |
import com.sun.javadoc.MethodDoc; |
| 77 |
import com.sun.javadoc.ParamTag; |
| 78 |
import com.sun.javadoc.Parameter; |
| 79 |
import com.sun.javadoc.RootDoc; |
| 80 |
import com.sun.javadoc.SeeTag; |
| 81 |
import com.sun.javadoc.Tag; |
| 82 |
import com.sun.javadoc.AnnotationDesc.ElementValuePair; |
| 83 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.AnnotationDocType; |
| 84 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.ClassDocType; |
| 85 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.MethodDocType; |
| 86 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.NamedValueType; |
| 87 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.ParamDocType; |
| 88 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.RepresentationDocType; |
| 89 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.RequestDocType; |
| 90 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.ResourceDocType; |
| 91 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.ResponseDocType; |
| 92 |
import com.sun.jersey.server.wadl.generators.resourcedoc.model.WadlParamType; |
| 93 |
|
| 94 |
/** |
| 95 |
* This doclet creates a resourcedoc xml file. The ResourceDoc file contains the javadoc documentation |
| 96 |
* of resource classes, so that this can be used for extending generated wadl with useful |
| 97 |
* documentation.<br> |
| 98 |
* Created on: Jun 7, 2008<br> |
| 99 |
* |
| 100 |
* @author <a href="mailto:[email protected]">Martin Grotzke</a> |
| 101 |
* @version $Id$ |
| 102 |
*/ |
| 103 |
public class ResourceDoclet { |
| 104 |
|
| 105 |
private static final Pattern PATTERN_RESPONSE_REPRESENATION = Pattern.compile( "@response\\.representation\\.([\\d]+)\\..*" ); |
| 106 |
private static final String OPTION_OUTPUT = "-output"; |
| 107 |
private static final String OPTION_CLASSPATH = "-classpath"; |
| 108 |
private static final String OPTION_DOC_PROCESSORS = "-processors"; |
| 109 |
|
| 110 |
private static final Logger LOG = Logger.getLogger( ResourceDoclet.class |
| 111 |
.getName() ); |
| 112 |
|
| 113 |
/** |
| 114 |
* Start the doclet. |
| 115 |
* |
| 116 |
* @param root |
| 117 |
* @return true if no exception is thrown |
| 118 |
*/ |
| 119 |
public static boolean start( RootDoc root ) { |
| 120 |
final String output = getOptionArg( root.options(), OPTION_OUTPUT ); |
| 121 |
|
| 122 |
final String classpath = getOptionArg( root.options(), OPTION_CLASSPATH ); |
| 123 |
// LOG.info( "Have classpath: " + classpath ); |
| 124 |
final String[] classpathElements = classpath.split( ":" ); |
| 125 |
|
| 126 |
final ClassLoader cl = Thread.currentThread().getContextClassLoader(); |
| 127 |
final ClassLoader ncl = new Loader( classpathElements, |
| 128 |
ResourceDoclet.class.getClassLoader() ); |
| 129 |
Thread.currentThread().setContextClassLoader( ncl ); |
| 130 |
|
| 131 |
|
| 132 |
final String docProcessorOption = getOptionArg( root.options(), OPTION_DOC_PROCESSORS ); |
| 133 |
final String[] docProcessors = docProcessorOption != null ? docProcessorOption.split( ":" ) : null; |
| 134 |
final DocProcessorWrapper docProcessor = new DocProcessorWrapper(); |
| 135 |
try { |
| 136 |
if ( docProcessors != null && docProcessors.length > 0 ) { |
| 137 |
final Class<?> clazz = Class.forName( docProcessors[0], true, Thread.currentThread().getContextClassLoader() ); |
| 138 |
final Class<? extends DocProcessor> dpClazz = clazz.asSubclass( DocProcessor.class ); |
| 139 |
docProcessor.add( dpClazz.newInstance() ); |
| 140 |
} |
| 141 |
} catch ( Exception e ) { |
| 142 |
LOG.log( Level.SEVERE, "Could not load docProcessors " + docProcessorOption, e ); |
| 143 |
} |
| 144 |
|
| 145 |
try { |
| 146 |
final ResourceDocType result = new ResourceDocType(); |
| 147 |
|
| 148 |
final ClassDoc[] classes = root.classes(); |
| 149 |
for ( ClassDoc classDoc : classes ) { |
| 150 |
LOG.fine( "Writing class " + classDoc.qualifiedTypeName() ); |
| 151 |
final ClassDocType classDocType = new ClassDocType(); |
| 152 |
classDocType.setClassName( classDoc.qualifiedTypeName() ); |
| 153 |
classDocType.setCommentText( classDoc.commentText() ); |
| 154 |
docProcessor.processClassDoc( classDoc, classDocType ); |
| 155 |
|
| 156 |
for ( MethodDoc methodDoc : classDoc.methods() ) { |
| 157 |
|
| 158 |
final MethodDocType methodDocType = new MethodDocType(); |
| 159 |
methodDocType.setMethodName( methodDoc.name() ); |
| 160 |
methodDocType.setCommentText( methodDoc.commentText() ); |
| 161 |
docProcessor.processMethodDoc( methodDoc, methodDocType ); |
| 162 |
|
| 163 |
addParamDocs( methodDoc, methodDocType, docProcessor ); |
| 164 |
|
| 165 |
addRequestRepresentationDoc( methodDoc, methodDocType ); |
| 166 |
|
| 167 |
addResponseDoc( methodDoc, methodDocType ); |
| 168 |
|
| 169 |
classDocType.getMethodDocs().add( methodDocType ); |
| 170 |
} |
| 171 |
|
| 172 |
result.getDocs().add( classDocType ); |
| 173 |
} |
| 174 |
|
| 175 |
try { |
| 176 |
final Class<?>[] clazzes = getJAXBContextClasses( result, docProcessor ); |
| 177 |
final JAXBContext c = JAXBContext.newInstance( clazzes ); |
| 178 |
final Marshaller m = c.createMarshaller(); |
| 179 |
m.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, true ); |
| 180 |
final OutputStream out = new BufferedOutputStream( new FileOutputStream( output ) ); |
| 181 |
|
| 182 |
|
| 183 |
final String[] cdataElements = getCDataElements( docProcessor ); |
| 184 |
final XMLSerializer serializer = getXMLSerializer( out, cdataElements ); |
| 185 |
|
| 186 |
m.marshal( result, serializer ); |
| 187 |
out.close(); |
| 188 |
|
| 189 |
LOG.info( "Wrote " + output ); |
| 190 |
|
| 191 |
} catch (Exception e) { |
| 192 |
LOG.log( Level.SEVERE, "Could not serialize ResourceDoc.", e ); |
| 193 |
return false; |
| 194 |
} |
| 195 |
} finally { |
| 196 |
Thread.currentThread().setContextClassLoader( cl ); |
| 197 |
} |
| 198 |
|
| 199 |
return true; |
| 200 |
} |
| 201 |
|
| 202 |
private static String[] getCDataElements( DocProcessor docProcessor ) { |
| 203 |
final String[] original = new String[] { "ns1^commentText", "ns2^commentText", "^commentText" }; |
| 204 |
if ( docProcessor == null ) { |
| 205 |
return original; |
| 206 |
} |
| 207 |
else { |
| 208 |
final String[] cdataElements = docProcessor.getCDataElements(); |
| 209 |
if ( cdataElements == null || cdataElements.length == 0 ) { |
| 210 |
return original; |
| 211 |
} |
| 212 |
else { |
| 213 |
|
| 214 |
final String[] result = copyOf( original, original.length + cdataElements.length ); |
| 215 |
for ( int i = 0; i < cdataElements.length; i++ ) { |
| 216 |
result[ original.length + i ] = cdataElements[i]; |
| 217 |
} |
| 218 |
return result; |
| 219 |
} |
| 220 |
} |
| 221 |
} |
| 222 |
|
| 223 |
@SuppressWarnings("unchecked") |
| 224 |
private static <T,U> T[] copyOf( U[] original, int newLength ) { |
| 225 |
final T[] copy = ((Object)original.getClass() == (Object)Object[].class) |
| 226 |
? (T[]) new Object[newLength] |
| 227 |
: (T[]) Array.newInstance(original.getClass().getComponentType(), newLength); |
| 228 |
System.arraycopy(original, 0, copy, 0, |
| 229 |
Math.min(original.length, newLength)); |
| 230 |
return copy; |
| 231 |
} |
| 232 |
|
| 233 |
private static Class<?>[] getJAXBContextClasses( |
| 234 |
final ResourceDocType result, DocProcessor docProcessor ) { |
| 235 |
final Class<?>[] clazzes; |
| 236 |
if ( docProcessor == null ) { |
| 237 |
clazzes = new Class<?>[1]; |
| 238 |
} |
| 239 |
else { |
| 240 |
final Class<?>[] requiredJaxbContextClasses = docProcessor.getRequiredJaxbContextClasses(); |
| 241 |
if ( requiredJaxbContextClasses != null ) { |
| 242 |
clazzes = new Class<?>[1 + requiredJaxbContextClasses.length ]; |
| 243 |
for ( int i = 0; i < requiredJaxbContextClasses.length; i++ ) { |
| 244 |
clazzes[i + 1] = requiredJaxbContextClasses[i]; |
| 245 |
} |
| 246 |
} |
| 247 |
else { |
| 248 |
clazzes = new Class<?>[1]; |
| 249 |
} |
| 250 |
} |
| 251 |
clazzes[0] = result.getClass(); |
| 252 |
return clazzes; |
| 253 |
} |
| 254 |
|
| 255 |
private static XMLSerializer getXMLSerializer( OutputStream os, String[] cdataElements ) throws InstantiationException, IllegalAccessException, ClassNotFoundException { |
| 256 |
// configure an OutputFormat to handle CDATA |
| 257 |
OutputFormat of = new OutputFormat(); |
| 258 |
|
| 259 |
// specify which of your elements you want to be handled as CDATA. |
| 260 |
// The use of the '^' between the namespaceURI and the localname |
| 261 |
// seems to be an implementation detail of the xerces code. |
| 262 |
// When processing xml that doesn't use namespaces, simply omit the |
| 263 |
// namespace prefix as shown in the third CDataElement below. |
| 264 |
of.setCDataElements( cdataElements ); |
| 265 |
|
| 266 |
// set any other options you'd like |
| 267 |
of.setPreserveSpace(true); |
| 268 |
of.setIndenting(true); |
| 269 |
|
| 270 |
// create the serializer |
| 271 |
XMLSerializer serializer = new XMLSerializer(of); |
| 272 |
|
| 273 |
serializer.setOutputByteStream( os ); |
| 274 |
|
| 275 |
return serializer; |
| 276 |
} |
| 277 |
|
| 278 |
private static void addResponseDoc( MethodDoc methodDoc, |
| 279 |
final MethodDocType methodDocType ) { |
| 280 |
|
| 281 |
final ResponseDocType responseDoc = new ResponseDocType(); |
| 282 |
|
| 283 |
final Tag returnTag = getSingleTagOrNull( methodDoc, "return" ); |
| 284 |
if ( returnTag != null ) { |
| 285 |
responseDoc.setReturnDoc( returnTag.text() ); |
| 286 |
} |
| 287 |
|
| 288 |
final Tag[] responseParamTags = methodDoc.tags( "response.param" ); |
| 289 |
for ( Tag responseParamTag : responseParamTags ) { |
| 290 |
// LOG.info( "Have responseparam tag: " + print( responseParamTag ) ); |
| 291 |
final WadlParamType wadlParam = new WadlParamType(); |
| 292 |
for ( Tag inlineTag : responseParamTag.inlineTags() ) { |
| 293 |
final String tagName = inlineTag.name(); |
| 294 |
final String tagText = inlineTag.text(); |
| 295 |
/* skip empty tags |
| 296 |
*/ |
| 297 |
if ( isEmpty( tagText ) ) { |
| 298 |
if ( LOG.isLoggable( Level.FINE ) ) { |
| 299 |
LOG.fine( "Skipping empty inline tag of @response.param in method " + |
| 300 |
methodDoc.qualifiedName() + ": " + tagName ); |
| 301 |
} |
| 302 |
continue; |
| 303 |
} |
| 304 |
if ( "@name".equals( tagName ) ) { |
| 305 |
wadlParam.setName( tagText ); |
| 306 |
} |
| 307 |
else if ( "@style".equals( tagName ) ) { |
| 308 |
wadlParam.setStyle( tagText ); |
| 309 |
} |
| 310 |
else if ( "@type".equals( tagName ) ) { |
| 311 |
wadlParam.setType( QName.valueOf( tagText ) ); |
| 312 |
} |
| 313 |
else if ( "@doc".equals( tagName ) ) { |
| 314 |
wadlParam.setDoc( tagText ); |
| 315 |
} |
| 316 |
else { |
| 317 |
LOG.warning( "Unknown inline tag of @response.param in method " + |
| 318 |
methodDoc.qualifiedName() + ": " + tagName + |
| 319 |
" (value: " + tagText + ")" ); |
| 320 |
} |
| 321 |
} |
| 322 |
responseDoc.getWadlParams().add( wadlParam ); |
| 323 |
} |
| 324 |
|
| 325 |
final Map<String, List<Tag>> tagsByStatus = getResponseRepresentationTags( methodDoc ); |
| 326 |
for ( Entry<String, List<Tag>> entry : tagsByStatus.entrySet() ) { |
| 327 |
final RepresentationDocType representationDoc = new RepresentationDocType(); |
| 328 |
representationDoc.setStatus( Long.valueOf( entry.getKey() ) ); |
| 329 |
for ( Tag tag : entry.getValue() ) { |
| 330 |
if ( tag.name().endsWith( ".qname" ) ) { |
| 331 |
representationDoc.setElement( QName.valueOf( tag.text() ) ); |
| 332 |
} |
| 333 |
else if ( tag.name().endsWith( ".mediaType" ) ) { |
| 334 |
representationDoc.setMediaType( tag.text() ); |
| 335 |
} |
| 336 |
else if ( tag.name().endsWith( ".example" ) ) { |
| 337 |
representationDoc.setExample( getSerializedExample( tag ) ); |
| 338 |
} |
| 339 |
else if ( tag.name().endsWith( ".doc" ) ) { |
| 340 |
representationDoc.setDoc( tag.text() ); |
| 341 |
} |
| 342 |
else { |
| 343 |
LOG.warning( "Unknown response representation tag " + tag.name() ); |
| 344 |
} |
| 345 |
} |
| 346 |
responseDoc.getRepresentations().add( representationDoc ); |
| 347 |
} |
| 348 |
|
| 349 |
methodDocType.setResponseDoc( responseDoc ); |
| 350 |
} |
| 351 |
|
| 352 |
private static boolean isEmpty( String value ) { |
| 353 |
return value == null || value.length() == 0 || value.trim().length() == 0 ? true : false; |
| 354 |
} |
| 355 |
|
| 356 |
private static void addRequestRepresentationDoc( MethodDoc methodDoc, |
| 357 |
final MethodDocType methodDocType ) { |
| 358 |
final Tag requestElement = getSingleTagOrNull( methodDoc, "request.representation.qname" ); |
| 359 |
final Tag requestExample = getSingleTagOrNull( methodDoc, "request.representation.example" ); |
| 360 |
if ( requestElement != null || requestExample != null ) { |
| 361 |
final RequestDocType requestDoc = new RequestDocType(); |
| 362 |
final RepresentationDocType representationDoc = new RepresentationDocType(); |
| 363 |
|
| 364 |
/* requestElement exists |
| 365 |
*/ |
| 366 |
if ( requestElement != null ) { |
| 367 |
representationDoc.setElement( QName.valueOf( requestElement.text() ) ); |
| 368 |
} |
| 369 |
|
| 370 |
/* requestExample exists |
| 371 |
*/ |
| 372 |
if ( requestExample != null ) { |
| 373 |
final String example = getSerializedExample( requestExample ); |
| 374 |
if ( !isEmpty( example ) ) { |
| 375 |
representationDoc.setExample( example ); |
| 376 |
} |
| 377 |
else { |
| 378 |
LOG.warning( "Could not get serialized example for method " + methodDoc.qualifiedName() ); |
| 379 |
} |
| 380 |
} |
| 381 |
|
| 382 |
requestDoc.setRepresentationDoc( representationDoc ); |
| 383 |
methodDocType.setRequestDoc( requestDoc ); |
| 384 |
} |
| 385 |
} |
| 386 |
|
| 387 |
private static Map<String, List<Tag>> getResponseRepresentationTags( |
| 388 |
MethodDoc methodDoc ) { |
| 389 |
final Map<String,List<Tag>> tagsByStatus = new HashMap<String, List<Tag>>(); |
| 390 |
for ( Tag tag : methodDoc.tags() ) { |
| 391 |
final Matcher matcher = PATTERN_RESPONSE_REPRESENATION.matcher( tag.name() ); |
| 392 |
if ( matcher.matches() ) { |
| 393 |
final String status = matcher.group( 1 ); |
| 394 |
List<Tag> tags = tagsByStatus.get( status ); |
| 395 |
if ( tags == null ) { |
| 396 |
tags = new ArrayList<Tag>(); |
| 397 |
tagsByStatus.put( status, tags ); |
| 398 |
} |
| 399 |
tags.add( tag ); |
| 400 |
} |
| 401 |
} |
| 402 |
return tagsByStatus; |
| 403 |
} |
| 404 |
|
| 405 |
/** |
| 406 |
* Searches an <code>@link</code> tag within the inline tags of the specified tags |
| 407 |
* and serializes the referenced instance. |
| 408 |
* @param tag |
| 409 |
* @return |
| 410 |
* @author Martin Grotzke |
| 411 |
*/ |
| 412 |
private static String getSerializedExample( Tag tag ) { |
| 413 |
if ( tag != null ) { |
| 414 |
final Tag[] inlineTags = tag.inlineTags(); |
| 415 |
if ( inlineTags != null && inlineTags.length > 0 ) { |
| 416 |
for ( Tag inlineTag : inlineTags ) { |
| 417 |
if ( LOG.isLoggable( Level.FINE ) ) { |
| 418 |
LOG.fine( "Have inline tag: " + print( inlineTag ) ); |
| 419 |
} |
| 420 |
if ( "@link".equals( inlineTag.name() ) ) { |
| 421 |
if ( LOG.isLoggable( Level.FINE ) ) { |
| 422 |
LOG.fine( "Have link: " + print( inlineTag ) ); |
| 423 |
} |
| 424 |
final SeeTag linkTag = (SeeTag) inlineTag; |
| 425 |
return getSerializedLinkFromTag( linkTag ); |
| 426 |
} |
| 427 |
else if ( !isEmpty( inlineTag.text() ) ) { |
| 428 |
return inlineTag.text(); |
| 429 |
} |
| 430 |
} |
| 431 |
} |
| 432 |
else { |
| 433 |
LOG.fine( "Have example: " + print( tag ) ); |
| 434 |
return tag.text(); |
| 435 |
} |
| 436 |
} |
| 437 |
return null; |
| 438 |
} |
| 439 |
|
| 440 |
private static Tag getSingleTagOrNull( MethodDoc methodDoc, String tagName ) { |
| 441 |
final Tag[] tags = methodDoc.tags( tagName ); |
| 442 |
if ( tags != null && tags.length == 1 ) { |
| 443 |
return tags[0]; |
| 444 |
} |
| 445 |
return null; |
| 446 |
} |
| 447 |
|
| 448 |
private static void addParamDocs( MethodDoc methodDoc, |
| 449 |
final MethodDocType methodDocType, |
| 450 |
final DocProcessor docProcessor ) { |
| 451 |
final Parameter[] parameters = methodDoc.parameters(); |
| 452 |
final ParamTag[] paramTags = methodDoc.paramTags(); |
| 453 |
|
| 454 |
/* only use both javadoc and reflection information when the number |
| 455 |
* of params are the same |
| 456 |
*/ |
| 457 |
if ( parameters != null && paramTags != null |
| 458 |
&& parameters.length == paramTags.length ) { |
| 459 |
|
| 460 |
for ( int i = 0; i < parameters.length; i++ ) { |
| 461 |
final Parameter parameter = parameters[i]; |
| 462 |
|
| 463 |
/* TODO: this only works if the params and tags are in the same |
| 464 |
* order. If the param tags are mixed up, the comments for parameters |
| 465 |
* will be wrong. |
| 466 |
*/ |
| 467 |
final ParamTag paramTag = paramTags[i]; |
| 468 |
|
| 469 |
final ParamDocType paramDocType = new ParamDocType(); |
| 470 |
paramDocType.setParamName( paramTag.parameterName() ); |
| 471 |
paramDocType.setCommentText( paramTag.parameterComment() ); |
| 472 |
docProcessor.processParamTag( paramTag, parameter, paramDocType ); |
| 473 |
|
| 474 |
AnnotationDesc[] annotations = parameter.annotations(); |
| 475 |
if ( annotations != null ) { |
| 476 |
for ( AnnotationDesc annotationDesc : annotations ) { |
| 477 |
final AnnotationDocType annotationDocType = new AnnotationDocType(); |
| 478 |
final String typeName = annotationDesc.annotationType().qualifiedName(); |
| 479 |
annotationDocType.setAnnotationTypeName( typeName ); |
| 480 |
for ( ElementValuePair elementValuePair : annotationDesc.elementValues() ) { |
| 481 |
final NamedValueType namedValueType = new NamedValueType(); |
| 482 |
namedValueType.setName( elementValuePair.element().name() ); |
| 483 |
namedValueType.setValue( elementValuePair.value().value().toString() ); |
| 484 |
annotationDocType.getAttributeDocs().add( namedValueType ); |
| 485 |
} |
| 486 |
paramDocType.getAnnotationDocs().add( annotationDocType ); |
| 487 |
} |
| 488 |
} |
| 489 |
|
| 490 |
methodDocType.getParamDocs().add( paramDocType ); |
| 491 |
|
| 492 |
} |
| 493 |
|
| 494 |
} |
| 495 |
} |
| 496 |
|
| 497 |
private static String getSerializedLinkFromTag( final SeeTag linkTag ) { |
| 498 |
final MemberDoc referencedMember = linkTag.referencedMember(); |
| 499 |
|
| 500 |
if ( referencedMember == null ) { |
| 501 |
throw new NullPointerException( "Referenced member of @link "+ print( linkTag ) +" cannot be resolved." ); |
| 502 |
} |
| 503 |
|
| 504 |
if ( !referencedMember.isStatic() ) { |
| 505 |
LOG.warning( "Referenced member of @link "+ print( linkTag ) +" is not static." + |
| 506 |
" Right now only references to static members are supported." ); |
| 507 |
return null; |
| 508 |
} |
| 509 |
|
| 510 |
/* Get referenced example bean |
| 511 |
*/ |
| 512 |
final ClassDoc containingClass = referencedMember.containingClass(); |
| 513 |
final Object object; |
| 514 |
try { |
| 515 |
Field declaredField = Class.forName( containingClass.qualifiedName(), false, Thread.currentThread().getContextClassLoader() ).getDeclaredField( referencedMember.name() ); |
| 516 |
if ( referencedMember.isFinal() ) { |
| 517 |
declaredField.setAccessible( true ); |
| 518 |
} |
| 519 |
object = declaredField.get( null ); |
| 520 |
LOG.log( Level.FINE, "Got object " + object ); |
| 521 |
} catch ( Exception e ) { |
| 522 |
LOG.info( "Have classloader: " + ResourceDoclet.class.getClassLoader().getClass() ); |
| 523 |
LOG.info( "Have thread classloader " + Thread.currentThread().getContextClassLoader().getClass() ); |
| 524 |
LOG.info( "Have system classloader " + ClassLoader.getSystemClassLoader().getClass() ); |
| 525 |
LOG.log( Level.SEVERE, "Could not get field " + referencedMember.qualifiedName(), e ); |
| 526 |
return null; |
| 527 |
} |
| 528 |
|
| 529 |
/* marshal the bean to xml |
| 530 |
*/ |
| 531 |
try { |
| 532 |
final JAXBContext jaxbContext = JAXBContext.newInstance( object.getClass() ); |
| 533 |
final StringWriter stringWriter = new StringWriter(); |
| 534 |
final Marshaller marshaller = jaxbContext.createMarshaller(); |
| 535 |
marshaller.setProperty( Marshaller.JAXB_FORMATTED_OUTPUT, true ); |
| 536 |
marshaller.marshal( object, stringWriter ); |
| 537 |
final String result = stringWriter.getBuffer().toString(); |
| 538 |
LOG.log( Level.FINE, "Got marshalled output:\n" + result ); |
| 539 |
return result; |
| 540 |
} catch ( Exception e ) { |
| 541 |
LOG.log( Level.SEVERE, "Could serialize bean to xml: " + object, e ); |
| 542 |
return null; |
| 543 |
} |
| 544 |
} |
| 545 |
|
| 546 |
private static String print( Tag tag ) { |
| 547 |
final StringBuilder sb = new StringBuilder(); |
| 548 |
sb.append( tag.getClass() ).append( "[" ); |
| 549 |
sb.append( "firstSentenceTags=" ).append( toCSV( tag.firstSentenceTags() ) ); |
| 550 |
sb.append( ", inlineTags=" ).append( toCSV( tag.inlineTags() ) ); |
| 551 |
sb.append( ", kind=" ).append( tag.kind() ); |
| 552 |
sb.append( ", name=" ).append( tag.name() ); |
| 553 |
sb.append( ", text=" ).append( tag.text() ); |
| 554 |
sb.append( "]" ); |
| 555 |
return sb.toString(); |
| 556 |
} |
| 557 |
|
| 558 |
static <T> String toCSV( Tag[] items ) { |
| 559 |
if ( items == null ) { |
| 560 |
return null; |
| 561 |
} |
| 562 |
return toCSV( Arrays.asList( items ) ); |
| 563 |
} |
| 564 |
|
| 565 |
static <I> String toCSV( Collection<Tag> items ) { |
| 566 |
return toCSV( items, ", ", null ); |
| 567 |
} |
| 568 |
|
| 569 |
static <I> String toCSV( Collection<Tag> items, String separator, String delimiter ) { |
| 570 |
if ( items == null ) { |
| 571 |
return null; |
| 572 |
} |
| 573 |
if ( items.isEmpty() ) { |
| 574 |
return ""; |
| 575 |
} |
| 576 |
final StringBuilder sb = new StringBuilder(); |
| 577 |
for ( final Iterator<Tag> iter = items.iterator(); iter.hasNext(); ) { |
| 578 |
if ( delimiter != null ) { |
| 579 |
sb.append( delimiter ); |
| 580 |
} |
| 581 |
final Tag item = iter.next(); |
| 582 |
sb.append( item.name() ); |
| 583 |
if ( delimiter != null ) { |
| 584 |
sb.append( delimiter ); |
| 585 |
} |
| 586 |
if ( iter.hasNext() ) { |
| 587 |
sb.append( separator ); |
| 588 |
} |
| 589 |
} |
| 590 |
return sb.toString(); |
| 591 |
} |
| 592 |
|
| 593 |
/** |
| 594 |
* Return array length for given option: 1 + the number of arguments that |
| 595 |
* the option takes. |
| 596 |
* |
| 597 |
* @param option |
| 598 |
* @return the number of args for the specified option |
| 599 |
*/ |
| 600 |
public static int optionLength( String option ) { |
| 601 |
LOG.fine( "Invoked with option " + option ); |
| 602 |
|
| 603 |
if ( OPTION_OUTPUT.equals( option ) |
| 604 |
|| OPTION_CLASSPATH.equals( option ) |
| 605 |
|| OPTION_DOC_PROCESSORS.equals( option ) ) { |
| 606 |
return 2; |
| 607 |
} |
| 608 |
|
| 609 |
return 0; |
| 610 |
} |
| 611 |
|
| 612 |
/** |
| 613 |
* Validate options. |
| 614 |
* |
| 615 |
* @param options |
| 616 |
* @param reporter |
| 617 |
* @return if the specified options are valid |
| 618 |
*/ |
| 619 |
public static boolean validOptions( String[][] options, DocErrorReporter reporter ) { |
| 620 |
return validOption( OPTION_OUTPUT, "<path-to-file>", options, reporter ) |
| 621 |
&& validOption( OPTION_CLASSPATH, "<path>", options, reporter ); |
| 622 |
} |
| 623 |
|
| 624 |
private static boolean validOption( String optionName, |
| 625 |
String reportOptionName, |
| 626 |
String[][] options, |
| 627 |
DocErrorReporter reporter ) { |
| 628 |
final String option = getOptionArg( options, optionName ); |
| 629 |
|
| 630 |
final boolean foundOption = option != null && option.trim().length() > 0; |
| 631 |
if ( !foundOption ) { |
| 632 |
reporter.printError( optionName + " "+ reportOptionName +" must be specified." ); |
| 633 |
} |
| 634 |
return foundOption; |
| 635 |
} |
| 636 |
|
| 637 |
private static String getOptionArg( String[][] options, String option ) { |
| 638 |
|
| 639 |
for ( int i = 0; i < options.length; i++ ) { |
| 640 |
String[] opt = options[i]; |
| 641 |
|
| 642 |
if ( opt[0].equals( option ) ) { |
| 643 |
return opt[1]; |
| 644 |
} |
| 645 |
} |
| 646 |
|
| 647 |
return null; |
| 648 |
} |
| 649 |
|
| 650 |
static class Loader extends URLClassLoader { |
| 651 |
|
| 652 |
public Loader(String[] paths, ClassLoader parent) { |
| 653 |
super(getURLs(paths), parent); |
| 654 |
} |
| 655 |
|
| 656 |
Loader(String[] paths) { |
| 657 |
super(getURLs(paths)); |
| 658 |
} |
| 659 |
|
| 660 |
private static URL[] getURLs(String[] paths) { |
| 661 |
final List<URL> urls = new ArrayList<URL>(); |
| 662 |
for (String path: paths) { |
| 663 |
try { |
| 664 |
urls.add(new File(path).toURI().toURL()); |
| 665 |
} catch (MalformedURLException e) { |
| 666 |
throw new RuntimeException(e); |
| 667 |
} |
| 668 |
} |
| 669 |
final URL[] us = urls.toArray(new URL[0]); |
| 670 |
return us; |
| 671 |
} |
| 672 |
|
| 673 |
} |
| 674 |
|
| 675 |
} |