Return-Path: X-Original-To: apmail-cxf-commits-archive@www.apache.org Delivered-To: apmail-cxf-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 3C83A1821E for ; Fri, 9 Oct 2015 11:44:58 +0000 (UTC) Received: (qmail 30544 invoked by uid 500); 9 Oct 2015 11:44:58 -0000 Delivered-To: apmail-cxf-commits-archive@cxf.apache.org Received: (qmail 30482 invoked by uid 500); 9 Oct 2015 11:44:58 -0000 Mailing-List: contact commits-help@cxf.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@cxf.apache.org Delivered-To: mailing list commits@cxf.apache.org Received: (qmail 30471 invoked by uid 99); 9 Oct 2015 11:44:58 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 09 Oct 2015 11:44:58 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id AC009DFC8D; Fri, 9 Oct 2015 11:44:57 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: sergeyb@apache.org To: commits@cxf.apache.org Message-Id: X-Mailer: ASF-Git Admin Mailer Subject: cxf git commit: [CXF-6634] Moving DocumentationProvider to a dedicated package Date: Fri, 9 Oct 2015 11:44:57 +0000 (UTC) Repository: cxf Updated Branches: refs/heads/master e1cb88a13 -> 22a683b82 [CXF-6634] Moving DocumentationProvider to a dedicated package Project: http://git-wip-us.apache.org/repos/asf/cxf/repo Commit: http://git-wip-us.apache.org/repos/asf/cxf/commit/22a683b8 Tree: http://git-wip-us.apache.org/repos/asf/cxf/tree/22a683b8 Diff: http://git-wip-us.apache.org/repos/asf/cxf/diff/22a683b8 Branch: refs/heads/master Commit: 22a683b82bc5d65cb4104c19edca96b4b0dced61 Parents: e1cb88a Author: Sergey Beryozkin Authored: Fri Oct 9 12:44:36 2015 +0100 Committer: Sergey Beryozkin Committed: Fri Oct 9 12:44:36 2015 +0100 ---------------------------------------------------------------------- .../maven_plugin/javatowadl/Java2WADLMojo.java | 2 +- .../javatowadl/ResourceMapJavaDocProvider.java | 2 +- .../jaxrs/model/doc/DocumentationProvider.java | 29 ++ .../cxf/jaxrs/model/doc/JavaDocProvider.java | 363 +++++++++++++++++++ .../jaxrs/model/wadl/DocumentationProvider.java | 29 -- .../cxf/jaxrs/model/wadl/JavaDocProvider.java | 363 ------------------- .../cxf/jaxrs/model/wadl/WadlGenerator.java | 2 + .../jaxrs/model/doc/JavaDocProviderTest.java | 107 ++++++ .../jaxrs/model/wadl/JavaDocProviderTest.java | 107 ------ 9 files changed, 503 insertions(+), 501 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cxf/blob/22a683b8/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 1d04a84..75e63a3 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 @@ -38,7 +38,7 @@ import org.apache.cxf.BusFactory; import org.apache.cxf.common.util.ClasspathScanner; import org.apache.cxf.helpers.FileUtils; import org.apache.cxf.jaxrs.model.ClassResourceInfo; -import org.apache.cxf.jaxrs.model.wadl.DocumentationProvider; +import org.apache.cxf.jaxrs.model.doc.DocumentationProvider; import org.apache.cxf.jaxrs.model.wadl.WadlGenerator; import org.apache.cxf.jaxrs.utils.InjectionUtils; import org.apache.cxf.jaxrs.utils.ResourceUtils; http://git-wip-us.apache.org/repos/asf/cxf/blob/22a683b8/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 index 05d08b0..fcd29b7 100644 --- 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 @@ -28,7 +28,7 @@ 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; +import org.apache.cxf.jaxrs.model.doc.DocumentationProvider; public class ResourceMapJavaDocProvider implements DocumentationProvider { http://git-wip-us.apache.org/repos/asf/cxf/blob/22a683b8/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/doc/DocumentationProvider.java ---------------------------------------------------------------------- diff --git a/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/doc/DocumentationProvider.java b/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/doc/DocumentationProvider.java new file mode 100644 index 0000000..dff4fd6 --- /dev/null +++ b/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/doc/DocumentationProvider.java @@ -0,0 +1,29 @@ +/** + * 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.jaxrs.model.doc; + +import org.apache.cxf.jaxrs.model.ClassResourceInfo; +import org.apache.cxf.jaxrs.model.OperationResourceInfo; + +public interface DocumentationProvider { + String getClassDoc(ClassResourceInfo cri); + String getMethodDoc(OperationResourceInfo ori); + String getMethodResponseDoc(OperationResourceInfo ori); + String getMethodParameterDoc(OperationResourceInfo ori, int paramIndex); +} http://git-wip-us.apache.org/repos/asf/cxf/blob/22a683b8/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/doc/JavaDocProvider.java ---------------------------------------------------------------------- diff --git a/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/doc/JavaDocProvider.java b/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/doc/JavaDocProvider.java new file mode 100644 index 0000000..b3fe34a --- /dev/null +++ b/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/doc/JavaDocProvider.java @@ -0,0 +1,363 @@ +/** + * 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.jaxrs.model.doc; + +import java.io.InputStream; +import java.lang.reflect.Method; +import java.net.URL; +import java.net.URLClassLoader; +import java.util.LinkedList; +import java.util.List; +import java.util.concurrent.ConcurrentHashMap; + +import javax.ws.rs.Path; + +import org.apache.cxf.Bus; +import org.apache.cxf.BusFactory; +import org.apache.cxf.common.util.StringUtils; +import org.apache.cxf.helpers.IOUtils; +import org.apache.cxf.jaxrs.model.ClassResourceInfo; +import org.apache.cxf.jaxrs.model.OperationResourceInfo; +import org.apache.cxf.jaxrs.utils.ResourceUtils; + +public class JavaDocProvider implements DocumentationProvider { + public static final double JAVA_VERSION = getVersion(); + public static final double JAVA_VERSION_16 = 1.6D; + public static final double JAVA_VERSION_17 = 1.7D; + public static final double JAVA_VERSION_18 = 1.8D; + + private ClassLoader javaDocLoader; + private ConcurrentHashMap docs = new ConcurrentHashMap(); + private double javaDocsBuiltByVersion = JAVA_VERSION; + + public JavaDocProvider(URL javaDocUrl) { + if (javaDocUrl == null) { + throw new IllegalArgumentException("URL is null"); + } + javaDocLoader = new URLClassLoader(new URL[]{javaDocUrl}); + } + + public JavaDocProvider(String path) throws Exception { + this(BusFactory.getDefaultBus(), path); + } + + public JavaDocProvider(Bus bus, String path) throws Exception { + this(ResourceUtils.getResourceURL(path, bus)); + } + + private static double getVersion() { + String version = System.getProperty("java.version"); + try { + return Double.parseDouble(version.substring(0, 3)); + } catch (Exception ex) { + return JAVA_VERSION_16; + } + } + + public String getClassDoc(ClassResourceInfo cri) { + try { + ClassDocs doc = getClassDocInternal(cri.getServiceClass()); + if (doc == null) { + return null; + } + return doc.getClassInfo(); + } catch (Exception ex) { + // ignore + } + return null; + } + + public String getMethodDoc(OperationResourceInfo ori) { + try { + MethodDocs doc = getOperationDocInternal(ori); + if (doc == null) { + return null; + } + return doc.getMethodInfo(); + } catch (Exception ex) { + // ignore + } + return null; + } + + public String getMethodResponseDoc(OperationResourceInfo ori) { + try { + MethodDocs doc = getOperationDocInternal(ori); + if (doc == null) { + return null; + } + return doc.getResponseInfo(); + } catch (Exception ex) { + // ignore + } + return null; + } + + public String getMethodParameterDoc(OperationResourceInfo ori, int paramIndex) { + try { + MethodDocs doc = getOperationDocInternal(ori); + if (doc == null) { + return null; + } + List params = doc.getParamInfo(); + if (paramIndex < params.size()) { + return params.get(paramIndex); + } else { + return null; + } + } catch (Exception ex) { + // ignore + } + return null; + } + + private Class getPathAnnotatedClass(Class cls) { + if (cls.getAnnotation(Path.class) != null) { + return cls; + } + if (cls.getSuperclass() != null && cls.getSuperclass().getAnnotation(Path.class) != null) { + return cls.getSuperclass(); + } + for (Class i : cls.getInterfaces()) { + if (i.getAnnotation(Path.class) != null) { + return i; + } + } + return cls; + } + + private ClassDocs getClassDocInternal(Class cls) throws Exception { + Class annotatedClass = getPathAnnotatedClass(cls); + String resource = annotatedClass.getName().replace(".", "/") + ".html"; + ClassDocs classDocs = docs.get(resource); + if (classDocs == null) { + InputStream resourceStream = javaDocLoader.getResourceAsStream(resource); + if (resourceStream != null) { + String doc = IOUtils.readStringFromStream(resourceStream); + + String qualifier = annotatedClass.isInterface() ? "Interface" : "Class"; + String classMarker = qualifier + " " + annotatedClass.getSimpleName(); + int index = doc.indexOf(classMarker); + if (index != -1) { + String classInfoTag = getClassInfoTag(); + String classInfo = getJavaDocText(doc, classInfoTag, + "Method Summary", index + classMarker.length()); + classDocs = new ClassDocs(doc, classInfo); + docs.putIfAbsent(resource, classDocs); + } + } + } + return classDocs; + } + + + private MethodDocs getOperationDocInternal(OperationResourceInfo ori) throws Exception { + Method method = ori.getAnnotatedMethod() == null + ? ori.getMethodToInvoke() + : ori.getAnnotatedMethod(); + ClassDocs classDoc = getClassDocInternal(method.getDeclaringClass()); + if (classDoc == null) { + return null; + } + MethodDocs mDocs = classDoc.getMethodDocs(method); + if (mDocs == null) { + String operLink = getOperLink(); + String operMarker = operLink + method.getName() + getOperationMarkerOpen(); + + int operMarkerIndex = classDoc.getClassDoc().indexOf(operMarker); + while (operMarkerIndex != -1) { + int startOfOpSigIndex = operMarkerIndex + operMarker.length(); + int endOfOpSigIndex = classDoc.getClassDoc().indexOf(getOperationMarkerClose(), + startOfOpSigIndex); + int paramLen = method.getParameterTypes().length; + if (endOfOpSigIndex == startOfOpSigIndex && paramLen == 0) { + break; + } else if (endOfOpSigIndex > startOfOpSigIndex + 1) { + String paramSequence = classDoc.getClassDoc().substring(operMarkerIndex, endOfOpSigIndex); + if (paramSequence.startsWith(operMarker)) { + paramSequence = paramSequence.substring(operMarker.length()); + String[] opBits = paramSequence.split(getOperationParamSeparator()); + if (opBits.length == paramLen) { + break; + } + } + } + operMarkerIndex = classDoc.getClassDoc().indexOf(operMarker, + operMarkerIndex + operMarker.length()); + } + + if (operMarkerIndex == -1) { + return null; + } + + String operDoc = classDoc.getClassDoc().substring(operMarkerIndex + operMarker.length()); + String operInfoTag = getOperInfoTag(); + String operInfo = getJavaDocText(operDoc, operInfoTag, operLink, 0); + String responseInfo = null; + List paramDocs = new LinkedList(); + if (!StringUtils.isEmpty(operInfo)) { + int returnsIndex = operDoc.indexOf("Returns:", operLink.length()); + int nextOpIndex = operDoc.indexOf(operLink); + if (returnsIndex != -1 && (nextOpIndex > returnsIndex || nextOpIndex == -1)) { + responseInfo = getJavaDocText(operDoc, getResponseMarker(), operLink, returnsIndex + 8); + } + + int paramIndex = operDoc.indexOf("Parameters:"); + if (paramIndex != -1 && (nextOpIndex == -1 || paramIndex < nextOpIndex)) { + String paramString = returnsIndex == -1 ? operDoc.substring(paramIndex) + : operDoc.substring(paramIndex, returnsIndex); + + String codeTag = getCodeTag(); + + int codeIndex = paramString.indexOf(codeTag); + while (codeIndex != -1) { + int next = paramString.indexOf("<", codeIndex + 7); + if (next == -1) { + next = paramString.length(); + } + String param = paramString.substring(codeIndex + 7, next).trim(); + if (param.startsWith("-")) { + param = param.substring(1).trim(); + } + paramDocs.add(param); + if (next == paramString.length()) { + break; + } else { + codeIndex = next + 1; + } + codeIndex = paramString.indexOf(codeTag, codeIndex); + } + + } + } + mDocs = new MethodDocs(operInfo, paramDocs, responseInfo); + classDoc.addMethodDocs(method, mDocs); + } + + return mDocs; + } + + + + private String getJavaDocText(String doc, String tag, String notAfterTag, int index) { + int tagIndex = doc.indexOf(tag, index); + if (tagIndex != -1) { + int notAfterIndex = doc.indexOf(notAfterTag, index); + if (notAfterIndex == -1 || notAfterIndex > tagIndex) { + int nextIndex = doc.indexOf("<", tagIndex + tag.length()); + if (nextIndex != -1) { + return doc.substring(tagIndex + tag.length(), nextIndex).trim(); + } + } + } + return null; + } + + protected String getClassInfoTag() { + if (javaDocsBuiltByVersion == JAVA_VERSION_16) { + return "

