This is an automated email from the ASF dual-hosted git repository. reta pushed a commit to branch 3.5.x-fixes in repository https://gitbox.apache.org/repos/asf/cxf.git
commit ae2e6c30175ba30086a7375827c6843a91b2aff4 Author: Francesco Chicchiriccò <[email protected]> AuthorDate: Tue Jun 13 08:39:36 2023 +0200 [CXF-8886] Support scraping javadocs generated by Java 17 (#1299) --- .../cxf/jaxrs/model/doc/JavaDocProvider.java | 102 ++++++++++++--------- .../cxf/jaxrs/model/doc/JavaDocProviderTest.java | 33 +++++-- .../cxf/jaxrs/model/wadl/petstore/PetStore.java | 27 +++--- ...tore-javadoc16.jar => pet-store-javadoc1.6.jar} | Bin ...tore-javadoc17.jar => pet-store-javadoc1.7.jar} | Bin ...tore-javadoc18.jar => pet-store-javadoc1.8.jar} | Bin .../resources/javadocs/pet-store-javadoc11.jar | Bin 0 -> 3432 bytes .../resources/javadocs/pet-store-javadoc17.jar | Bin 3601 -> 3462 bytes 8 files changed, 95 insertions(+), 67 deletions(-) diff --git a/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/doc/JavaDocProvider.java b/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/doc/JavaDocProvider.java index e556702300..d7d620cf18 100644 --- a/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/doc/JavaDocProvider.java +++ b/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/doc/JavaDocProvider.java @@ -16,7 +16,6 @@ * specific language governing permissions and limitations * under the License. */ - package org.apache.cxf.jaxrs.model.doc; import java.io.InputStream; @@ -38,14 +37,24 @@ 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 final ConcurrentHashMap<String, ClassDocs> docs = new ConcurrentHashMap<>(); - private double javaDocsBuiltByVersion = JAVA_VERSION; + protected static final double JAVA_VERSION = getVersion(); + + protected static final double JAVA_VERSION_1_6 = 1.6D; + + protected static final double JAVA_VERSION_1_7 = 1.7D; + + protected static final double JAVA_VERSION_1_8 = 1.8D; + + protected static final double JAVA_VERSION_11 = 11.0D; + + protected static final double JAVA_VERSION_17 = 17.0D; + + protected ClassLoader javaDocLoader; + + protected final ConcurrentHashMap<String, ClassDocs> docs = new ConcurrentHashMap<>(); + + protected double javaDocsBuiltByVersion = JAVA_VERSION; public JavaDocProvider() { } @@ -78,8 +87,8 @@ public class JavaDocProvider implements DocumentationProvider { String version = System.getProperty("java.version"); try { return Double.parseDouble(version.substring(0, 3)); - } catch (Exception ex) { - return JAVA_VERSION_16; + } catch (NumberFormatException ex) { + return JAVA_VERSION_1_6; } } @@ -143,7 +152,7 @@ public class JavaDocProvider implements DocumentationProvider { return null; } - private Class<?> getPathAnnotatedClass(Class<?> cls) { + protected Class<?> getPathAnnotatedClass(Class<?> cls) { if (cls.getAnnotation(Path.class) != null) { return cls; } @@ -158,7 +167,7 @@ public class JavaDocProvider implements DocumentationProvider { return cls; } - private ClassDocs getClassDocInternal(Class<?> cls) throws Exception { + protected ClassDocs getClassDocInternal(Class<?> cls) throws Exception { Class<?> annotatedClass = getPathAnnotatedClass(cls); String resource = annotatedClass.getName().replace(".", "/") + ".html"; ClassDocs classDocs = docs.get(resource); @@ -174,7 +183,7 @@ public class JavaDocProvider implements DocumentationProvider { if (index != -1) { String classInfoTag = getClassInfoTag(); String classInfo = getJavaDocText(doc, classInfoTag, - "Method Summary", index + classMarker.length()); + "Method Summary", index + classMarker.length()); classDocs = new ClassDocs(doc, classInfo); docs.putIfAbsent(resource, classDocs); } @@ -183,8 +192,7 @@ public class JavaDocProvider implements DocumentationProvider { return classDocs; } - - private MethodDocs getOperationDocInternal(OperationResourceInfo ori) throws Exception { + protected MethodDocs getOperationDocInternal(OperationResourceInfo ori) throws Exception { Method method = ori.getAnnotatedMethod() == null ? ori.getMethodToInvoke() : ori.getAnnotatedMethod(); @@ -200,8 +208,7 @@ public class JavaDocProvider implements DocumentationProvider { int operMarkerIndex = classDoc.getClassDoc().indexOf(operMarker); while (operMarkerIndex != -1) { int startOfOpSigIndex = operMarkerIndex + operMarker.length(); - int endOfOpSigIndex = classDoc.getClassDoc().indexOf(getOperationMarkerClose(), - startOfOpSigIndex); + int endOfOpSigIndex = classDoc.getClassDoc().indexOf(getOperationMarkerClose(), startOfOpSigIndex); int paramLen = method.getParameterTypes().length; if (endOfOpSigIndex == startOfOpSigIndex && paramLen == 0) { break; @@ -215,8 +222,7 @@ public class JavaDocProvider implements DocumentationProvider { } } } - operMarkerIndex = classDoc.getClassDoc().indexOf(operMarker, - operMarkerIndex + operMarker.length()); + operMarkerIndex = classDoc.getClassDoc().indexOf(operMarker, operMarkerIndex + operMarker.length()); } if (operMarkerIndex == -1) { @@ -238,7 +244,7 @@ public class JavaDocProvider implements DocumentationProvider { int paramIndex = operDoc.indexOf("Parameters:"); if (paramIndex != -1 && (nextOpIndex == -1 || paramIndex < nextOpIndex)) { String paramString = returnsIndex == -1 ? operDoc.substring(paramIndex) - : operDoc.substring(paramIndex, returnsIndex); + : operDoc.substring(paramIndex, returnsIndex); String codeTag = getCodeTag(); @@ -269,9 +275,7 @@ public class JavaDocProvider implements DocumentationProvider { return mDocs; } - - - private String getJavaDocText(String doc, String tag, String notAfterTag, int index) { + protected 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); @@ -286,13 +290,14 @@ public class JavaDocProvider implements DocumentationProvider { } protected String getClassInfoTag() { - if (javaDocsBuiltByVersion == JAVA_VERSION_16) { + if (javaDocsBuiltByVersion == JAVA_VERSION_1_6) { return "<P>"; } return "<div class=\"block\">"; } + protected String getOperInfoTag() { - if (javaDocsBuiltByVersion == JAVA_VERSION_16) { + if (javaDocsBuiltByVersion == JAVA_VERSION_1_6) { return "<DD>"; } return "<div class=\"block\">"; @@ -300,40 +305,45 @@ public class JavaDocProvider implements DocumentationProvider { protected String getOperLink() { String operLink = "<A NAME=\""; - return javaDocsBuiltByVersion == JAVA_VERSION_16 + return javaDocsBuiltByVersion == JAVA_VERSION_1_6 ? operLink - : javaDocsBuiltByVersion <= JAVA_VERSION_18 + : javaDocsBuiltByVersion <= JAVA_VERSION_1_8 ? operLink.toLowerCase() - : "<a id=\""; + : javaDocsBuiltByVersion <= JAVA_VERSION_11 + ? "<a id=\"" + : "<section class=\"detail\" id=\""; } protected String getResponseMarker() { String tag = "<DD>"; - return javaDocsBuiltByVersion == JAVA_VERSION_16 ? tag : tag.toLowerCase(); + return javaDocsBuiltByVersion == JAVA_VERSION_1_6 ? tag : tag.toLowerCase(); } protected String getCodeTag() { String tag = "</CODE>"; - return javaDocsBuiltByVersion == JAVA_VERSION_16 ? tag : tag.toLowerCase(); + return javaDocsBuiltByVersion == JAVA_VERSION_1_6 ? tag : tag.toLowerCase(); } protected String getOperationMarkerOpen() { - return javaDocsBuiltByVersion == JAVA_VERSION_18 ? "-" : "("; + return javaDocsBuiltByVersion == JAVA_VERSION_1_8 ? "-" : "("; } + protected String getOperationMarkerClose() { - return javaDocsBuiltByVersion == JAVA_VERSION_18 ? "-\"" : ")"; + return javaDocsBuiltByVersion == JAVA_VERSION_1_8 ? "-\"" : ")"; } + protected String getOperationParamSeparator() { - return javaDocsBuiltByVersion == JAVA_VERSION_18 ? "-" : ","; - } - public void setJavaDocsBuiltByVersion(String version) { - javaDocsBuiltByVersion = Double.valueOf(version); + return javaDocsBuiltByVersion == JAVA_VERSION_1_8 ? "-" : ","; } - private static class ClassDocs { - private final String classDoc; - private final String classInfo; - private final ConcurrentHashMap<Method, MethodDocs> mdocs = new ConcurrentHashMap<>(); + protected static class ClassDocs { + + protected final String classDoc; + + protected final String classInfo; + + protected final ConcurrentHashMap<Method, MethodDocs> mdocs = new ConcurrentHashMap<>(); + ClassDocs(String classDoc, String classInfo) { this.classDoc = classDoc; this.classInfo = classInfo; @@ -356,10 +366,14 @@ public class JavaDocProvider implements DocumentationProvider { } } - private static class MethodDocs { - private final String methodInfo; - private final List<String> paramInfo; - private final String responseInfo; + protected static class MethodDocs { + + protected final String methodInfo; + + protected final List<String> paramInfo; + + protected final String responseInfo; + MethodDocs(String methodInfo, List<String> paramInfo, String responseInfo) { this.methodInfo = methodInfo; this.paramInfo = paramInfo; diff --git a/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/model/doc/JavaDocProviderTest.java b/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/model/doc/JavaDocProviderTest.java index 7268e33087..effac41253 100644 --- a/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/model/doc/JavaDocProviderTest.java +++ b/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/model/doc/JavaDocProviderTest.java @@ -18,6 +18,8 @@ */ package org.apache.cxf.jaxrs.model.doc; +import java.lang.reflect.Field; + import org.apache.cxf.jaxrs.model.ClassResourceInfo; import org.apache.cxf.jaxrs.model.OperationResourceInfo; import org.apache.cxf.jaxrs.model.wadl.petstore.PetStore; @@ -32,23 +34,37 @@ public class JavaDocProviderTest { @Test public void testJava6Docs() throws Exception { - doTestJavaDocs("classpath:/javadocs/pet-store-javadoc16.jar", "1.6"); + doTestJavaDocs("classpath:/javadocs/pet-store-javadoc1.6.jar", JavaDocProvider.JAVA_VERSION_1_6); } @Test public void testJava7Docs() throws Exception { - doTestJavaDocs("classpath:/javadocs/pet-store-javadoc17.jar", "1.7"); + doTestJavaDocs("classpath:/javadocs/pet-store-javadoc1.7.jar", JavaDocProvider.JAVA_VERSION_1_7); } + @Test public void testJava8Docs() throws Exception { - doTestJavaDocs("classpath:/javadocs/pet-store-javadoc18.jar", "1.8"); + doTestJavaDocs("classpath:/javadocs/pet-store-javadoc1.8.jar", JavaDocProvider.JAVA_VERSION_1_8); } - private void doTestJavaDocs(String path, String version) throws Exception { + @Test + public void testJava11Docs() throws Exception { + doTestJavaDocs("classpath:/javadocs/pet-store-javadoc11.jar", JavaDocProvider.JAVA_VERSION_11); + } + + @Test + public void testJava17Docs() throws Exception { + doTestJavaDocs("classpath:/javadocs/pet-store-javadoc17.jar", JavaDocProvider.JAVA_VERSION_17); + } + + private void doTestJavaDocs(String path, double version) throws Exception { JavaDocProvider p = new JavaDocProvider(path); - p.setJavaDocsBuiltByVersion(version); - ClassResourceInfo cri = - ResourceUtils.createClassResourceInfo(PetStore.class, PetStore.class, true, true); + + Field javaDocsBuiltByVersion = JavaDocProvider.class.getDeclaredField("javaDocsBuiltByVersion"); + javaDocsBuiltByVersion.setAccessible(true); + javaDocsBuiltByVersion.set(p, version); + + ClassResourceInfo cri = ResourceUtils.createClassResourceInfo(PetStore.class, PetStore.class, true, true); String classDoc = p.getClassDoc(cri); assertEquals("The Pet Store", classDoc); @@ -89,6 +105,7 @@ public class JavaDocProviderTest { 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()); @@ -96,6 +113,7 @@ public class JavaDocProviderTest { 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()); @@ -104,5 +122,4 @@ public class JavaDocProviderTest { assertEquals("the query", p.getMethodParameterDoc(ori, 1)); assertEquals("the query2", p.getMethodParameterDoc(ori, 2)); } - } diff --git a/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/model/wadl/petstore/PetStore.java b/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/model/wadl/petstore/PetStore.java index 06d58c2d2a..e576910861 100644 --- a/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/model/wadl/petstore/PetStore.java +++ b/rt/frontend/jaxrs/src/test/java/org/apache/cxf/jaxrs/model/wadl/petstore/PetStore.java @@ -16,7 +16,6 @@ * specific language governing permissions and limitations * under the License. */ - package org.apache.cxf.jaxrs.model.wadl.petstore; import javax.ws.rs.GET; @@ -34,24 +33,21 @@ public class PetStore { public static final String CLOSED = "The Pet Store is closed"; - public PetStore() { - } - - @GET - @Produces("text/plain") /** * Return Pet Status with no params * * @return status * @throws Exception */ + @GET + @Produces("text/plain") public Response getBaseStatus() throws Exception { - return Response.ok(CLOSED).build(); } /** * Return Pet Status with 2 params + * * @param petId the pet id * @param query the query * @return status @@ -60,14 +56,16 @@ public class PetStore { @GET @Path("/petstore/pets/{petId}/") @Produces("text/xml") - public Response getStatus2Params(@PathParam("petId") String petId, - @QueryParam("query") String query) throws Exception { + public Response getStatus2Params( + @PathParam("petId") String petId, + @QueryParam("query") String query) throws Exception { return Response.ok(CLOSED).build(); } /** * Return Pet Status With 1 Param + * * @param petId the pet id * @return status * @throws Exception @@ -76,13 +74,12 @@ public class PetStore { @Path("/petstore/pets/id/{petId}/") @Produces("text/xml") public Response getStatus1Param(@PathParam("petId") String petId) throws Exception { - return Response.ok(CLOSED).build(); } - /** * Return Pet Status With 3 Params + * * @param petId the pet id * @param query the query * @param query2 the query2 @@ -92,11 +89,11 @@ public class PetStore { @GET @Path("/petstore/pets/{petId}/") @Produces("text/xml") - public Response getStatus3Params(@PathParam("petId") String petId, - @QueryParam("query") String query, - @QueryParam("query2") String query2) throws Exception { + public Response getStatus3Params( + @PathParam("petId") String petId, + @QueryParam("query") String query, + @QueryParam("query2") String query2) throws Exception { return Response.ok(CLOSED).build(); } - } diff --git a/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc16.jar b/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc1.6.jar similarity index 100% rename from rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc16.jar rename to rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc1.6.jar diff --git a/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc17.jar b/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc1.7.jar similarity index 100% copy from rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc17.jar copy to rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc1.7.jar diff --git a/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc18.jar b/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc1.8.jar similarity index 100% rename from rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc18.jar rename to rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc1.8.jar diff --git a/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc11.jar b/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc11.jar new file mode 100644 index 0000000000..8e1eb17c84 Binary files /dev/null and b/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc11.jar differ diff --git a/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc17.jar b/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc17.jar index d49a58d5ce..fa4ae03305 100644 Binary files a/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc17.jar and b/rt/frontend/jaxrs/src/test/resources/javadocs/pet-store-javadoc17.jar differ
