Repository: cxf Updated Branches: refs/heads/master 1bd380a4c -> 762719c29
[CXF-5479]add javadoc support for the java2wadl-plugin Project: http://git-wip-us.apache.org/repos/asf/cxf/repo Commit: http://git-wip-us.apache.org/repos/asf/cxf/commit/762719c2 Tree: http://git-wip-us.apache.org/repos/asf/cxf/tree/762719c2 Diff: http://git-wip-us.apache.org/repos/asf/cxf/diff/762719c2 Branch: refs/heads/master Commit: 762719c29c74b78b70789d232b6602d09414789f Parents: 1bd380a Author: Freeman Fang <[email protected]> Authored: Tue Apr 22 10:15:22 2014 +0800 Committer: Freeman Fang <[email protected]> Committed: Tue Apr 22 10:15:22 2014 +0800 ---------------------------------------------------------------------- maven-plugins/java2wadl-plugin/pom.xml | 15 ++ .../maven_plugin/javatowadl/DumpJavaDoc.java | 107 +++++++++ .../maven_plugin/javatowadl/Java2WADLMojo.java | 3 +- .../javatowadl/ParseJavaDocMojo.java | 217 +++++++++++++++++++ .../javatowadl/ResourceMapJavaDocProvider.java | 99 +++++++++ 5 files changed, 440 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cxf/blob/762719c2/maven-plugins/java2wadl-plugin/pom.xml ---------------------------------------------------------------------- diff --git a/maven-plugins/java2wadl-plugin/pom.xml b/maven-plugins/java2wadl-plugin/pom.xml index 8328930..6c837a1 100644 --- a/maven-plugins/java2wadl-plugin/pom.xml +++ b/maven-plugins/java2wadl-plugin/pom.xml @@ -114,6 +114,21 @@ <groupId>org.apache.ant</groupId> <artifactId>ant-nodeps</artifactId> </dependency> + + <dependency> + <groupId>org.apache.maven.plugins</groupId> + <artifactId>maven-javadoc-plugin</artifactId> + <version>2.9.1</version> + </dependency> + + <dependency> + <groupId>com.sun</groupId> + <artifactId>tools</artifactId> + <version>1.6.0</version> + <scope>system</scope> + <systemPath>${java.home}/../lib/tools.jar</systemPath> + </dependency> + </dependencies> http://git-wip-us.apache.org/repos/asf/cxf/blob/762719c2/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/DumpJavaDoc.java ---------------------------------------------------------------------- diff --git a/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/DumpJavaDoc.java b/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/DumpJavaDoc.java new file mode 100644 index 0000000..23c40b5 --- /dev/null +++ b/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/DumpJavaDoc.java @@ -0,0 +1,107 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.cxf.maven_plugin.javatowadl; + +import java.io.FileOutputStream; +import java.io.IOException; +import java.util.Properties; + +import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.DocErrorReporter; +import com.sun.javadoc.MethodDoc; +import com.sun.javadoc.ParamTag; +import com.sun.javadoc.Parameter; +import com.sun.javadoc.RootDoc; +import com.sun.javadoc.Tag; + +public final class DumpJavaDoc { + + private DumpJavaDoc() { + + } + + public static boolean start(RootDoc root) throws IOException { + String dumpFileName = readOptions(root.options()); + FileOutputStream fos = new FileOutputStream(dumpFileName); + Properties javaDocMap = new Properties(); + for (ClassDoc classDoc : root.classes()) { + javaDocMap.put(classDoc.toString(), classDoc.commentText()); + for (MethodDoc method : classDoc.methods()) { + javaDocMap.put(method.qualifiedName(), method.commentText()); + for (ParamTag paramTag : method.paramTags()) { + Parameter[] parameters = method.parameters(); + for (int i = 0; i < parameters.length; ++i) { + if (parameters[i].name().equals(paramTag.parameterName())) { + javaDocMap.put(method.qualifiedName() + ".paramCommentTag." + i, + paramTag.parameterComment()); + } + } + } + Tag retTags[] = method.tags("return"); + if (retTags != null && retTags.length == 1) { + Tag retTag = method.tags("return")[0]; + javaDocMap.put(method.qualifiedName() + "." + "returnCommentTag", + retTag.text()); + } + } + + } + javaDocMap.store(fos, ""); + fos.flush(); + fos.close(); + return true; + } + + private static String readOptions(String[][] options) { + String tagName = null; + for (int i = 0; i < options.length; i++) { + String[] opt = options[i]; + if (opt[0].equals("-dumpJavaDocFile")) { + tagName = opt[1]; + } + } + return tagName; + } + + public static int optionLength(String option) { + if ("-dumpJavaDocFile".equals(option)) { + return 2; + } + return 0; + } + + public static boolean validOptions(String options[][], DocErrorReporter reporter) { + boolean foundTagOption = false; + for (int i = 0; i < options.length; i++) { + String[] opt = options[i]; + if (opt[0].equals("-dumpJavaDocFile")) { + if (foundTagOption) { + reporter.printError("Only one -dumpJavaDocFile option allowed."); + return false; + } else { + foundTagOption = true; + } + } + } + if (!foundTagOption) { + reporter.printError("Usage: -dumpJavaDocFile theFileToDumpJavaDocForLatarUse..."); + } + return foundTagOption; + } +} http://git-wip-us.apache.org/repos/asf/cxf/blob/762719c2/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/Java2WADLMojo.java ---------------------------------------------------------------------- diff --git a/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/Java2WADLMojo.java b/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/Java2WADLMojo.java index 3d92bed..1cda24d 100644 --- a/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/Java2WADLMojo.java +++ b/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/Java2WADLMojo.java @@ -124,6 +124,7 @@ public class Java2WADLMojo extends AbstractMojo { public void execute() throws MojoExecutionException { + getResourcesList(); WadlGenerator wadlGenernator = new WadlGenerator(getBus()); DocumentationProvider documentationProvider = null; @@ -131,7 +132,7 @@ public class Java2WADLMojo extends AbstractMojo { try { documentationProvider = (DocumentationProvider)getClassLoader().loadClass(docProvider). getConstructor(new Class[] {String.class}). - newInstance(new Object[] {project.getBuild().getDirectory() + "/classes" }); + newInstance(new Object[] {project.getBuild().getDirectory()}); wadlGenernator.setDocumentationProvider(documentationProvider); } catch (Exception e) { throw new MojoExecutionException(e.getMessage(), e); http://git-wip-us.apache.org/repos/asf/cxf/blob/762719c2/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/ParseJavaDocMojo.java ---------------------------------------------------------------------- diff --git a/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/ParseJavaDocMojo.java b/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/ParseJavaDocMojo.java new file mode 100644 index 0000000..3322520 --- /dev/null +++ b/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/ParseJavaDocMojo.java @@ -0,0 +1,217 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.cxf.maven_plugin.javatowadl; + +import java.io.File; +import java.lang.reflect.Field; +import java.util.List; +import java.util.Locale; + +import org.apache.maven.artifact.Artifact; +import org.apache.maven.artifact.factory.ArtifactFactory; +import org.apache.maven.artifact.metadata.ArtifactMetadataSource; +import org.apache.maven.artifact.repository.ArtifactRepository; +import org.apache.maven.artifact.resolver.ArtifactResolver; +import org.apache.maven.plugin.MojoExecutionException; +import org.apache.maven.plugin.MojoFailureException; +import org.apache.maven.plugin.javadoc.AbstractJavadocMojo; +import org.apache.maven.plugin.javadoc.options.DocletArtifact; +import org.apache.maven.project.MavenProject; +import org.apache.maven.project.MavenProjectBuilder; +import org.apache.maven.reporting.MavenReportException; + +import org.apache.maven.toolchain.ToolchainManager; +import org.codehaus.plexus.archiver.manager.ArchiverManager; + +/** + * @goal parsejavadoc + * @description CXF Java To WADL Tool + * @requiresDependencyResolution compile + * @threadSafe + */ +public class ParseJavaDocMojo extends AbstractJavadocMojo { + + /** + * @parameter expression="${project}" + * @required + */ + private MavenProject mavenProject; + + /** + * @component + */ + private ArchiverManager archiverManager; + + /** + * @component + */ + private ArtifactFactory mavenArtifactFactory; + + /** + * @component + */ + private ArtifactResolver artifactResolver; + + /** + * @component + */ + private MavenProjectBuilder mavenProjectBuilder; + + /** + * @component + */ + private ArtifactMetadataSource artifactMetadataSource; + + /** + * @component + */ + private ToolchainManager toolchainManager; + + /** + * @parameter default-value = "${project.reporting.outputDirectory}/apidocs" + * @required + */ + private File dumpFileOutputDirectory; + + /** + * The local maven repository. + * + * @parameter expression="${localRepository}" + * @required + * @readonly + */ + private ArtifactRepository localRepository; + + /** + * The remote repositories where artifacts are located. + * + * @parameter expression="${project.remoteArtifactRepositories}" + * @required + * @readonly + */ + private List<ArtifactRepository> remoteRepositories; + + @Override + public void execute() throws MojoExecutionException, MojoFailureException { + if (skip) { + getLog().info("Skipping parse javadoc"); + return; + } + + try { + Locale locale = Locale.getDefault(); + Field f = AbstractJavadocMojo.class.getDeclaredField("doclet"); + f.setAccessible(true); + f.set(this, "org.apache.cxf.maven_plugin.javatowadl.DumpJavaDoc"); + + f = AbstractJavadocMojo.class.getDeclaredField("stylesheet"); + f.setAccessible(true); + f.set(this, "stylesheet"); + + f = AbstractJavadocMojo.class.getDeclaredField("docletArtifact"); + f.setAccessible(true); + DocletArtifact docletArtifact = new DocletArtifact(); + for (Object o : this.mavenProject.getPluginArtifacts()) { + if (o instanceof Artifact) { + Artifact artifact = (Artifact)o; + if (artifact.getArtifactId().equals("cxf-java2wadl-plugin")) { + docletArtifact.setGroupId(artifact.getGroupId()); + docletArtifact.setArtifactId(artifact.getArtifactId()); + docletArtifact.setVersion(artifact.getVersion()); + } + } + } + f.set(this, docletArtifact); + + f = AbstractJavadocMojo.class.getDeclaredField("factory"); + f.setAccessible(true); + f.set(this, this.mavenArtifactFactory); + + f = AbstractJavadocMojo.class.getDeclaredField("mavenProjectBuilder"); + f.setAccessible(true); + f.set(this, this.mavenProjectBuilder); + + f = AbstractJavadocMojo.class.getDeclaredField("resolver"); + f.setAccessible(true); + f.set(this, this.artifactResolver); + + f = AbstractJavadocMojo.class.getDeclaredField("archiverManager"); + f.setAccessible(true); + f.set(this, this.archiverManager); + + f = AbstractJavadocMojo.class.getDeclaredField("artifactMetadataSource"); + f.setAccessible(true); + f.set(this, this.artifactMetadataSource); + + f = AbstractJavadocMojo.class.getDeclaredField("toolchainManager"); + f.setAccessible(true); + f.set(this, this.toolchainManager); + + f = AbstractJavadocMojo.class.getDeclaredField("localRepository"); + f.setAccessible(true); + f.set(this, this.localRepository); + + f = AbstractJavadocMojo.class.getDeclaredField("remoteRepositories"); + f.setAccessible(true); + f.set(this, this.remoteRepositories); + + f = AbstractJavadocMojo.class.getDeclaredField("applyJavadocSecurityFix"); + f.setAccessible(true); + f.set(this, false); + + f = AbstractJavadocMojo.class.getDeclaredField("additionalparam"); + f.setAccessible(true); + f.set(this, "-dumpJavaDocFile " + this.dumpFileOutputDirectory.getAbsolutePath() + + File.separator + "dumpFile.properties"); + + useStandardDocletOptions = false; + this.project = mavenProject; + generate(locale); + } catch (Exception e) { + failOnError("An error has occurred in parsing javadoc", e); + } + + } + + private void generate(Locale locale) throws MavenReportException { + try { + outputDirectory = getReportOutputDirectory(); + executeReport(locale); + } catch (MavenReportException e) { + if (failOnError) { + throw e; + } + getLog().error("Error while creating javadoc report: " + e.getMessage(), e); + } catch (RuntimeException e) { + if (failOnError) { + throw e; + } + getLog().error("Error while creating javadoc report: " + e.getMessage(), e); + } + } + + private File getReportOutputDirectory() { + if (dumpFileOutputDirectory == null) { + return outputDirectory; + } + + return dumpFileOutputDirectory; + } + +} http://git-wip-us.apache.org/repos/asf/cxf/blob/762719c2/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/ResourceMapJavaDocProvider.java ---------------------------------------------------------------------- diff --git a/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/ResourceMapJavaDocProvider.java b/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/ResourceMapJavaDocProvider.java new file mode 100644 index 0000000..05d08b0 --- /dev/null +++ b/maven-plugins/java2wadl-plugin/src/main/java/org/apache/cxf/maven_plugin/javatowadl/ResourceMapJavaDocProvider.java @@ -0,0 +1,99 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.apache.cxf.maven_plugin.javatowadl; + +import java.io.FileInputStream; +import java.lang.reflect.Method; +import java.util.Properties; +import java.util.logging.Logger; + +import javax.ws.rs.Path; + +import org.apache.cxf.common.logging.LogUtils; +import org.apache.cxf.jaxrs.model.ClassResourceInfo; +import org.apache.cxf.jaxrs.model.OperationResourceInfo; +import org.apache.cxf.jaxrs.model.wadl.DocumentationProvider; + +public class ResourceMapJavaDocProvider implements DocumentationProvider { + + private static final Logger LOG = LogUtils.getL7dLogger(ResourceMapJavaDocProvider.class); + + private Properties dumpedDocFile; + + public ResourceMapJavaDocProvider(String targetFolder) { + try { + dumpedDocFile = new Properties(); + FileInputStream fis = new FileInputStream(targetFolder + "/site/apidocs/dumpFile.properties"); + dumpedDocFile.load(fis); + fis.close(); + } catch (Exception e) { + LOG.warning("can't load dumped Docomentation file" + e.getMessage()); + } + } + + @Override + public String getClassDoc(ClassResourceInfo cri) { + Class<?> annotatedClass = getPathAnnotatedClass(cri.getServiceClass()); + return dumpedDocFile.getProperty(annotatedClass.getName()); + } + + @Override + public String getMethodDoc(OperationResourceInfo ori) { + Method method = ori.getAnnotatedMethod() == null ? ori.getMethodToInvoke() + : ori.getAnnotatedMethod(); + String methodKey = method.getDeclaringClass().getName() + + "." + method.getName(); + return dumpedDocFile.getProperty(methodKey); + } + + @Override + public String getMethodResponseDoc(OperationResourceInfo ori) { + Method method = ori.getAnnotatedMethod() == null ? ori.getMethodToInvoke() + : ori.getAnnotatedMethod(); + String methodResponseKey = method.getDeclaringClass().getName() + + "." + method.getName() + "." + "returnCommentTag"; + return dumpedDocFile.getProperty(methodResponseKey); + } + + @Override + public String getMethodParameterDoc(OperationResourceInfo ori, int paramIndex) { + Method method = ori.getAnnotatedMethod() == null ? ori.getMethodToInvoke() + : ori.getAnnotatedMethod(); + String methodParamKey = method.getDeclaringClass().getName() + + "." + method.getName() + + ".paramCommentTag." + paramIndex; + return dumpedDocFile.getProperty(methodParamKey); + } + + private Class<?> getPathAnnotatedClass(Class<?> cls) { + if (cls.getAnnotation(Path.class) != null) { + return cls; + } + if (cls.getSuperclass().getAnnotation(Path.class) != null) { + return cls.getSuperclass(); + } + for (Class<?> i : cls.getInterfaces()) { + if (i.getAnnotation(Path.class) != null) { + return i; + } + } + return cls; + } + +}