"; + } else { + return "

"; + } + } + protected String getOperInfoTag() { + if (javaDocsBuiltByVersion == JAVA_VERSION_16) { + return "
"; + } else { + return "
"; + } + } + protected String getOperLink() { + String operLink = " mdocs = new ConcurrentHashMap(); + public ClassDocs(String classDoc, String classInfo) { + this.classDoc = classDoc; + this.classInfo = classInfo; + } + + public String getClassDoc() { + return classDoc; + } + + public String getClassInfo() { + return classInfo; + } + + public MethodDocs getMethodDocs(Method method) { + return mdocs.get(method); + } + + public void addMethodDocs(Method method, MethodDocs doc) { + mdocs.putIfAbsent(method, doc); + } + } + + private static class MethodDocs { + private String methodInfo; + private List paramInfo = new LinkedList(); + private String responseInfo; + public MethodDocs(String methodInfo, List paramInfo, String responseInfo) { + this.methodInfo = methodInfo; + this.paramInfo = paramInfo; + this.responseInfo = responseInfo; + } + + public String getMethodInfo() { + return methodInfo; + } + + public List getParamInfo() { + return paramInfo; + } + + public String getResponseInfo() { + return responseInfo; + } + } +} http://git-wip-us.apache.org/repos/asf/cxf/blob/22a683b8/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/DocumentationProvider.java ---------------------------------------------------------------------- diff --git a/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/DocumentationProvider.java b/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/DocumentationProvider.java deleted file mode 100644 index 1e89a1d..0000000 --- a/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/DocumentationProvider.java +++ /dev/null @@ -1,29 +0,0 @@ -/** - * 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.jaxrs.model.wadl; - -import org.apache.cxf.jaxrs.model.ClassResourceInfo; -import org.apache.cxf.jaxrs.model.OperationResourceInfo; - -public interface DocumentationProvider { - String getClassDoc(ClassResourceInfo cri); - String getMethodDoc(OperationResourceInfo ori); - String getMethodResponseDoc(OperationResourceInfo ori); - String getMethodParameterDoc(OperationResourceInfo ori, int paramIndex); -} http://git-wip-us.apache.org/repos/asf/cxf/blob/22a683b8/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/JavaDocProvider.java ---------------------------------------------------------------------- diff --git a/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/JavaDocProvider.java b/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/JavaDocProvider.java deleted file mode 100644 index a5bcf0c..0000000 --- a/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/JavaDocProvider.java +++ /dev/null @@ -1,363 +0,0 @@ -/** - * 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.jaxrs.model.wadl; - -import java.io.InputStream; -import java.lang.reflect.Method; -import java.net.URL; -import java.net.URLClassLoader; -import java.util.LinkedList; -import java.util.List; -import java.util.concurrent.ConcurrentHashMap; - -import javax.ws.rs.Path; - -import org.apache.cxf.Bus; -import org.apache.cxf.BusFactory; -import org.apache.cxf.common.util.StringUtils; -import org.apache.cxf.helpers.IOUtils; -import org.apache.cxf.jaxrs.model.ClassResourceInfo; -import org.apache.cxf.jaxrs.model.OperationResourceInfo; -import org.apache.cxf.jaxrs.utils.ResourceUtils; - -public class JavaDocProvider implements DocumentationProvider { - public static final double JAVA_VERSION = getVersion(); - public static final double JAVA_VERSION_16 = 1.6D; - public static final double JAVA_VERSION_17 = 1.7D; - public static final double JAVA_VERSION_18 = 1.8D; - - private ClassLoader javaDocLoader; - private ConcurrentHashMap docs = new ConcurrentHashMap(); - private double javaDocsBuiltByVersion = JAVA_VERSION; - - public JavaDocProvider(URL javaDocUrl) { - if (javaDocUrl == null) { - throw new IllegalArgumentException("URL is null"); - } - javaDocLoader = new URLClassLoader(new URL[]{javaDocUrl}); - } - - public JavaDocProvider(String path) throws Exception { - this(BusFactory.getDefaultBus(), path); - } - - public JavaDocProvider(Bus bus, String path) throws Exception { - this(ResourceUtils.getResourceURL(path, bus)); - } - - private static double getVersion() { - String version = System.getProperty("java.version"); - try { - return Double.parseDouble(version.substring(0, 3)); - } catch (Exception ex) { - return JAVA_VERSION_16; - } - } - - public String getClassDoc(ClassResourceInfo cri) { - try { - ClassDocs doc = getClassDocInternal(cri.getServiceClass()); - if (doc == null) { - return null; - } - return doc.getClassInfo(); - } catch (Exception ex) { - // ignore - } - return null; - } - - public String getMethodDoc(OperationResourceInfo ori) { - try { - MethodDocs doc = getOperationDocInternal(ori); - if (doc == null) { - return null; - } - return doc.getMethodInfo(); - } catch (Exception ex) { - // ignore - } - return null; - } - - public String getMethodResponseDoc(OperationResourceInfo ori) { - try { - MethodDocs doc = getOperationDocInternal(ori); - if (doc == null) { - return null; - } - return doc.getResponseInfo(); - } catch (Exception ex) { - // ignore - } - return null; - } - - public String getMethodParameterDoc(OperationResourceInfo ori, int paramIndex) { - try { - MethodDocs doc = getOperationDocInternal(ori); - if (doc == null) { - return null; - } - List params = doc.getParamInfo(); - if (paramIndex < params.size()) { - return params.get(paramIndex); - } else { - return null; - } - } catch (Exception ex) { - // ignore - } - return null; - } - - private Class getPathAnnotatedClass(Class cls) { - if (cls.getAnnotation(Path.class) != null) { - return cls; - } - if (cls.getSuperclass() != null && cls.getSuperclass().getAnnotation(Path.class) != null) { - return cls.getSuperclass(); - } - for (Class i : cls.getInterfaces()) { - if (i.getAnnotation(Path.class) != null) { - return i; - } - } - return cls; - } - - private ClassDocs getClassDocInternal(Class cls) throws Exception { - Class annotatedClass = getPathAnnotatedClass(cls); - String resource = annotatedClass.getName().replace(".", "/") + ".html"; - ClassDocs classDocs = docs.get(resource); - if (classDocs == null) { - InputStream resourceStream = javaDocLoader.getResourceAsStream(resource); - if (resourceStream != null) { - String doc = IOUtils.readStringFromStream(resourceStream); - - String qualifier = annotatedClass.isInterface() ? "Interface" : "Class"; - String classMarker = qualifier + " " + annotatedClass.getSimpleName(); - int index = doc.indexOf(classMarker); - if (index != -1) { - String classInfoTag = getClassInfoTag(); - String classInfo = getJavaDocText(doc, classInfoTag, - "Method Summary", index + classMarker.length()); - classDocs = new ClassDocs(doc, classInfo); - docs.putIfAbsent(resource, classDocs); - } - } - } - return classDocs; - } - - - private MethodDocs getOperationDocInternal(OperationResourceInfo ori) throws Exception { - Method method = ori.getAnnotatedMethod() == null - ? ori.getMethodToInvoke() - : ori.getAnnotatedMethod(); - ClassDocs classDoc = getClassDocInternal(method.getDeclaringClass()); - if (classDoc == null) { - return null; - } - MethodDocs mDocs = classDoc.getMethodDocs(method); - if (mDocs == null) { - String operLink = getOperLink(); - String operMarker = operLink + method.getName() + getOperationMarkerOpen(); - - int operMarkerIndex = classDoc.getClassDoc().indexOf(operMarker); - while (operMarkerIndex != -1) { - int startOfOpSigIndex = operMarkerIndex + operMarker.length(); - int endOfOpSigIndex = classDoc.getClassDoc().indexOf(getOperationMarkerClose(), - startOfOpSigIndex); - int paramLen = method.getParameterTypes().length; - if (endOfOpSigIndex == startOfOpSigIndex && paramLen == 0) { - break; - } else if (endOfOpSigIndex > startOfOpSigIndex + 1) { - String paramSequence = classDoc.getClassDoc().substring(operMarkerIndex, endOfOpSigIndex); - if (paramSequence.startsWith(operMarker)) { - paramSequence = paramSequence.substring(operMarker.length()); - String[] opBits = paramSequence.split(getOperationParamSeparator()); - if (opBits.length == paramLen) { - break; - } - } - } - operMarkerIndex = classDoc.getClassDoc().indexOf(operMarker, - operMarkerIndex + operMarker.length()); - } - - if (operMarkerIndex == -1) { - return null; - } - - String operDoc = classDoc.getClassDoc().substring(operMarkerIndex + operMarker.length()); - String operInfoTag = getOperInfoTag(); - String operInfo = getJavaDocText(operDoc, operInfoTag, operLink, 0); - String responseInfo = null; - List paramDocs = new LinkedList(); - if (!StringUtils.isEmpty(operInfo)) { - int returnsIndex = operDoc.indexOf("Returns:", operLink.length()); - int nextOpIndex = operDoc.indexOf(operLink); - if (returnsIndex != -1 && (nextOpIndex > returnsIndex || nextOpIndex == -1)) { - responseInfo = getJavaDocText(operDoc, getResponseMarker(), operLink, returnsIndex + 8); - } - - int paramIndex = operDoc.indexOf("Parameters:"); - if (paramIndex != -1 && (nextOpIndex == -1 || paramIndex < nextOpIndex)) { - String paramString = returnsIndex == -1 ? operDoc.substring(paramIndex) - : operDoc.substring(paramIndex, returnsIndex); - - String codeTag = getCodeTag(); - - int codeIndex = paramString.indexOf(codeTag); - while (codeIndex != -1) { - int next = paramString.indexOf("<", codeIndex + 7); - if (next == -1) { - next = paramString.length(); - } - String param = paramString.substring(codeIndex + 7, next).trim(); - if (param.startsWith("-")) { - param = param.substring(1).trim(); - } - paramDocs.add(param); - if (next == paramString.length()) { - break; - } else { - codeIndex = next + 1; - } - codeIndex = paramString.indexOf(codeTag, codeIndex); - } - - } - } - mDocs = new MethodDocs(operInfo, paramDocs, responseInfo); - classDoc.addMethodDocs(method, mDocs); - } - - return mDocs; - } - - - - private String getJavaDocText(String doc, String tag, String notAfterTag, int index) { - int tagIndex = doc.indexOf(tag, index); - if (tagIndex != -1) { - int notAfterIndex = doc.indexOf(notAfterTag, index); - if (notAfterIndex == -1 || notAfterIndex > tagIndex) { - int nextIndex = doc.indexOf("<", tagIndex + tag.length()); - if (nextIndex != -1) { - return doc.substring(tagIndex + tag.length(), nextIndex).trim(); - } - } - } - return null; - } - - protected String getClassInfoTag() { - if (javaDocsBuiltByVersion == JAVA_VERSION_16) { - return "

