diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4349a0f..352f837 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -8,9 +8,6 @@ updates: ignore: # maven core artifacts are provided by the running maven, do not update to prevent consuming something unavailable - dependency-name: "org.apache.maven:*" - # 1.7 and later require Java 11, which this repository does not yet support - - dependency-name: "io.jenkins.tools.incrementals:git-changelist-maven-extension" - versions: [">=1.7"] - package-ecosystem: "github-actions" directory: "/" schedule: diff --git a/.github/workflows/cd.yaml b/.github/workflows/cd.yaml index 4110861..f371773 100644 --- a/.github/workflows/cd.yaml +++ b/.github/workflows/cd.yaml @@ -1,4 +1,4 @@ -# Switch to https://raw.githubusercontent.com/jenkinsci/.github/master/workflow-templates/cd.yaml once we support Java 11 +# Note: additional setup is required, see https://www.jenkins.io/redirect/continuous-delivery-of-plugins name: cd on: @@ -7,53 +7,13 @@ on: types: - completed -jobs: - validate: - runs-on: ubuntu-latest - outputs: - should_release: ${{ steps.verify-ci-status.outputs.result == 'success' && steps.interesting-categories.outputs.interesting == 'true' }} - steps: - - name: Verify CI status - uses: jenkins-infra/verify-ci-status-action@v1.2.2 - id: verify-ci-status - with: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - output_result: true - - - name: Release Drafter - uses: release-drafter/release-drafter@v5 - if: steps.verify-ci-status.outputs.result == 'success' - with: - name: next - tag: next - version: next - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} +permissions: + checks: read + contents: write - - name: Check interesting categories - uses: jenkins-infra/interesting-category-action@v1.2.1 - id: interesting-categories - if: steps.verify-ci-status.outputs.result == 'success' - with: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - release: - runs-on: ubuntu-latest - needs: [validate] - if: needs.validate.outputs.should_release == 'true' - steps: - - name: Check out - uses: actions/checkout@v3 - with: - fetch-depth: 0 - - name: Set up JDK 8 - uses: actions/setup-java@v3 - with: - distribution: temurin - java-version: 8 - - name: Release - uses: jenkins-infra/jenkins-maven-cd-action@v1.3.3 - with: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }} - MAVEN_TOKEN: ${{ secrets.MAVEN_TOKEN }} +jobs: + maven-cd: + uses: jenkins-infra/github-reusable-workflows/.github/workflows/maven-cd.yml@v1 + secrets: + MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }} + MAVEN_TOKEN: ${{ secrets.MAVEN_TOKEN }} diff --git a/.github/workflows/site.yml b/.github/workflows/site.yml index e79b8c7..883c04b 100644 --- a/.github/workflows/site.yml +++ b/.github/workflows/site.yml @@ -28,7 +28,7 @@ jobs: uses: actions/setup-java@v3 with: distribution: 'temurin' - java-version: '8' + java-version: '11' cache: 'maven' - name: Setup Pages uses: actions/configure-pages@v3 diff --git a/.mvn/extensions.xml b/.mvn/extensions.xml index 90787cb..1f36364 100644 --- a/.mvn/extensions.xml +++ b/.mvn/extensions.xml @@ -2,6 +2,6 @@ io.jenkins.tools.incrementals git-changelist-maven-extension - 1.6 + 1.7 diff --git a/Jenkinsfile b/Jenkinsfile index addd64e..998e5dd 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -4,6 +4,6 @@ * allowing one to test against multiple Jenkins versions. */ buildPlugin(useContainerAgent: true, configurations: [ - [ platform: 'linux', jdk: '8' ], - [ platform: 'windows', jdk: '8' ], + [platform: 'linux', jdk: 17], + [platform: 'windows', jdk: 11], ]) diff --git a/jellydoc-maven-plugin/pom.xml b/jellydoc-maven-plugin/pom.xml index ffa744c..28fb2c2 100644 --- a/jellydoc-maven-plugin/pom.xml +++ b/jellydoc-maven-plugin/pom.xml @@ -30,9 +30,7 @@ - org.apache.commons:commons-lang3 org.slf4j:slf4j-api - xerces:xercesImpl @@ -40,28 +38,6 @@ - - - org.codehaus.mojo - flatten-maven-plugin - - - flatten - - flatten - - process-resources - - - keep - - - - - @@ -203,25 +179,6 @@ - - - - jdk-8-and-below - - (,1.8] - - - - com.sun - tools - 1.8.0 - system - ${java.home}/../lib/tools.jar - - - - - diff --git a/jellydoc-maven-plugin/src/main/java/org/jvnet/maven/jellydoc/JellydocMojo.java b/jellydoc-maven-plugin/src/main/java/org/jvnet/maven/jellydoc/JellydocMojo.java index 83650db..04b1615 100644 --- a/jellydoc-maven-plugin/src/main/java/org/jvnet/maven/jellydoc/JellydocMojo.java +++ b/jellydoc-maven-plugin/src/main/java/org/jvnet/maven/jellydoc/JellydocMojo.java @@ -159,7 +159,7 @@ public void execute() throws MojoExecutionException { d.setPath(docletPath); // debug support -// javadoc.createArg().setLine("-J-Xrunjdwp:transport=dt_socket,server=y,address=8000"); +// javadoc.createArg().setLine("-J-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:8000"); javadoc.execute(); diff --git a/jellydoc-maven-plugin/src/main/java/org/jvnet/maven/jellydoc/TagXMLDoclet.java b/jellydoc-maven-plugin/src/main/java/org/jvnet/maven/jellydoc/TagXMLDoclet.java index fc77fbf..3e7a9d7 100644 --- a/jellydoc-maven-plugin/src/main/java/org/jvnet/maven/jellydoc/TagXMLDoclet.java +++ b/jellydoc-maven-plugin/src/main/java/org/jvnet/maven/jellydoc/TagXMLDoclet.java @@ -15,19 +15,13 @@ */ package org.jvnet.maven.jellydoc; -import com.sun.javadoc.AnnotationDesc; -import com.sun.javadoc.AnnotationDesc.ElementValuePair; -import com.sun.javadoc.ClassDoc; -import com.sun.javadoc.Doc; -import com.sun.javadoc.DocErrorReporter; -import com.sun.javadoc.Doclet; -import com.sun.javadoc.MethodDoc; -import com.sun.javadoc.PackageDoc; -import com.sun.javadoc.Parameter; -import com.sun.javadoc.ProgramElementDoc; -import com.sun.javadoc.RootDoc; -import com.sun.javadoc.SeeTag; -import com.sun.javadoc.Tag; +import com.sun.source.doctree.BlockTagTree; +import com.sun.source.doctree.DocCommentTree; +import com.sun.source.doctree.DocTree; +import com.sun.source.doctree.LinkTree; +import com.sun.source.doctree.LiteralTree; +import com.sun.source.doctree.ReferenceTree; +import com.sun.source.util.DocTrees; import com.sun.xml.txw2.TXW; import com.sun.xml.txw2.TypedXmlWriter; import com.sun.xml.txw2.output.StreamSerializer; @@ -47,9 +41,27 @@ import java.io.StringReader; import java.lang.annotation.Annotation; import java.util.Arrays; -import java.util.HashSet; +import java.util.List; +import java.util.Locale; +import java.util.Map; import java.util.Set; import java.util.Stack; +import javax.lang.model.SourceVersion; +import javax.lang.model.element.AnnotationMirror; +import javax.lang.model.element.AnnotationValue; +import javax.lang.model.element.Element; +import javax.lang.model.element.ExecutableElement; +import javax.lang.model.element.Modifier; +import javax.lang.model.element.PackageElement; +import javax.lang.model.element.TypeElement; +import javax.lang.model.element.VariableElement; +import javax.lang.model.type.DeclaredType; +import javax.lang.model.type.TypeMirror; +import javax.lang.model.util.ElementFilter; +import javax.tools.Diagnostic; +import jdk.javadoc.doclet.Doclet; +import jdk.javadoc.doclet.DocletEnvironment; +import jdk.javadoc.doclet.Reporter; /** * Main Doclet class to generate Tag Library ML. @@ -61,14 +73,16 @@ // #### somehow we need to handle taglib inheritence... -public class TagXMLDoclet extends Doclet { +public class TagXMLDoclet implements Doclet { + + private DocTrees docTrees; + private Reporter reporter; private String targetFileName = null; private String encodingFormat; - public TagXMLDoclet (RootDoc root) throws Exception + private void main(DocletEnvironment root) throws Exception { - readOptions(root); File targetFile = new File(targetFileName); targetFile.getParentFile().mkdirs(); FileOutputStream writer = new FileOutputStream(targetFileName); @@ -78,32 +92,54 @@ public TagXMLDoclet (RootDoc root) throws Exception tw.commit(); } + @Override + public void init(Locale locale, Reporter reporter) { + this.reporter = reporter; + } + + @Override + public String getName() { + return "TagXMLDoclet"; + } + + @Override + public Set getSupportedOptions() { + return Set.of( + new Option("-d", "target directory", "", 1) { + @Override + public boolean process(String opt, List args) { + targetFileName = args.get(0) + "/taglib.xml"; + return true; + } + }); + } + + @Override + public SourceVersion getSupportedSourceVersion() { + return SourceVersion.latest(); + } + /** * Generates the xml for the tag libraries */ - private void javadocXML(RootDoc root, Tags tw) throws SAXException { - Set pkgs = new HashSet<>(); - for (ClassDoc c : root.specifiedClasses()) - pkgs.add(c.containingPackage()); - pkgs.addAll(Arrays.asList(root.specifiedPackages())); + private void javadocXML(DocletEnvironment root, Tags tw) throws SAXException { + docTrees = root.getDocTrees(); // Generate for packages. - for (PackageDoc pkg : pkgs) + for (PackageElement pkg : ElementFilter.packagesIn(root.getIncludedElements())) packageXML(pkg,tw); } /** * Generates doc for a tag library */ - private void packageXML(PackageDoc packageDoc, Tags tw) throws SAXException { + private void packageXML(PackageElement packageDoc, Tags tw) throws SAXException { - System.out.println( "processing package: " + packageDoc.name()); - - ClassDoc[] classArray = packageDoc.ordinaryClasses(); + System.out.println( "processing package: " + packageDoc.getQualifiedName()); // lets see if we find a Tag boolean foundTag = false; - for (ClassDoc classDoc : classArray) { + for (TypeElement classDoc : ElementFilter.typesIn(packageDoc.getEnclosedElements())) { if (isTag(classDoc)) { foundTag = true; break; @@ -113,16 +149,16 @@ private void packageXML(PackageDoc packageDoc, Tags tw) throws SAXException { return; Library library = tw.library(); - library.name(packageDoc.name()); + library.name(packageDoc.getQualifiedName().toString()); - String name = packageDoc.name(); + String name = packageDoc.getQualifiedName().toString(); int idx = name.lastIndexOf('.'); if ( idx > 0 ) { name = name.substring(idx+1); } library.prefix(name); - String uri = findUri(packageDoc.annotations()); + String uri = findUri(packageDoc.getAnnotationMirrors()); if(uri==null) uri = "jelly:" + name; // fallback @@ -132,50 +168,72 @@ private void packageXML(PackageDoc packageDoc, Tags tw) throws SAXException { docXML(packageDoc,library); // generate tags - for (ClassDoc c : classArray) { - if (isTag(c) && !c.isAbstract()) { + for (TypeElement c : ElementFilter.typesIn(packageDoc.getEnclosedElements())) { + if (isTag(c) && !c.getModifiers().contains(Modifier.ABSTRACT)) { tagXML(c,library.tag()); } } } - private String findUri(AnnotationDesc[] an) { - for (AnnotationDesc a : an) - if(a.annotationType().qualifiedName().equals(TagLibUri.class.getName())) - for (ElementValuePair e : a.elementValues()) - if(e.element().name().equals("value")) - return e.value().value().toString(); + private String findUri(List an) { + for (AnnotationMirror a : an) { + if (a.getAnnotationType().asElement() instanceof TypeElement + && ((TypeElement) a.getAnnotationType().asElement()) + .getQualifiedName() + .toString() + .equals(TagLibUri.class.getName())) { + for (Map.Entry e : + a.getElementValues().entrySet()) { + if (e.getKey().getSimpleName().toString().equals("value")) { + return e.getValue().toString(); + } + } + } + } return null; } - private boolean has(ProgramElementDoc doc, Class type) { - for (AnnotationDesc a : doc.annotations()) - if(a.annotationType().qualifiedName().equals(type.getName())) + private boolean has(Element doc, Class type) { + for (AnnotationMirror a : doc.getAnnotationMirrors()) { + if (a.getAnnotationType().asElement() instanceof TypeElement + && ((TypeElement) a.getAnnotationType().asElement()) + .getQualifiedName() + .toString() + .equals(type.getName())) { return true; + } + } return false; } /** * @return true if this class is a Jelly Tag */ - private boolean isTag(ClassDoc classDoc) { - ClassDoc[] interfaceArray = classDoc.interfaces(); - for (ClassDoc i : interfaceArray) { - String name = i.qualifiedName(); - if ("org.apache.commons.jelly.Tag".equals(name)) { + private boolean isTag(TypeElement classDoc) { + List interfaceArray = classDoc.getInterfaces(); + for (TypeMirror i : interfaceArray) { + if ("org.apache.commons.jelly.Tag".equals(i.toString())) { return true; } } - ClassDoc base = classDoc.superclass(); - return base != null && isTag(base); + TypeMirror base = classDoc.getSuperclass(); + if (base instanceof DeclaredType) { + DeclaredType declaredType = (DeclaredType) base; + Element element = declaredType.asElement(); + if (element instanceof TypeElement) { + TypeElement typeElement = (TypeElement) element; + return isTag(typeElement); + } + } + return false; } /** * Generates doc for a tag */ - private void tagXML(ClassDoc classDoc, org.jvnet.maven.jellydoc.Tag tag) throws SAXException { - tag.className(classDoc.name()); - String name = classDoc.name(); + private void tagXML(TypeElement classDoc, org.jvnet.maven.jellydoc.Tag tag) throws SAXException { + String name = classDoc.getSimpleName().toString(); + tag.className(name); if ( name.endsWith( "Tag" ) ) { name = name.substring(0, name.length() - 3 ); } @@ -198,14 +256,18 @@ private void tagXML(ClassDoc classDoc, org.jvnet.maven.jellydoc.Tag tag) throws /** * Generates doc for a tag property */ - private void propertiesXML(ClassDoc classDoc, org.jvnet.maven.jellydoc.Tag tag) throws SAXException { - MethodDoc[] methodArray = classDoc.methods(); - for (MethodDoc m : methodArray) { + private void propertiesXML(TypeElement classDoc, org.jvnet.maven.jellydoc.Tag tag) throws SAXException { + for (ExecutableElement m : ElementFilter.methodsIn(classDoc.getEnclosedElements())) { propertyXML(m,tag); } - ClassDoc base = classDoc.superclass(); - if ( base != null ) { - propertiesXML( base, tag); + TypeMirror base = classDoc.getSuperclass(); + if (base instanceof DeclaredType) { + DeclaredType declaredType = (DeclaredType) base; + Element element = declaredType.asElement(); + if (element instanceof TypeElement) { + TypeElement typeElement = (TypeElement) element; + propertiesXML(typeElement, tag); + } } } @@ -213,19 +275,20 @@ private void propertiesXML(ClassDoc classDoc, org.jvnet.maven.jellydoc.Tag tag) /** * Generates doc for a tag property */ - private void propertyXML(MethodDoc methodDoc, org.jvnet.maven.jellydoc.Tag tag) throws SAXException { - if ( ! methodDoc.isPublic() || methodDoc.isStatic() ) { + private void propertyXML(ExecutableElement methodDoc, org.jvnet.maven.jellydoc.Tag tag) throws SAXException { + if (!methodDoc.getModifiers().contains(Modifier.PUBLIC) + || methodDoc.getModifiers().contains(Modifier.STATIC)) { return; } - String name = methodDoc.name(); + String name = methodDoc.getSimpleName().toString(); if ( ! name.startsWith( "set" ) ) { return; } - Parameter[] parameterArray = methodDoc.parameters(); - if ( parameterArray == null || parameterArray.length != 1 ) { + List parameterArray = methodDoc.getParameters(); + if ( parameterArray == null || parameterArray.size() != 1 ) { return; } - Parameter parameter = parameterArray[0]; + VariableElement parameter = parameterArray.get(0); name = name.substring(3); name = Introspector.decapitalize(name); @@ -236,7 +299,7 @@ private void propertyXML(MethodDoc methodDoc, org.jvnet.maven.jellydoc.Tag tag) Attribute a = tag.attribute(); a.name(name); - a.type(parameter.typeName()); + a.type(parameter.asType().toString()); if(has(methodDoc, Required.class)) a.use("required"); @@ -249,45 +312,41 @@ private void propertyXML(MethodDoc methodDoc, org.jvnet.maven.jellydoc.Tag tag) /** * Generates doc for element "doc" */ - private void docXML(Doc doc, Item w) throws SAXException { + private void docXML(Element doc, Item w) throws SAXException { TypedXmlWriter d = w.doc(); - // handle the "comment" part, including {@link} tags - { - for (Tag tag : doc.inlineTags()) { + DocCommentTree docCommentTree = docTrees.getDocCommentTree(doc); + if (docCommentTree != null) { + StringBuilder sb = new StringBuilder(); + // handle the "comment" part, including {@link} tags + for (DocTree bodyTree : docCommentTree.getFullBody()) { // if tags[i] is an @link tag - if (tag instanceof SeeTag) { - String label = ((SeeTag) tag).label(); + if (bodyTree instanceof LinkTree) { + LinkTree linkTree = (LinkTree) bodyTree; + List label = linkTree.getLabel(); // if the label is null or empty, use the class#member part of the link - if (null == label || "".equals(label)) { - StringBuilder buf = new StringBuilder(); - String className = ((SeeTag) tag).referencedClassName(); - if ("".equals(className)) { - className = null; - } - String memberName = ((SeeTag) tag).referencedMemberName(); - if ("".equals(memberName)) { - memberName = null; - } - if (null != className) { - buf.append(className); - if (null != memberName) { - buf.append("."); - } + if (label == null || label.isEmpty()) { + ReferenceTree reference = linkTree.getReference(); + sb.append(reference.toString()); + } else { + for (DocTree labelElement : label) { + sb.append(labelElement.toString()); } - if (null != memberName) { - buf.append(memberName); - } - label = buf.toString(); } - parseHTML(label,d); + } else if (bodyTree instanceof LiteralTree) { + sb.append(((LiteralTree) bodyTree).getBody().getBody()); } else { - parseHTML(tag.text(),d); + sb.append(bodyTree.toString()); + } + } + parseHTML(sb.toString(), d); + + // handle the "tags" part + for (DocTree tag : docCommentTree.getBlockTags()) { + if (tag instanceof BlockTagTree) { + javadocTagXML((BlockTagTree) tag, w); } } } - // handle the "tags" part - for (Tag tag : doc.tags()) - javadocTagXML(tag,w); } protected void parseHTML(String text, final TypedXmlWriter d) throws SAXException { @@ -340,15 +399,23 @@ protected boolean validDocElementName(String name) { /** * Generates doc for all tag elements. */ - private void javadocTagXML(Tag tag, Item w) throws SAXException { - String name = tag.name().substring(1) + "tag"; - if (! tag.text().equals("")) - w._element(name,TypedXmlWriter.class)._pcdata(tag.text()); + private void javadocTagXML(BlockTagTree tag, Item w) throws SAXException { + String name = tag.getTagName() + "tag"; + String text = tag.toString().substring(tag.getTagName().length() + 2); + if (!text.isEmpty()) { + w._element(name,TypedXmlWriter.class)._pcdata(text); + } } - public static boolean start(RootDoc root) { + @Override + public boolean run(DocletEnvironment root) { + if (targetFileName == null) { + reporter.print(Diagnostic.Kind.ERROR, "Usage: javadoc -d -doclet TagXMLDoclet ..."); + return false; + } + try { - new TagXMLDoclet(root); + main(root); return true; } catch (Exception e) { e.printStackTrace(); @@ -357,59 +424,47 @@ public static boolean start(RootDoc root) { } } - private void readOptions(RootDoc root) - { - for (String[] opt : root.options()) { - if (opt[0].equals("-d")) { - targetFileName = opt[1] + "/taglib.xml"; - } - if (opt[0].equals("-encoding")) { - encodingFormat = opt[1]; - } + private abstract static class Option implements Doclet.Option { + private final String[] names; + private final String parameters; + private final String description; + private final int argCount; + + protected Option(String name, String description, String parameters, int argCount) { + this.names = name.trim().split("\\s+"); + this.description = description; + this.parameters = parameters; + this.argCount = argCount; } - } - public static int optionLength(String option) - { - if(option.equals("-d")) - { - return 2; + @Override + public String getDescription() { + return description; } - if(option.equals("-encoding")) - { - return 2; + + @Override + public Option.Kind getKind() { + return Doclet.Option.Kind.STANDARD; } - return 0; - } - public static boolean validOptions(String[][] options, - DocErrorReporter reporter) - { - boolean foundEncodingOption = false; - boolean foundDirOption = false; - for (String[] opt : options) { - if (opt[0].equals("-d")) { - if (foundDirOption) { - reporter.printError("Only one -d option allowed."); - return false; - } else { - foundDirOption = true; - } - } - if (opt[0].equals("-encoding")) { - if (foundEncodingOption) { - reporter.printError("Only one -encoding option allowed."); - return false; - } else { - foundEncodingOption = true; - } - } + @Override + public List getNames() { + return List.of(names); } - if (!foundDirOption) - { - reporter.printError("Usage: javadoc -d -doclet TagXMLDoclet ..."); - return false; + + @Override + public String getParameters() { + return parameters; + } + + @Override + public String toString() { + return Arrays.toString(names); + } + + @Override + public int getArgumentCount() { + return argCount; } - return true; } } diff --git a/pom.xml b/pom.xml index 60057d1..752681a 100644 --- a/pom.xml +++ b/pom.xml @@ -35,8 +35,6 @@ 999999-SNAPSHOT jenkinsci/jellydoc-maven-plugin - - 1.6 @@ -53,95 +51,9 @@ - - - - - maven-enforcer-plugin - - - display-info - - - - [1.8.0,] - - - 1.8 - - - - - - - - - jellydoc-maven-plugin jellydoc-annotations taglib-xml-writer - - - - - jdk-9-and-above - - [9,) - - - - - - maven-compiler-plugin - - 8 - 8 - - - - maven-javadoc-plugin - - 8 - - - - - - - - jdk-8-and-below - - (,1.8] - - - 2.29.0 - - - - - - maven-compiler-plugin - - 1.8 - 1.8 - 1.8 - 1.8 - - - - - - maven-javadoc-plugin - - 1.8 - - - - - - - -