"; - } else { - return "

"; - } - } - protected String getOperInfoTag() { - if (javaDocsBuiltByVersion == JAVA_VERSION_16) { - return "
"; - } else { - return "
"; - } - } - protected String getOperLink() { - String operLink = " mdocs = new ConcurrentHashMap(); - public ClassDocs(String classDoc, String classInfo) { - this.classDoc = classDoc; - this.classInfo = classInfo; - } - - public String getClassDoc() { - return classDoc; - } - - public String getClassInfo() { - return classInfo; - } - - public MethodDocs getMethodDocs(Method method) { - return mdocs.get(method); - } - - public void addMethodDocs(Method method, MethodDocs doc) { - mdocs.putIfAbsent(method, doc); - } - } - - private static class MethodDocs { - private String methodInfo; - private List paramInfo = new LinkedList(); - private String responseInfo; - public MethodDocs(String methodInfo, List paramInfo, String responseInfo) { - this.methodInfo = methodInfo; - this.paramInfo = paramInfo; - this.responseInfo = responseInfo; - } - - public String getMethodInfo() { - return methodInfo; - } - - public List getParamInfo() { - return paramInfo; - } - - public String getResponseInfo() { - return responseInfo; - } - } -} http://git-wip-us.apache.org/repos/asf/cxf/blob/22a683b8/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/WadlGenerator.java ---------------------------------------------------------------------- diff --git a/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/WadlGenerator.java b/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/WadlGenerator.java index 5758aa0..a6c6756 100644 --- a/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/WadlGenerator.java +++ b/rt/rs/description/src/main/java/org/apache/cxf/jaxrs/model/wadl/WadlGenerator.java @@ -114,6 +114,8 @@ import org.apache.cxf.jaxrs.model.Parameter; import org.apache.cxf.jaxrs.model.ParameterType; import org.apache.cxf.jaxrs.model.ResourceTypes; import org.apache.cxf.jaxrs.model.URITemplate; +import org.apache.cxf.jaxrs.model.doc.DocumentationProvider; +import org.apache.cxf.jaxrs.model.doc.JavaDocProvider; import org.apache.cxf.jaxrs.provider.ServerProviderFactory; import org.apache.cxf.jaxrs.utils.AnnotationUtils; import org.apache.cxf.jaxrs.utils.ExceptionUtils; http://git-wip-us.apache.org/repos/asf/cxf/blob/22a683b8/rt/rs/description/src/test/java/org/apache/cxf/jaxrs/model/doc/JavaDocProviderTest.java ---------------------------------------------------------------------- diff --git a/rt/rs/description/src/test/java/org/apache/cxf/jaxrs/model/doc/JavaDocProviderTest.java b/rt/rs/description/src/test/java/org/apache/cxf/jaxrs/model/doc/JavaDocProviderTest.java new file mode 100644 index 0000000..94319e4 --- /dev/null +++ b/rt/rs/description/src/test/java/org/apache/cxf/jaxrs/model/doc/JavaDocProviderTest.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.jaxrs.model.doc; + +import org.apache.cxf.jaxrs.model.ClassResourceInfo; +import org.apache.cxf.jaxrs.model.OperationResourceInfo; +import org.apache.cxf.jaxrs.model.wadl.petstore.PetStore; +import org.apache.cxf.jaxrs.utils.ResourceUtils; + +import org.junit.Assert; +import org.junit.Test; + +public class JavaDocProviderTest extends Assert { + + @Test + public void testJava6Docs() throws Exception { + doTestJavaDocs("classpath:/javadocs/pet-store-javadoc16.jar", "1.6"); + } + + @Test + public void testJava7Docs() throws Exception { + doTestJavaDocs("classpath:/javadocs/pet-store-javadoc17.jar", "1.7"); + } + @Test + public void testJava8Docs() throws Exception { + doTestJavaDocs("classpath:/javadocs/pet-store-javadoc18.jar", "1.8"); + } + + private void doTestJavaDocs(String path, String version) throws Exception { + JavaDocProvider p = new JavaDocProvider(path); + p.setJavaDocsBuiltByVersion(version); + ClassResourceInfo cri = + ResourceUtils.createClassResourceInfo(PetStore.class, PetStore.class, true, true); + String classDoc = p.getClassDoc(cri); + assertEquals("The Pet Store", classDoc); + + boolean getStatus1Tested = false; + boolean getStatus2Tested = false; + boolean getStatus3Tested = false; + boolean noDocsTested = false; + for (OperationResourceInfo ori : cri.getMethodDispatcher().getOperationResourceInfos()) { + if ("getStatus1Param".equals(ori.getMethodToInvoke().getName())) { + testGetStatus1JavaDocs(p, ori); + getStatus1Tested = true; + } else if ("getStatus2Params".equals(ori.getMethodToInvoke().getName())) { + testGetStatus2JavaDocs(p, ori); + getStatus2Tested = true; + } else if ("getStatus3Params".equals(ori.getMethodToInvoke().getName())) { + testGetStatus3JavaDocs(p, ori); + getStatus3Tested = true; + } else if ("getBaseStatus".equals(ori.getMethodToInvoke().getName())) { + testOperWithNoJavaDocs(p, ori); + noDocsTested = true; + } + } + assertTrue(getStatus1Tested); + assertTrue(getStatus2Tested); + assertTrue(getStatus3Tested); + assertTrue(noDocsTested); + assertTrue(true); + } + + private void testOperWithNoJavaDocs(JavaDocProvider p, OperationResourceInfo ori) { + assertEquals(0, ori.getParameters().size()); + assertEquals("Return Pet Status with no params", p.getMethodDoc(ori)); + assertEquals("status", p.getMethodResponseDoc(ori)); + } + + private void testGetStatus1JavaDocs(JavaDocProvider p, OperationResourceInfo ori) { + assertEquals("Return Pet Status With 1 Param", p.getMethodDoc(ori)); + assertEquals(1, ori.getParameters().size()); + assertEquals("status", p.getMethodResponseDoc(ori)); + assertEquals("the pet id", p.getMethodParameterDoc(ori, 0)); + } + private void testGetStatus2JavaDocs(JavaDocProvider p, OperationResourceInfo ori) { + assertEquals("Return Pet Status with 2 params", p.getMethodDoc(ori)); + assertEquals(2, ori.getParameters().size()); + assertEquals("status", p.getMethodResponseDoc(ori)); + assertEquals("the pet id", p.getMethodParameterDoc(ori, 0)); + assertEquals("the query", p.getMethodParameterDoc(ori, 1)); + } + private void testGetStatus3JavaDocs(JavaDocProvider p, OperationResourceInfo ori) { + assertEquals("Return Pet Status With 3 Params", p.getMethodDoc(ori)); + assertEquals(3, ori.getParameters().size()); + assertEquals("status", p.getMethodResponseDoc(ori)); + assertEquals("the pet id", p.getMethodParameterDoc(ori, 0)); + assertEquals("the query", p.getMethodParameterDoc(ori, 1)); + assertEquals("the query2", p.getMethodParameterDoc(ori, 2)); + } + +} http://git-wip-us.apache.org/repos/asf/cxf/blob/22a683b8/rt/rs/description/src/test/java/org/apache/cxf/jaxrs/model/wadl/JavaDocProviderTest.java ---------------------------------------------------------------------- diff --git a/rt/rs/description/src/test/java/org/apache/cxf/jaxrs/model/wadl/JavaDocProviderTest.java b/rt/rs/description/src/test/java/org/apache/cxf/jaxrs/model/wadl/JavaDocProviderTest.java deleted file mode 100644 index f8f675e..0000000 --- a/rt/rs/description/src/test/java/org/apache/cxf/jaxrs/model/wadl/JavaDocProviderTest.java +++ /dev/null @@ -1,107 +0,0 @@ -/** - * 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.jaxrs.model.wadl; - -import org.apache.cxf.jaxrs.model.ClassResourceInfo; -import org.apache.cxf.jaxrs.model.OperationResourceInfo; -import org.apache.cxf.jaxrs.model.wadl.petstore.PetStore; -import org.apache.cxf.jaxrs.utils.ResourceUtils; - -import org.junit.Assert; -import org.junit.Test; - -public class JavaDocProviderTest extends Assert { - - @Test - public void testJava6Docs() throws Exception { - doTestJavaDocs("classpath:/javadocs/pet-store-javadoc16.jar", "1.6"); - } - - @Test - public void testJava7Docs() throws Exception { - doTestJavaDocs("classpath:/javadocs/pet-store-javadoc17.jar", "1.7"); - } - @Test - public void testJava8Docs() throws Exception { - doTestJavaDocs("classpath:/javadocs/pet-store-javadoc18.jar", "1.8"); - } - - private void doTestJavaDocs(String path, String version) throws Exception { - JavaDocProvider p = new JavaDocProvider(path); - p.setJavaDocsBuiltByVersion(version); - ClassResourceInfo cri = - ResourceUtils.createClassResourceInfo(PetStore.class, PetStore.class, true, true); - String classDoc = p.getClassDoc(cri); - assertEquals("The Pet Store", classDoc); - - boolean getStatus1Tested = false; - boolean getStatus2Tested = false; - boolean getStatus3Tested = false; - boolean noDocsTested = false; - for (OperationResourceInfo ori : cri.getMethodDispatcher().getOperationResourceInfos()) { - if ("getStatus1Param".equals(ori.getMethodToInvoke().getName())) { - testGetStatus1JavaDocs(p, ori); - getStatus1Tested = true; - } else if ("getStatus2Params".equals(ori.getMethodToInvoke().getName())) { - testGetStatus2JavaDocs(p, ori); - getStatus2Tested = true; - } else if ("getStatus3Params".equals(ori.getMethodToInvoke().getName())) { - testGetStatus3JavaDocs(p, ori); - getStatus3Tested = true; - } else if ("getBaseStatus".equals(ori.getMethodToInvoke().getName())) { - testOperWithNoJavaDocs(p, ori); - noDocsTested = true; - } - } - assertTrue(getStatus1Tested); - assertTrue(getStatus2Tested); - assertTrue(getStatus3Tested); - assertTrue(noDocsTested); - assertTrue(true); - } - - private void testOperWithNoJavaDocs(JavaDocProvider p, OperationResourceInfo ori) { - assertEquals(0, ori.getParameters().size()); - assertEquals("Return Pet Status with no params", p.getMethodDoc(ori)); - assertEquals("status", p.getMethodResponseDoc(ori)); - } - - private void testGetStatus1JavaDocs(JavaDocProvider p, OperationResourceInfo ori) { - assertEquals("Return Pet Status With 1 Param", p.getMethodDoc(ori)); - assertEquals(1, ori.getParameters().size()); - assertEquals("status", p.getMethodResponseDoc(ori)); - assertEquals("the pet id", p.getMethodParameterDoc(ori, 0)); - } - private void testGetStatus2JavaDocs(JavaDocProvider p, OperationResourceInfo ori) { - assertEquals("Return Pet Status with 2 params", p.getMethodDoc(ori)); - assertEquals(2, ori.getParameters().size()); - assertEquals("status", p.getMethodResponseDoc(ori)); - assertEquals("the pet id", p.getMethodParameterDoc(ori, 0)); - assertEquals("the query", p.getMethodParameterDoc(ori, 1)); - } - private void testGetStatus3JavaDocs(JavaDocProvider p, OperationResourceInfo ori) { - assertEquals("Return Pet Status With 3 Params", p.getMethodDoc(ori)); - assertEquals(3, ori.getParameters().size()); - assertEquals("status", p.getMethodResponseDoc(ori)); - assertEquals("the pet id", p.getMethodParameterDoc(ori, 0)); - assertEquals("the query", p.getMethodParameterDoc(ori, 1)); - assertEquals("the query2", p.getMethodParameterDoc(ori, 2)); - } - -}