# HG changeset patch # User jjg # Date 1471908760 25200 # Node ID 1c355ea550edba082f65b19c6b6a970263ba283e # Parent e17429a7e843c4a4ed3651458d0f950970edcbcc 8164130: Simplify doclet IOException handling Reviewed-by: bpatel, ksrini diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AbstractBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AbstractBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/internal/toolkit/builders/AbstractBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 2016, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -124,7 +124,7 @@ /** * Build the documentation. * - * @throws IOException if there was a problem writing the output. + * @throws IOException if there is a problem writing the output */ public abstract void build() throws IOException; diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractIndexWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractIndexWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractIndexWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -26,7 +26,6 @@ package jdk.javadoc.internal.doclets.formats.html; import java.io.*; -import java.nio.file.*; import java.util.*; import java.util.zip.*; @@ -46,9 +45,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; import jdk.javadoc.internal.doclets.toolkit.util.DocFile; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder; /** @@ -93,6 +92,7 @@ * * @return a content tree for the tree label */ + @Override protected Content getNavLinkIndex() { Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.indexLabel); return li; @@ -242,6 +242,7 @@ * * @param pkg the package to be documented * @param dlTree the content tree to which the description will be added + * @param si the search index item to be updated */ protected void addDescription(PackageElement pkg, Content dlTree, SearchIndexItem si) { Content link = getPackageLink(pkg, new StringContent(utils.getPackageName(pkg))); @@ -265,6 +266,7 @@ * * @param typeElement the class being documented * @param dlTree the content tree to which the description will be added + * @param si the search index item to be updated */ protected void addDescription(TypeElement typeElement, Content dlTree, SearchIndexItem si) { Content link = getLink(new LinkInfoImpl(configuration, @@ -332,9 +334,9 @@ } protected void addDescription(SearchIndexItem sii, Content dlTree) { - String path = pathToRoot.isEmpty() ? "" : pathToRoot.getPath() + "/"; - path += sii.getUrl(); - HtmlTree labelLink = HtmlTree.A(path, new StringContent(sii.getLabel())); + String siiPath = pathToRoot.isEmpty() ? "" : pathToRoot.getPath() + "/"; + siiPath += sii.getUrl(); + HtmlTree labelLink = HtmlTree.A(siiPath, new StringContent(sii.getLabel())); Content dt = HtmlTree.DT(HtmlTree.SPAN(HtmlStyle.searchTagLink, labelLink)); dt.addContent(" - "); dt.addContent(contents.getContent("doclet.Search_tag_in", sii.getHolder())); @@ -430,7 +432,10 @@ return "I:" + getName(unicode); } - protected void createSearchIndexFiles() { + /** + * @throws DocFileIOException if there is a problem creating any of the search index files + */ + protected void createSearchIndexFiles() throws DocFileIOException { if (configuration.showModules) { createSearchIndexFile(DocPaths.MODULE_SEARCH_INDEX_JSON, DocPaths.MODULE_SEARCH_INDEX_ZIP, configuration.moduleSearchIndex); @@ -445,54 +450,37 @@ configuration.tagSearchIndex); } + /** + * @throws DocFileIOException if there is a problem creating the search index file + */ protected void createSearchIndexFile(DocPath searchIndexFile, DocPath searchIndexZip, - List searchIndex) { + List searchIndex) throws DocFileIOException { if (!searchIndex.isEmpty()) { - try { - StringBuilder searchVar = new StringBuilder("["); - boolean first = true; - DocFile searchFile = DocFile.createFileForOutput(configuration, searchIndexFile); - Path p = Paths.get(searchFile.getPath()); - for (SearchIndexItem item : searchIndex) { - if (first) { - searchVar.append(item.toString()); - first = false; - } else { - searchVar.append(",").append(item.toString()); - } + StringBuilder searchVar = new StringBuilder("["); + boolean first = true; + for (SearchIndexItem item : searchIndex) { + if (first) { + searchVar.append(item.toString()); + first = false; + } else { + searchVar.append(",").append(item.toString()); } - searchVar.append("]"); - Files.write(p, searchVar.toString().getBytes()); - DocFile zipFile = DocFile.createFileForOutput(configuration, searchIndexZip); - try (FileOutputStream fos = new FileOutputStream(zipFile.getPath()); - ZipOutputStream zos = new ZipOutputStream(fos)) { - zipFile(searchFile.getPath(), searchIndexFile, zos); + } + searchVar.append("]"); + + DocFile zipFile = DocFile.createFileForOutput(configuration, searchIndexZip); + try (OutputStream fos = zipFile.openOutputStream(); + ZipOutputStream zos = new ZipOutputStream(fos)) { + try { + ZipEntry ze = new ZipEntry(searchIndexFile.getPath()); + zos.putNextEntry(ze); + zos.write(searchVar.toString().getBytes()); + } finally { + zos.closeEntry(); } - Files.delete(p); } catch (IOException ie) { - throw new DocletAbortException(ie); + throw new DocFileIOException(zipFile, DocFileIOException.Mode.WRITE, ie); } } } - - protected void zipFile(String inputFile, DocPath file, ZipOutputStream zos) { - try { - try { - ZipEntry ze = new ZipEntry(file.getPath()); - zos.putNextEntry(ze); - try (FileInputStream fis = new FileInputStream(new File(inputFile))) { - byte[] buf = new byte[2048]; - int len = fis.read(buf); - while (len > 0) { - zos.write(buf, 0, len); - len = fis.read(buf); - } - } - } finally { - zos.closeEntry(); - } - } catch (IOException e) { - throw new DocletAbortException(e); - } - } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractModuleIndexWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractModuleIndexWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractModuleIndexWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.Map; import java.util.Set; import java.util.SortedMap; @@ -39,6 +38,7 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; /** @@ -123,8 +123,9 @@ * * @param title the title of the window. * @param includeScript boolean set true if windowtitle script is to be included + * @throws DocFileIOException if there is a problem building the module index file */ - protected void buildModuleIndexFile(String title, boolean includeScript) throws IOException { + protected void buildModuleIndexFile(String title, boolean includeScript) throws DocFileIOException { String windowOverview = configuration.getText(title); Content body = getBody(includeScript, getWindowTitle(windowOverview)); addNavigationBarHeader(body); @@ -144,9 +145,10 @@ * @param title the title of the window. * @param includeScript boolean set true if windowtitle script is to be included * @param mdle the name of the module being documented + * @throws DocFileIOException if there is an exception building the module packages index file */ protected void buildModulePackagesIndexFile(String title, - boolean includeScript, ModuleElement mdle) throws IOException { + boolean includeScript, ModuleElement mdle) throws DocFileIOException { String windowOverview = configuration.getText(title); Content body = getBody(includeScript, getWindowTitle(windowOverview)); addNavigationBarHeader(body); @@ -163,8 +165,7 @@ * * @param body the document tree to which the overview will be added */ - protected void addOverview(Content body) throws IOException { - } + protected void addOverview(Content body) { } /** * Adds the frame or non-frame module index to the documentation tree. @@ -259,6 +260,7 @@ * * @return a Content object to be added to the documentation tree */ + @Override protected Content getNavLinkContents() { Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.overviewLabel); return li; @@ -269,22 +271,19 @@ * * @param div the document tree to which the all classes link will be added */ - protected void addAllClassesLink(Content div) { - } + protected void addAllClassesLink(Content div) { } /** * Do nothing. This will be overridden in ModuleIndexFrameWriter. * * @param div the document tree to which the all packages link will be added */ - protected void addAllPackagesLink(Content div) { - } + protected void addAllPackagesLink(Content div) { } /** * Do nothing. This will be overridden in ModulePackageIndexFrameWriter. * * @param div the document tree to which the all modules link will be added */ - protected void addAllModulesLink(Content div) { - } + protected void addAllModulesLink(Content div) { } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractPackageIndexWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractPackageIndexWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractPackageIndexWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.PackageElement; @@ -36,6 +35,7 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; /** @@ -109,8 +109,9 @@ * * @param title the title of the window. * @param includeScript boolean set true if windowtitle script is to be included + * @throws DocFileIOException if there is a problem building the package index file */ - protected void buildPackageIndexFile(String title, boolean includeScript) throws IOException { + protected void buildPackageIndexFile(String title, boolean includeScript) throws DocFileIOException { String windowOverview = configuration.getText(title); Content body = getBody(includeScript, getWindowTitle(windowOverview)); addNavigationBarHeader(body); @@ -127,8 +128,7 @@ * * @param body the document tree to which the overview will be added */ - protected void addOverview(Content body) throws IOException { - } + protected void addOverview(Content body) { } /** * Adds the frame or non-frame package index to the documentation tree. @@ -190,6 +190,7 @@ * * @return a Content object to be added to the documentation tree */ + @Override protected Content getNavLinkContents() { Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.overviewLabel); return li; diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractTreeWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractTreeWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractTreeWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.TypeElement; @@ -37,7 +36,6 @@ import jdk.javadoc.internal.doclets.toolkit.Content; import jdk.javadoc.internal.doclets.toolkit.util.ClassTree; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** @@ -67,8 +65,6 @@ * @param configuration The current configuration * @param filename File to be generated. * @param classtree Tree built by {@link ClassTree}. - * @throws IOException - * @throws DocletAbortException */ protected AbstractTreeWriter(ConfigurationImpl configuration, DocPath filename, ClassTree classtree) { diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesFrameWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesFrameWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesFrameWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.IOException; import javax.lang.model.element.Element; import javax.lang.model.element.TypeElement; @@ -35,10 +34,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder; @@ -75,8 +73,6 @@ * @param configuration The current configuration * @param filename Path to the file which is getting generated. * @param indexbuilder Unicode based Index from {@link IndexBuilder} - * @throws IOException - * @throws DocletAbortException */ public AllClassesFrameWriter(ConfigurationImpl configuration, DocPath filename, IndexBuilder indexbuilder) { @@ -90,10 +86,10 @@ * destination directory. * * @param indexBuilder IndexBuilder object for all classes index. - * @throws DocletAbortException + * @throws DocFileIOException */ public static void generate(ConfigurationImpl configuration, - IndexBuilder indexBuilder) { + IndexBuilder indexBuilder) throws DocFileIOException { if (configuration.frames) { generate(configuration, indexBuilder, DocPaths.ALLCLASSES_FRAME, true); generate(configuration, indexBuilder, DocPaths.ALLCLASSES_NOFRAME, false); @@ -103,27 +99,20 @@ } private static void generate(ConfigurationImpl configuration, IndexBuilder indexBuilder, - DocPath fileName, boolean wantFrames) { - try { - AllClassesFrameWriter allclassgen = new AllClassesFrameWriter(configuration, - fileName, indexBuilder); - allclassgen.buildAllClassesFile(wantFrames); - allclassgen = new AllClassesFrameWriter(configuration, - fileName, indexBuilder); - allclassgen.buildAllClassesFile(false); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), fileName); - throw new DocletAbortException(exc); - } + DocPath fileName, boolean wantFrames) throws DocFileIOException { + AllClassesFrameWriter allclassgen = new AllClassesFrameWriter(configuration, + fileName, indexBuilder); + allclassgen.buildAllClassesFile(wantFrames); + allclassgen = new AllClassesFrameWriter(configuration, + fileName, indexBuilder); + allclassgen.buildAllClassesFile(false); } /** * Print all the classes in the file. * @param wantFrames True if we want frames. */ - protected void buildAllClassesFile(boolean wantFrames) throws IOException { + protected void buildAllClassesFile(boolean wantFrames) throws DocFileIOException { String label = configuration.getText("doclet.All_Classes"); Content body = getBody(false, getWindowTitle(label)); Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeWriterImpl.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeWriterImpl.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeWriterImpl.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.IOException; import java.util.List; import javax.lang.model.element.PackageElement; @@ -42,9 +41,9 @@ import jdk.javadoc.internal.doclets.toolkit.Content; import jdk.javadoc.internal.doclets.toolkit.builders.MemberSummaryBuilder; import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; /** @@ -78,11 +77,9 @@ * @param annotationType the annotation type being documented. * @param prevType the previous class that was documented. * @param nextType the next class being documented. - * @throws java.lang.Exception */ public AnnotationTypeWriterImpl(ConfigurationImpl configuration, - TypeElement annotationType, TypeMirror prevType, TypeMirror nextType) - throws Exception { + TypeElement annotationType, TypeMirror prevType, TypeMirror nextType) { super(configuration, DocPath.forClass(configuration.utils, annotationType)); this.annotationType = annotationType; configuration.currentTypeElement = annotationType; @@ -243,7 +240,7 @@ * {@inheritDoc} */ @Override - public void printDocument(Content contentTree) throws IOException { + public void printDocument(Content contentTree) throws DocFileIOException { printHtmlDocument(configuration.metakeywords.getMetaKeywords(annotationType), true, contentTree); } @@ -352,22 +349,17 @@ */ @Override protected void addSummaryDetailLinks(Content subDiv) { - try { - Content div = HtmlTree.DIV(getNavSummaryLinks()); - div.addContent(getNavDetailLinks()); - subDiv.addContent(div); - } catch (Exception e) { - throw new DocletAbortException(e); - } + Content div = HtmlTree.DIV(getNavSummaryLinks()); + div.addContent(getNavDetailLinks()); + subDiv.addContent(div); } /** * Get summary links for navigation bar. * * @return the content tree for the navigation summary links - * @throws java.lang.Exception */ - protected Content getNavSummaryLinks() throws Exception { + protected Content getNavSummaryLinks() { Content li = HtmlTree.LI(contents.summaryLabel); li.addContent(Contents.SPACE); Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li); @@ -417,9 +409,8 @@ * Get detail links for the navigation bar. * * @return the content tree for the detail links - * @throws java.lang.Exception */ - protected Content getNavDetailLinks() throws Exception { + protected Content getNavDetailLinks() { Content li = HtmlTree.LI(contents.detailLabel); li.addContent(Contents.SPACE); Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.IOException; import java.util.ArrayList; import java.util.Collections; import java.util.HashMap; @@ -47,12 +46,11 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; import jdk.javadoc.internal.doclets.toolkit.util.ClassTree; import jdk.javadoc.internal.doclets.toolkit.util.ClassUseMapper; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** * Generate class usage information. @@ -112,12 +110,10 @@ * Constructor. * * @param filename the file to be generated. - * @throws IOException - * @throws DocletAbortException */ public ClassUseWriter(ConfigurationImpl configuration, ClassUseMapper mapper, DocPath filename, - TypeElement typeElement) throws IOException { + TypeElement typeElement) { super(configuration, filename); this.typeElement = typeElement; if (mapper.classToPackageAnnotations.containsKey(typeElement)) { @@ -175,9 +171,12 @@ /** * Write out class use pages. - * @throws DocletAbortException + * + * @param configuration the configuration for this doclet + * @param classtree the class tree hierarchy + * @throws DocFileIOException if there is an error while generating the documentation */ - public static void generate(ConfigurationImpl configuration, ClassTree classtree) { + public static void generate(ConfigurationImpl configuration, ClassTree classtree) throws DocFileIOException { ClassUseMapper mapper = new ClassUseMapper(configuration, classtree); for (TypeElement aClass : configuration.docEnv.getIncludedTypeElements()) { // If -nodeprecated option is set and the containing package is marked @@ -217,28 +216,25 @@ /** * Generate a class page. + * + * @throws DocFileIOException if there is a problem while generating the documentation */ public static void generate(ConfigurationImpl configuration, ClassUseMapper mapper, - TypeElement typeElement) { + TypeElement typeElement) throws DocFileIOException { ClassUseWriter clsgen; DocPath path = DocPath.forPackage(configuration.utils, typeElement) .resolve(DocPaths.CLASS_USE) .resolve(DocPath.forName(configuration.utils, typeElement)); - try { - clsgen = new ClassUseWriter(configuration, mapper, path, typeElement); - clsgen.generateClassUseFile(); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), path.getPath()); - throw new DocletAbortException(exc); - } + clsgen = new ClassUseWriter(configuration, mapper, path, typeElement); + clsgen.generateClassUseFile(); } /** * Generate the class use elements. + * + * @throws DocFileIOException if there is a problem while generating the documentation */ - protected void generateClassUseFile() throws IOException { + protected void generateClassUseFile() throws DocFileIOException { HtmlTree body = getClassUseHeader(); HtmlTree div = new HtmlTree(HtmlTag.DIV); div.addStyle(HtmlStyle.classUseContainer); @@ -270,7 +266,7 @@ * * @param contentTree the content tree to which the class use information will be added */ - protected void addClassUse(Content contentTree) throws IOException { + protected void addClassUse(Content contentTree) { HtmlTree ul = new HtmlTree(HtmlTag.UL); ul.addStyle(HtmlStyle.blockList); if (configuration.packages.size() > 1) { @@ -286,7 +282,7 @@ * * @param contentTree the content tree to which the packages elements will be added */ - protected void addPackageList(Content contentTree) throws IOException { + protected void addPackageList(Content contentTree) { Content caption = getTableCaption(configuration.getContent( "doclet.ClassUse_Packages.that.use.0", getLink(new LinkInfoImpl(configuration, @@ -314,7 +310,7 @@ * * @param contentTree the content tree to which the package annotation elements will be added */ - protected void addPackageAnnotationList(Content contentTree) throws IOException { + protected void addPackageAnnotationList(Content contentTree) { if (!utils.isAnnotationType(typeElement) || pkgToPackageAnnotations == null || pkgToPackageAnnotations.isEmpty()) { @@ -352,7 +348,7 @@ * * @param contentTree the content tree to which the class elements will be added */ - protected void addClassList(Content contentTree) throws IOException { + protected void addClassList(Content contentTree) { HtmlTree ul = new HtmlTree(HtmlTag.UL); ul.addStyle(HtmlStyle.blockList); for (PackageElement pkg : pkgSet) { @@ -383,7 +379,7 @@ * @param pkg the package that uses the given class * @param contentTree the content tree to which the package use information will be added */ - protected void addPackageUse(PackageElement pkg, Content contentTree) throws IOException { + protected void addPackageUse(PackageElement pkg, Content contentTree) { Content tdFirst = HtmlTree.TD(HtmlStyle.colFirst, getHyperLink(getPackageAnchorName(pkg), new StringContent(utils.getPackageName(pkg)))); contentTree.addContent(tdFirst); @@ -399,7 +395,7 @@ * @param pkg the package that uses the given class * @param contentTree the content tree to which the class use information will be added */ - protected void addClassUse(PackageElement pkg, Content contentTree) throws IOException { + protected void addClassUse(PackageElement pkg, Content contentTree) { Content classLink = getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.CLASS_USE_HEADER, typeElement)); Content pkgLink = getPackageLink(pkg, utils.getPackageName(pkg)); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriterImpl.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.IOException; import java.util.*; import javax.lang.model.element.AnnotationMirror; @@ -50,9 +49,9 @@ import jdk.javadoc.internal.doclets.toolkit.taglets.ParamTaglet; import jdk.javadoc.internal.doclets.toolkit.util.ClassTree; import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap.Kind; @@ -91,11 +90,9 @@ * @param prevClass the previous class that was documented. * @param nextClass the next class being documented. * @param classTree the class tree for the given class. - * @throws java.io.IOException */ public ClassWriterImpl(ConfigurationImpl configuration, TypeElement typeElement, - TypeElement prevClass, TypeElement nextClass, ClassTree classTree) - throws IOException { + TypeElement prevClass, TypeElement nextClass, ClassTree classTree) { super(configuration, DocPath.forClass(configuration.utils, typeElement)); this.typeElement = typeElement; configuration.currentTypeElement = typeElement; @@ -272,7 +269,7 @@ * {@inheritDoc} */ @Override - public void printDocument(Content contentTree) throws IOException { + public void printDocument(Content contentTree) throws DocFileIOException { printHtmlDocument(configuration.metakeywords.getMetaKeywords(typeElement), true, contentTree); } @@ -677,14 +674,11 @@ * * @param subDiv the content tree to which the summary detail links will be added */ + @Override protected void addSummaryDetailLinks(Content subDiv) { - try { - Content div = HtmlTree.DIV(getNavSummaryLinks()); - div.addContent(getNavDetailLinks()); - subDiv.addContent(div); - } catch (Exception e) { - throw new DocletAbortException(e); - } + Content div = HtmlTree.DIV(getNavSummaryLinks()); + div.addContent(getNavDetailLinks()); + subDiv.addContent(div); } /** @@ -692,7 +686,7 @@ * * @return the content tree for the navigation summary links */ - protected Content getNavSummaryLinks() throws Exception { + protected Content getNavSummaryLinks() { Content li = HtmlTree.LI(contents.summaryLabel); li.addContent(Contents.SPACE); Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li); @@ -727,9 +721,8 @@ * Get detail links for the navigation bar. * * @return the content tree for the detail links - * @throws java.lang.Exception */ - protected Content getNavDetailLinks() throws Exception { + protected Content getNavDetailLinks() { Content li = HtmlTree.LI(contents.detailLabel); li.addContent(Contents.SPACE); Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConfigurationImpl.java Mon Aug 22 16:32:40 2016 -0700 @@ -50,7 +50,6 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFile; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.Utils; import static javax.tools.Diagnostic.Kind.*; diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstantsSummaryWriterImpl.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstantsSummaryWriterImpl.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstantsSummaryWriterImpl.java Mon Aug 22 16:32:40 2016 -0700 @@ -41,6 +41,7 @@ import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.ConstantsSummaryWriter; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocLink; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; @@ -379,7 +380,8 @@ /** * {@inheritDoc} */ - public void printDocument(Content contentTree) throws IOException { + @Override + public void printDocument(Content contentTree) throws DocFileIOException { printHtmlDocument(null, true, contentTree); } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.ArrayList; import java.util.EnumMap; import java.util.List; @@ -35,13 +34,11 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder; +import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder.DeprElementKind; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; - -import static jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder.*; /** * Generate File to list all the deprecated classes and class members with the @@ -189,11 +186,11 @@ /** * Constructor. * - * @param filename the file to be generated. + * @param configuration the configuration for this doclet + * @param filename the file to be generated */ - public DeprecatedListWriter(ConfigurationImpl configuration, - DocPath filename) throws IOException { + public DeprecatedListWriter(ConfigurationImpl configuration, DocPath filename) { super(configuration, filename); this.configuration = configuration; NestedClassWriterImpl classW = new NestedClassWriterImpl(this); @@ -236,29 +233,23 @@ * Then instantiate DeprecatedListWriter and generate File. * * @param configuration the current configuration of the doclet. + * @throws DocFileIOException if there is a problem writing the deprecated list */ - public static void generate(ConfigurationImpl configuration) { + public static void generate(ConfigurationImpl configuration) throws DocFileIOException { DocPath filename = DocPaths.DEPRECATED_LIST; - try { - DeprecatedListWriter depr = - new DeprecatedListWriter(configuration, filename); - depr.generateDeprecatedListFile( - new DeprecatedAPIListBuilder(configuration)); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + DeprecatedListWriter depr = new DeprecatedListWriter(configuration, filename); + depr.generateDeprecatedListFile( + new DeprecatedAPIListBuilder(configuration)); } /** * Generate the deprecated API list. * * @param deprapi list of deprecated API built already. + * @throws DocFileIOException if there is a problem writing the deprecated list */ protected void generateDeprecatedListFile(DeprecatedAPIListBuilder deprapi) - throws IOException { + throws DocFileIOException { HtmlTree body = getHeader(); HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN)) ? HtmlTree.MAIN() @@ -378,6 +369,7 @@ * * @return a content tree for the deprecated label */ + @Override protected Content getNavLinkDeprecated() { Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.deprecatedLabel); return li; diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FrameOutputWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FrameOutputWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FrameOutputWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,17 +25,14 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; - import jdk.javadoc.internal.doclets.formats.html.markup.HtmlAttr; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** @@ -67,7 +64,6 @@ * * @param configuration for this run * @param filename File to be generated. - * @throws java.io.IOException */ public FrameOutputWriter(ConfigurationImpl configuration, DocPath filename) { super(configuration, filename); @@ -79,28 +75,20 @@ * file which will have the description of all the frames in the * documentation. The name of the generated file is "index.html" which is * the default first file for Html documents. - * @throws DocletAbortException + * @param configuration the configuration for this doclet + * @throws DocFileIOException if there is a problem generating the frame file */ - public static void generate(ConfigurationImpl configuration) { - FrameOutputWriter framegen; - DocPath filename = DocPath.empty; - try { - filename = DocPaths.INDEX; - framegen = new FrameOutputWriter(configuration, filename); - framegen.generateFrameFile(); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + public static void generate(ConfigurationImpl configuration) throws DocFileIOException { + FrameOutputWriter framegen = new FrameOutputWriter(configuration, DocPaths.INDEX); + framegen.generateFrameFile(); } /** * Generate the constants in the "index.html" file. Print the frame details * as well as warning if browser is not supporting the Html frames. + * @throws DocFileIOException if there is a problem generating the frame file */ - protected void generateFrameFile() throws IOException { + protected void generateFrameFile() throws DocFileIOException { Content frame = getFrameDetails(); HtmlTree body = new HtmlTree(HtmlTag.BODY); body.addAttr(HtmlAttr.ONLOAD, "loadFrames()"); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,18 +25,15 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; - import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** @@ -68,27 +65,21 @@ * file. The name of the generated file is "help-doc.html". The help file * will get generated if and only if "-helpfile" and "-nohelp" is not used * on the command line. - * @throws DocletAbortException + * + * @throws DocFileIOException if there is a problem while generating the documentation */ - public static void generate(ConfigurationImpl configuration) { - HelpWriter helpgen; - DocPath filename = DocPath.empty; - try { - filename = DocPaths.HELP_DOC; - helpgen = new HelpWriter(configuration, filename); - helpgen.generateHelpFile(); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + public static void generate(ConfigurationImpl configuration) throws DocFileIOException { + DocPath filename = DocPaths.HELP_DOC; + HelpWriter helpgen = new HelpWriter(configuration, filename); + helpgen.generateHelpFile(); } /** * Generate the help file contents. + * + * @throws DocFileIOException if there is a problem while generating the documentation */ - protected void generateHelpFile() throws IOException { + protected void generateHelpFile() throws DocFileIOException { String title = configuration.getText("doclet.Window_Help_title"); HtmlTree body = getBody(true, getWindowTitle(title)); HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER)) diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.ModuleElement; @@ -36,14 +35,14 @@ import jdk.javadoc.doclet.DocletEnvironment; import jdk.javadoc.doclet.Reporter; import jdk.javadoc.internal.doclets.toolkit.AbstractDoclet; -import jdk.javadoc.internal.doclets.toolkit.Configuration; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.Messages; import jdk.javadoc.internal.doclets.toolkit.builders.AbstractBuilder; import jdk.javadoc.internal.doclets.toolkit.util.ClassTree; import jdk.javadoc.internal.doclets.toolkit.util.DocFile; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder; /** @@ -92,25 +91,27 @@ * Create the configuration instance. * Override this method to use a different * configuration. + * @return the configuration for this doclet */ @Override // defined by AbstractDoclet - public Configuration configuration() { + public ConfigurationImpl configuration() { return configuration; } /** * Start the generation of files. Call generate methods in the individual - * writers, which will in turn genrate the documentation files. Call the + * writers, which will in turn generate the documentation files. Call the * TreeWriter generation first to ensure the Class Hierarchy is built * first and then can be used in the later generation. * * For new format. * + * @throws DocletException if there is a problem while writing the other files * @see jdk.doclet.DocletEnvironment */ @Override // defined by AbstractDoclet protected void generateOtherFiles(DocletEnvironment docEnv, ClassTree classtree) - throws Exception { + throws DocletException { super.generateOtherFiles(docEnv, classtree); if (configuration.linksource) { SourceToHTMLConverter.convertRoot(configuration, @@ -191,7 +192,7 @@ } } - protected void copyJqueryFiles() { + protected void copyJqueryFiles() throws DocletException { List files = Arrays.asList( "jquery-1.10.2.js", "jquery-ui.js", @@ -232,7 +233,8 @@ * {@inheritDoc} */ @Override // defined by AbstractDoclet - protected void generateClassFiles(SortedSet arr, ClassTree classtree) { + protected void generateClassFiles(SortedSet arr, ClassTree classtree) + throws DocletException { List list = new ArrayList<>(arr); ListIterator iterator = list.listIterator(); TypeElement klass = null; @@ -241,32 +243,24 @@ klass = iterator.next(); TypeElement next = iterator.nextIndex() == list.size() ? null : list.get(iterator.nextIndex()); + if (utils.isHidden(klass) || !(configuration.isGeneratedDoc(klass) && utils.isIncluded(klass))) { continue; } - try { - if (utils.isAnnotationType(klass)) { - AbstractBuilder annotationTypeBuilder = - configuration.getBuilderFactory() - .getAnnotationTypeBuilder(klass, - prev == null ? null : prev.asType(), - next == null ? null : next.asType()); - annotationTypeBuilder.build(); - } else { - AbstractBuilder classBuilder = - configuration.getBuilderFactory().getClassBuilder(klass, - prev, next, classtree); - classBuilder.build(); - } - } catch (IOException e) { - throw new DocletAbortException(e); - } catch (DocletAbortException de) { - de.printStackTrace(); - throw de; - } catch (Exception e) { - e.printStackTrace(); - throw new DocletAbortException(e); + + if (utils.isAnnotationType(klass)) { + AbstractBuilder annotationTypeBuilder = + configuration.getBuilderFactory() + .getAnnotationTypeBuilder(klass, + prev == null ? null : prev.asType(), + next == null ? null : next.asType()); + annotationTypeBuilder.build(); + } else { + AbstractBuilder classBuilder = + configuration.getBuilderFactory().getClassBuilder(klass, + prev, next, classtree); + classBuilder.build(); } } } @@ -275,7 +269,7 @@ * {@inheritDoc} */ @Override // defined by AbstractDoclet - protected void generateModuleFiles() throws Exception { + protected void generateModuleFiles() throws DocletException { if (configuration.showModules) { if (configuration.frames) { ModuleIndexFrameWriter.generate(configuration); @@ -313,7 +307,7 @@ * {@inheritDoc} */ @Override // defined by AbstractDoclet - protected void generatePackageFiles(ClassTree classtree) throws Exception { + protected void generatePackageFiles(ClassTree classtree) throws DocletException { Set packages = configuration.packages; if (packages.size() > 1 && configuration.frames) { PackageIndexFrameWriter.generate(configuration); @@ -356,24 +350,18 @@ return configuration.getSupportedOptions(); } - private void performCopy(String filename) { + private void performCopy(String filename) throws DocFileIOException { if (filename.isEmpty()) return; - try { - DocFile fromfile = DocFile.createFileForInput(configuration, filename); - DocPath path = DocPath.create(fromfile.getName()); - DocFile toFile = DocFile.createFileForOutput(configuration, path); - if (toFile.isSameFile(fromfile)) - return; + DocFile fromfile = DocFile.createFileForInput(configuration, filename); + DocPath path = DocPath.create(fromfile.getName()); + DocFile toFile = DocFile.createFileForOutput(configuration, path); + if (toFile.isSameFile(fromfile)) + return; - messages.notice("doclet.Copying_File_0_To_File_1", - fromfile.toString(), path.getPath()); - toFile.copyFile(fromfile); - } catch (IOException exc) { - messages.error("doclet.perform_copy_exception_encountered", - exc.toString()); - throw new DocletAbortException(exc); - } + messages.notice("doclet.Copying_File_0_To_File_1", + fromfile.toString(), path.getPath()); + toFile.copyFile(fromfile); } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.text.SimpleDateFormat; import java.util.*; import java.util.regex.Matcher; @@ -55,8 +54,8 @@ import com.sun.source.doctree.EndElementTree; import com.sun.source.doctree.EntityTree; import com.sun.source.doctree.ErroneousTree; +import com.sun.source.doctree.IndexTree; import com.sun.source.doctree.InheritDocTree; -import com.sun.source.doctree.IndexTree; import com.sun.source.doctree.LinkTree; import com.sun.source.doctree.LiteralTree; import com.sun.source.doctree.SeeTree; @@ -87,14 +86,15 @@ import jdk.javadoc.internal.doclets.toolkit.Resources; import jdk.javadoc.internal.doclets.toolkit.taglets.DocRootTaglet; import jdk.javadoc.internal.doclets.toolkit.taglets.TagletWriter; +import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; import jdk.javadoc.internal.doclets.toolkit.util.DocFile; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocLink; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; import jdk.javadoc.internal.doclets.toolkit.util.ImplementedMethods; import jdk.javadoc.internal.doclets.toolkit.util.Utils; -import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; import static com.sun.source.doctree.AttributeTree.ValueKind.*; import static com.sun.source.doctree.DocTree.Kind.*; @@ -439,9 +439,10 @@ * @param includeScript true if printing windowtitle script * false for files that appear in the left-hand frames * @param body the body htmltree to be included in the document + * @throws DocFileIOException if there is a problem writing the file */ public void printHtmlDocument(List metakeywords, boolean includeScript, - Content body) throws IOException { + Content body) throws DocFileIOException { Content htmlDocType = configuration.isOutputHtml5() ? DocType.HTML5 : DocType.TRANSITIONAL; @@ -2180,8 +2181,8 @@ head.addContent(javascript); if (configuration.createindex) { if (pathToRoot != null && script != null) { - String path = pathToRoot.isEmpty() ? "." : pathToRoot.getPath(); - script.addContent(new RawHtml("var pathtoroot = \"" + path + "/\";loadScripts(document, \'script\');")); + String ptrPath = pathToRoot.isEmpty() ? "." : pathToRoot.getPath(); + script.addContent(new RawHtml("var pathtoroot = \"" + ptrPath + "/\";loadScripts(document, \'script\');")); } addJQueryFile(head, DocPaths.JSZIP_MIN); addJQueryFile(head, DocPaths.JSZIPUTILS_MIN); @@ -2615,6 +2616,7 @@ * * @return the configuration for this doclet. */ + @Override public Configuration configuration() { return configuration; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,8 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.IOException; - import jdk.javadoc.internal.doclets.formats.html.markup.Comment; import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder; import jdk.javadoc.internal.doclets.formats.html.markup.DocType; @@ -37,10 +35,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import static jdk.javadoc.internal.doclets.formats.html.markup.HtmlDocWriter.CONTENT_TYPE; @@ -53,28 +50,23 @@ */ public class IndexRedirectWriter extends HtmlDocletWriter { - public static void generate(ConfigurationImpl configuration) { + public static void generate(ConfigurationImpl configuration) + throws DocFileIOException { IndexRedirectWriter indexRedirect; - DocPath filename = DocPath.empty; - try { - filename = DocPaths.INDEX; + DocPath filename = DocPaths.INDEX; indexRedirect = new IndexRedirectWriter(configuration, filename); indexRedirect.generateIndexFile(); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error( - "doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } } - IndexRedirectWriter(ConfigurationImpl configuration, DocPath filename) - throws IOException { + IndexRedirectWriter(ConfigurationImpl configuration, DocPath filename) { super(configuration, filename); } - void generateIndexFile() throws IOException { + /** + * Generate an index file that redirects to an alternate file. + * @throws DocFileIOException if there is a problem generating the file + */ + void generateIndexFile() throws DocFileIOException { Content htmlDocType = configuration.isOutputHtml5() ? DocType.HTML5 : DocType.TRANSITIONAL; diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleFrameWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.ModuleElement; @@ -39,8 +38,8 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** @@ -76,8 +75,7 @@ * @param configuration the configuration of the doclet. * @param moduleElement moduleElement under consideration. */ - public ModuleFrameWriter(ConfigurationImpl configuration, ModuleElement moduleElement) - throws IOException { + public ModuleFrameWriter(ConfigurationImpl configuration, ModuleElement moduleElement) { super(configuration, DocPaths.moduleTypeFrame(moduleElement)); this.mdle = moduleElement; if (configuration.getSpecifiedPackages().isEmpty()) { @@ -91,35 +89,29 @@ * * @param configuration the current configuration of the doclet. * @param moduleElement The package for which "module_name-type-frame.html" is to be generated. + * @throws DocFileIOException if there is a problem generating the module summary file */ - public static void generate(ConfigurationImpl configuration, ModuleElement moduleElement) { - ModuleFrameWriter mdlgen; - try { - mdlgen = new ModuleFrameWriter(configuration, moduleElement); - String mdlName = moduleElement.getQualifiedName().toString(); - Content mdlLabel = new StringContent(mdlName); - HtmlTree body = mdlgen.getBody(false, mdlgen.getWindowTitle(mdlName)); - HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN)) - ? HtmlTree.MAIN() - : body; - Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, HtmlStyle.bar, - mdlgen.getHyperLink(DocPaths.moduleSummary(moduleElement), mdlLabel, "", "classFrame")); - htmlTree.addContent(heading); - HtmlTree div = new HtmlTree(HtmlTag.DIV); - div.addStyle(HtmlStyle.indexContainer); - mdlgen.addClassListing(div); - htmlTree.addContent(div); - if (configuration.allowTag(HtmlTag.MAIN)) { - body.addContent(htmlTree); - } - mdlgen.printHtmlDocument( - configuration.metakeywords.getMetaKeywordsForModule(moduleElement), false, body); - } catch (IOException exc) { - configuration.messages.error( - "doclet.exception_encountered", - exc.toString(), DocPaths.moduleTypeFrame(moduleElement).getPath()); - throw new DocletAbortException(exc); + public static void generate(ConfigurationImpl configuration, ModuleElement moduleElement) + throws DocFileIOException { + ModuleFrameWriter mdlgen = new ModuleFrameWriter(configuration, moduleElement); + String mdlName = moduleElement.getQualifiedName().toString(); + Content mdlLabel = new StringContent(mdlName); + HtmlTree body = mdlgen.getBody(false, mdlgen.getWindowTitle(mdlName)); + HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN)) + ? HtmlTree.MAIN() + : body; + Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, HtmlStyle.bar, + mdlgen.getHyperLink(DocPaths.moduleSummary(moduleElement), mdlLabel, "", "classFrame")); + htmlTree.addContent(heading); + HtmlTree div = new HtmlTree(HtmlTag.DIV); + div.addStyle(HtmlStyle.indexContainer); + mdlgen.addClassListing(div); + htmlTree.addContent(div); + if (configuration.allowTag(HtmlTag.MAIN)) { + body.addContent(htmlTree); } + mdlgen.printHtmlDocument( + configuration.metakeywords.getMetaKeywordsForModule(moduleElement), false, body); } /** diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleIndexFrameWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleIndexFrameWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleIndexFrameWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.Map; import java.util.Set; @@ -39,10 +38,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** * Generate the module index for the left-hand frame in the generated output. @@ -65,27 +63,19 @@ * @param filename Name of the module index file to be generated. */ public ModuleIndexFrameWriter(ConfigurationImpl configuration, - DocPath filename) throws IOException { + DocPath filename) { super(configuration, filename); } /** * Generate the module index file named "module-overview-frame.html". - * @throws DocletAbortException + * @throws DocFileIOException * @param configuration the configuration object */ - public static void generate(ConfigurationImpl configuration) { - ModuleIndexFrameWriter modulegen; + public static void generate(ConfigurationImpl configuration) throws DocFileIOException { DocPath filename = DocPaths.MODULE_OVERVIEW_FRAME; - try { - modulegen = new ModuleIndexFrameWriter(configuration, filename); - modulegen.buildModuleIndexFile("doclet.Window_Overview", false); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + ModuleIndexFrameWriter modulegen = new ModuleIndexFrameWriter(configuration, filename); + modulegen.buildModuleIndexFile("doclet.Window_Overview", false); } /** diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleIndexWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleIndexWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleIndexWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,13 +25,11 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.ModuleElement; import javax.lang.model.element.PackageElement; -import jdk.javadoc.doclet.DocletEnvironment; import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; @@ -39,10 +37,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.Group; /** @@ -68,15 +65,14 @@ /** * HTML tree for main tag. */ - private HtmlTree htmlTree = HtmlTree.MAIN(); + private final HtmlTree htmlTree = HtmlTree.MAIN(); /** * Construct the ModuleIndexWriter. * @param configuration the configuration object * @param filename the name of the generated file - * @throws java.io.IOException */ - public ModuleIndexWriter(ConfigurationImpl configuration, DocPath filename) throws IOException { + public ModuleIndexWriter(ConfigurationImpl configuration, DocPath filename) { super(configuration, filename); modules = configuration.modules; } @@ -85,20 +81,12 @@ * Generate the module index page for the right-hand frame. * * @param configuration the current configuration of the doclet. + * @throws DocFileIOException if there is a problem generating the module index page */ - public static void generate(ConfigurationImpl configuration) { - ModuleIndexWriter mdlgen; + public static void generate(ConfigurationImpl configuration) throws DocFileIOException { DocPath filename = DocPaths.overviewSummary(configuration.frames); - try { - mdlgen = new ModuleIndexWriter(configuration, filename); - mdlgen.buildModuleIndexFile("doclet.Window_Overview_Summary", true); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error( - "doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + ModuleIndexWriter mdlgen = new ModuleIndexWriter(configuration, filename); + mdlgen.buildModuleIndexFile("doclet.Window_Overview_Summary", true); } /** @@ -106,6 +94,7 @@ * * @param body the documentation tree to which the index will be added */ + @Override protected void addIndex(Content body) { if (modules != null && !modules.isEmpty()) { addIndexContents(configuration.getText("doclet.Modules"), @@ -190,6 +179,7 @@ * * @param body the documentation tree to which the overview header will be added */ + @Override protected void addOverviewHeader(Content body) { addConfigurationTitle(body); if (!utils.getBody(configuration.overviewElement).isEmpty()) { @@ -233,9 +223,9 @@ * "-overview" option on the command line. * * @param body the documentation tree to which the overview will be added - * @throws java.io.IOException */ - protected void addOverview(Content body) throws IOException { + @Override + protected void addOverview(Content body) { HtmlTree div = new HtmlTree(HtmlTag.DIV); div.addStyle(HtmlStyle.contentContainer); addOverviewComment(div); @@ -254,6 +244,7 @@ * * @param body the documentation tree to which the navigation bar header will be added */ + @Override protected void addNavigationBarHeader(Content body) { Content htmlTree = (configuration.allowTag(HtmlTag.HEADER)) ? HtmlTree.HEADER() @@ -271,6 +262,7 @@ * * @param body the documentation tree to which the navigation bar footer will be added */ + @Override protected void addNavigationBarFooter(Content body) { Content htmltree = (configuration.allowTag(HtmlTag.FOOTER)) ? HtmlTree.FOOTER() @@ -282,10 +274,12 @@ } } + @Override protected void addModulePackagesList(Map> modules, String text, String tableSummary, Content body, ModuleElement mdle) { } + @Override protected void addModulesList(Map> modules, String text, String tableSummary, Content body) { } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModulePackageIndexFrameWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModulePackageIndexFrameWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModulePackageIndexFrameWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.IOException; import java.util.ArrayList; import java.util.List; import java.util.Map; @@ -41,10 +40,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** * Generate the module package index for the left-hand frame in the generated output. @@ -66,29 +64,20 @@ * @param configuration the configuration object * @param filename Name of the package index file to be generated. */ - public ModulePackageIndexFrameWriter(ConfigurationImpl configuration, - DocPath filename) throws IOException { + public ModulePackageIndexFrameWriter(ConfigurationImpl configuration, DocPath filename) { super(configuration, filename); } /** * Generate the module package index file. - * @throws DocletAbortException + * @throws DocFileIOException * @param configuration the configuration object * @param mdle the module being documented */ - public static void generate(ConfigurationImpl configuration, ModuleElement mdle) { - ModulePackageIndexFrameWriter modpackgen; + public static void generate(ConfigurationImpl configuration, ModuleElement mdle) throws DocFileIOException { DocPath filename = DocPaths.moduleFrame(mdle); - try { - modpackgen = new ModulePackageIndexFrameWriter(configuration, filename); - modpackgen.buildModulePackagesIndexFile("doclet.Window_Overview", false, mdle); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + ModulePackageIndexFrameWriter modpackgen = new ModulePackageIndexFrameWriter(configuration, filename); + modpackgen.buildModulePackagesIndexFile("doclet.Window_Overview", false, mdle); } /** diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriterImpl.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.ArrayList; import java.util.EnumMap; import java.util.List; @@ -46,8 +45,8 @@ import jdk.javadoc.internal.doclets.toolkit.Content; import jdk.javadoc.internal.doclets.toolkit.ModuleSummaryWriter; import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** * Class to generate file for each module contents in the right-hand @@ -515,12 +514,8 @@ * @param subDiv the content tree to which the summary detail links will be added */ protected void addSummaryDetailLinks(Content subDiv) { - try { - Content div = HtmlTree.DIV(getNavSummaryLinks()); - subDiv.addContent(div); - } catch (Exception e) { - throw new DocletAbortException(e); - } + Content div = HtmlTree.DIV(getNavSummaryLinks()); + subDiv.addContent(div); } /** @@ -528,7 +523,7 @@ * * @return the content tree for the navigation summary links */ - protected Content getNavSummaryLinks() throws Exception { + protected Content getNavSummaryLinks() { Content li = HtmlTree.LI(contents.moduleSubNavLabel); li.addContent(Contents.SPACE); Content ulNav = HtmlTree.UL(HtmlStyle.subNavList, li); @@ -591,7 +586,8 @@ /** * {@inheritDoc} */ - public void printDocument(Content contentTree) throws IOException { + @Override + public void printDocument(Content contentTree) throws DocFileIOException { printHtmlDocument(configuration.metakeywords.getMetaKeywordsForModule(mdle), true, contentTree); } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageFrameWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.PackageElement; @@ -38,10 +37,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Configuration; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** @@ -62,7 +60,7 @@ /** * The package being documented. */ - private PackageElement packageElement; + private final PackageElement packageElement; /** * The classes to be documented. Use this to filter out classes @@ -96,35 +94,29 @@ * * @param configuration the current configuration of the doclet. * @param packageElement The package for which "pacakge-frame.html" is to be generated. + * @throws DocFileIOException if there is a problem generating the package summary page */ - public static void generate(ConfigurationImpl configuration, PackageElement packageElement) { - PackageFrameWriter packgen; - try { - packgen = new PackageFrameWriter(configuration, packageElement); - String pkgName = configuration.utils.getPackageName(packageElement); - HtmlTree body = packgen.getBody(false, packgen.getWindowTitle(pkgName)); - Content pkgNameContent = new StringContent(pkgName); - HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN)) - ? HtmlTree.MAIN() - : body; - Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, HtmlStyle.bar, - packgen.getTargetPackageLink(packageElement, "classFrame", pkgNameContent)); - htmlTree.addContent(heading); - HtmlTree div = new HtmlTree(HtmlTag.DIV); - div.addStyle(HtmlStyle.indexContainer); - packgen.addClassListing(div); - htmlTree.addContent(div); - if (configuration.allowTag(HtmlTag.MAIN)) { - body.addContent(htmlTree); - } - packgen.printHtmlDocument( - configuration.metakeywords.getMetaKeywords(packageElement), false, body); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), DocPaths.PACKAGE_FRAME.getPath()); - throw new DocletAbortException(exc); + public static void generate(ConfigurationImpl configuration, PackageElement packageElement) + throws DocFileIOException { + PackageFrameWriter packgen = new PackageFrameWriter(configuration, packageElement); + String pkgName = configuration.utils.getPackageName(packageElement); + HtmlTree body = packgen.getBody(false, packgen.getWindowTitle(pkgName)); + Content pkgNameContent = new StringContent(pkgName); + HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN)) + ? HtmlTree.MAIN() + : body; + Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, HtmlStyle.bar, + packgen.getTargetPackageLink(packageElement, "classFrame", pkgNameContent)); + htmlTree.addContent(heading); + HtmlTree div = new HtmlTree(HtmlTag.DIV); + div.addStyle(HtmlStyle.indexContainer); + packgen.addClassListing(div); + htmlTree.addContent(div); + if (configuration.allowTag(HtmlTag.MAIN)) { + body.addContent(htmlTree); } + packgen.printHtmlDocument( + configuration.metakeywords.getMetaKeywords(packageElement), false, body); } /** @@ -168,7 +160,7 @@ /** * Add specific class kind listing. Also add label to the listing. * - * @param arr Array of specific class kinds, namely Class or Interface or Exception or Error + * @param list list of specific class kinds, namely Class or Interface or Exception or Error * @param labelContent content tree of the label to be added * @param contentTree the content tree to which the class kind listing will be added */ diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageIndexFrameWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageIndexFrameWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageIndexFrameWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.IOException; import java.util.Collection; import javax.lang.model.element.PackageElement; @@ -37,10 +36,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** @@ -62,32 +60,24 @@ * * @param filename Name of the package index file to be generated. */ - public PackageIndexFrameWriter(ConfigurationImpl configuration, - DocPath filename) throws IOException { + public PackageIndexFrameWriter(ConfigurationImpl configuration, DocPath filename) { super(configuration, filename); } /** * Generate the package index file named "overview-frame.html". - * @throws DocletAbortException + * @throws DocFileIOException */ - public static void generate(ConfigurationImpl configuration) { - PackageIndexFrameWriter packgen; + public static void generate(ConfigurationImpl configuration) throws DocFileIOException { DocPath filename = DocPaths.OVERVIEW_FRAME; - try { - packgen = new PackageIndexFrameWriter(configuration, filename); - packgen.buildPackageIndexFile("doclet.Window_Overview", false); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + PackageIndexFrameWriter packgen = new PackageIndexFrameWriter(configuration, filename); + packgen.buildPackageIndexFile("doclet.Window_Overview", false); } /** * {@inheritDoc} */ + @Override protected void addPackagesList(Collection packages, String text, String tableSummary, Content body) { Content heading = HtmlTree.HEADING(HtmlConstants.PACKAGE_HEADING, true, @@ -135,6 +125,7 @@ /** * {@inheritDoc} */ + @Override protected void addNavigationBarHeader(Content body) { Content headerContent; if (configuration.packagesheader.length() > 0) { @@ -150,6 +141,7 @@ /** * Do nothing as there is no overview information in this page. */ + @Override protected void addOverviewHeader(Content body) { } @@ -159,6 +151,7 @@ * * @param ul the Content object to which the "All Classes" link should be added */ + @Override protected void addAllClassesLink(Content ul) { Content linkContent = getHyperLink(DocPaths.ALLCLASSES_FRAME, contents.allClassesLabel, "", "packageFrame"); @@ -172,6 +165,7 @@ * * @param ul the Content object to which the "All Modules" link should be added */ + @Override protected void addAllModulesLink(Content ul) { Content linkContent = getHyperLink(DocPaths.MODULE_OVERVIEW_FRAME, contents.allModulesLabel, "", "packageListFrame"); @@ -182,6 +176,7 @@ /** * {@inheritDoc} */ + @Override protected void addNavigationBarFooter(Content body) { Content p = HtmlTree.P(Contents.SPACE); body.addContent(p); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageIndexWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageIndexWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageIndexWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,22 +25,19 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.PackageElement; -import jdk.javadoc.doclet.DocletEnvironment; import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.Group; /** @@ -58,38 +55,35 @@ */ public class PackageIndexWriter extends AbstractPackageIndexWriter { - /** - * Root of the program structure. Used for "overview" documentation. - */ - private DocletEnvironment docEnv; /** * Map representing the group of packages as specified on the command line. * * @see Group */ - private Map> groupPackageMap; + private final Map> groupPackageMap; /** * List to store the order groups as specified on the command line. */ - private List groupList; + private final List groupList; /** * HTML tree for main tag. */ - private HtmlTree htmlTree = HtmlTree.MAIN(); + private final HtmlTree htmlTree = HtmlTree.MAIN(); /** * Construct the PackageIndexWriter. Also constructs the grouping * information as provided on the command line by "-group" option. Stores * the order of groups specified by the user. * + * @param configuration the configuration for this doclet + * @param filename the path of the page to be generated * @see Group */ - public PackageIndexWriter(ConfigurationImpl configuration, DocPath filename) throws IOException { + public PackageIndexWriter(ConfigurationImpl configuration, DocPath filename) { super(configuration, filename); - this.docEnv = configuration.docEnv; groupPackageMap = configuration.group.groupPackages(packages); groupList = configuration.group.getGroupList(); } @@ -98,19 +92,12 @@ * Generate the package index page for the right-hand frame. * * @param configuration the current configuration of the doclet. + * @throws DocFileIOException if there is a problem generating the package index page */ - public static void generate(ConfigurationImpl configuration) { - PackageIndexWriter packgen; + public static void generate(ConfigurationImpl configuration) throws DocFileIOException { DocPath filename = DocPaths.overviewSummary(configuration.frames); - try { - packgen = new PackageIndexWriter(configuration, filename); - packgen.buildPackageIndexFile("doclet.Window_Overview_Summary", true); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + PackageIndexWriter packgen = new PackageIndexWriter(configuration, filename); + packgen.buildPackageIndexFile("doclet.Window_Overview_Summary", true); } /** @@ -119,6 +106,7 @@ * * @param body the documentation tree to which the index will be added */ + @Override protected void addIndex(Content body) { for (String groupname : groupList) { SortedSet list = groupPackageMap.get(groupname); @@ -133,6 +121,7 @@ /** * {@inheritDoc} */ + @Override protected void addPackagesList(Collection packages, String text, String tableSummary, Content body) { Content table = (configuration.isOutputHtml5()) @@ -183,6 +172,7 @@ * * @param body the documentation tree to which the overview header will be added */ + @Override protected void addOverviewHeader(Content body) { addConfigurationTitle(body); if (!utils.getBody(configuration.overviewElement).isEmpty()) { @@ -227,7 +217,8 @@ * * @param body the documentation tree to which the overview will be added */ - protected void addOverview(Content body) throws IOException { + @Override + protected void addOverview(Content body) { HtmlTree div = new HtmlTree(HtmlTag.DIV); div.addStyle(HtmlStyle.contentContainer); addOverviewComment(div); @@ -246,6 +237,7 @@ * * @param body the documentation tree to which the navigation bar header will be added */ + @Override protected void addNavigationBarHeader(Content body) { Content htmlTree = (configuration.allowTag(HtmlTag.HEADER)) ? HtmlTree.HEADER() @@ -263,6 +255,7 @@ * * @param body the documentation tree to which the navigation bar footer will be added */ + @Override protected void addNavigationBarFooter(Content body) { Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER)) ? HtmlTree.FOOTER() diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageTreeWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageTreeWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageTreeWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,8 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; - import javax.lang.model.element.PackageElement; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlConstants; @@ -34,11 +32,10 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTag; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; import jdk.javadoc.internal.doclets.toolkit.util.ClassTree; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** @@ -77,14 +74,11 @@ * @param packageElement the current package * @param prev the previous package * @param next the next package - * @throws IOException - * @throws DocletAbortException */ public PackageTreeWriter(ConfigurationImpl configuration, DocPath path, PackageElement packageElement, - PackageElement prev, PackageElement next) - throws IOException { + PackageElement prev, PackageElement next) { super(configuration, path, new ClassTree(configuration.typeElementCatalog.allClasses(packageElement), configuration)); this.packageElement = packageElement; @@ -102,30 +96,22 @@ * @param next Next package in the alpha-ordered list. * @param noDeprecated If true, do not generate any information for * deprecated classe or interfaces. - * @throws DocletAbortException + * @throws DocFileIOException if there is a problem generating the package tree page */ public static void generate(ConfigurationImpl configuration, PackageElement pkg, PackageElement prev, - PackageElement next, boolean noDeprecated) { - PackageTreeWriter packgen; + PackageElement next, boolean noDeprecated) + throws DocFileIOException { DocPath path = DocPath.forPackage(pkg).resolve(DocPaths.PACKAGE_TREE); - try { - packgen = new PackageTreeWriter(configuration, path, pkg, - prev, next); - packgen.generatePackageTreeFile(); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), path.getPath()); - throw new DocletAbortException(exc); - } + PackageTreeWriter packgen = new PackageTreeWriter(configuration, path, pkg, prev, next); + packgen.generatePackageTreeFile(); } /** * Generate a separate tree file for each package. - * @throws java.io.IOException + * @throws DocFileIOException if there is a problem generating the package tree file */ - protected void generatePackageTreeFile() throws IOException { + protected void generatePackageTreeFile() throws DocFileIOException { HtmlTree body = getPackageTreeHeader(); HtmlTree htmlTree = (configuration.allowTag(HtmlTag.MAIN)) ? HtmlTree.MAIN() @@ -200,6 +186,7 @@ * * @return a content tree for the link */ + @Override protected Content getNavLinkPrevious() { if (prev == null) { return getNavLinkPrevious(null); @@ -214,6 +201,7 @@ * * @return a content tree for the link */ + @Override protected Content getNavLinkNext() { if (next == null) { return getNavLinkNext(null); @@ -241,6 +229,7 @@ * * @return a content tree for the package link */ + @Override protected Content getNavLinkPackage() { Content linkContent = getHyperLink(DocPaths.PACKAGE_SUMMARY, contents.packageLabel); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageUseWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageUseWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageUseWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.PackageElement; @@ -38,11 +37,10 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; import jdk.javadoc.internal.doclets.toolkit.util.ClassUseMapper; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** * Generate package usage information. @@ -65,12 +63,10 @@ * Constructor. * * @param filename the file to be generated. - * @throws IOException - * @throws DocletAbortException */ public PackageUseWriter(ConfigurationImpl configuration, ClassUseMapper mapper, DocPath filename, - PackageElement pkgElement) throws IOException { + PackageElement pkgElement) { super(configuration, DocPath.forPackage(pkgElement).resolve(filename)); this.packageElement = pkgElement; @@ -101,25 +97,21 @@ * @param configuration the current configuration of the doclet. * @param mapper the mapping of the class usage. * @param pkgElement the package being documented. + * @throws DocFileIOException if there is a problem generating the package use page */ public static void generate(ConfigurationImpl configuration, - ClassUseMapper mapper, PackageElement pkgElement) { - PackageUseWriter pkgusegen; + ClassUseMapper mapper, PackageElement pkgElement) + throws DocFileIOException { DocPath filename = DocPaths.PACKAGE_USE; - try { - pkgusegen = new PackageUseWriter(configuration, mapper, filename, pkgElement); - pkgusegen.generatePackageUseFile(); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error(exc.toString(), filename); - throw new DocletAbortException(exc); - } + PackageUseWriter pkgusegen = new PackageUseWriter(configuration, mapper, filename, pkgElement); + pkgusegen.generatePackageUseFile(); } /** * Generate the package use list. + * @throws DocFileIOException if there is a problem generating the package use page */ - protected void generatePackageUseFile() throws IOException { + protected void generatePackageUseFile() throws DocFileIOException { HtmlTree body = getPackageUseHeader(); HtmlTree div = new HtmlTree(HtmlTag.DIV); div.addStyle(HtmlStyle.contentContainer); @@ -150,7 +142,7 @@ * * @param contentTree the content tree to which the package use information will be added */ - protected void addPackageUse(Content contentTree) throws IOException { + protected void addPackageUse(Content contentTree) { HtmlTree ul = new HtmlTree(HtmlTag.UL); ul.addStyle(HtmlStyle.blockList); if (configuration.packages.size() > 1) { @@ -165,7 +157,7 @@ * * @param contentTree the content tree to which the package list will be added */ - protected void addPackageList(Content contentTree) throws IOException { + protected void addPackageList(Content contentTree) { Content caption = getTableCaption(configuration.getContent( "doclet.ClassUse_Packages.that.use.0", getPackageLink(packageElement, utils.getPackageName(packageElement)))); @@ -193,7 +185,7 @@ * * @param contentTree the content tree to which the class list will be added */ - protected void addClassList(Content contentTree) throws IOException { + protected void addClassList(Content contentTree) { List classTableHeader = Arrays.asList( configuration.getText("doclet.0_and_1", configuration.getText("doclet.Class"), @@ -254,7 +246,7 @@ * @param pkg the package that used the given package * @param contentTree the content tree to which the information will be added */ - protected void addPackageUse(PackageElement pkg, Content contentTree) throws IOException { + protected void addPackageUse(PackageElement pkg, Content contentTree) { Content tdFirst = HtmlTree.TD(HtmlStyle.colFirst, getHyperLink(utils.getPackageName(pkg), new StringContent(utils.getPackageName(pkg)))); @@ -320,6 +312,7 @@ * * @return a content tree for the package link */ + @Override protected Content getNavLinkPackage() { Content linkContent = getHyperLink(DocPaths.PACKAGE_SUMMARY, contents.packageLabel); @@ -332,6 +325,7 @@ * * @return a content tree for the use link */ + @Override protected Content getNavLinkClassUse() { Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.useLabel); return li; @@ -342,6 +336,7 @@ * * @return a content tree for the tree link */ + @Override protected Content getNavLinkTree() { Content linkContent = getHyperLink(DocPaths.PACKAGE_TREE, contents.treeLabel); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.ModuleElement; @@ -42,6 +41,7 @@ import jdk.javadoc.internal.doclets.toolkit.Content; import jdk.javadoc.internal.doclets.toolkit.PackageSummaryWriter; import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; @@ -112,6 +112,7 @@ /** * {@inheritDoc} */ + @Override public Content getPackageHeader(String heading) { HtmlTree bodyTree = getBody(true, getWindowTitle(utils.getPackageName(packageElement))); HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER)) @@ -166,6 +167,7 @@ /** * {@inheritDoc} */ + @Override public Content getContentHeader() { HtmlTree div = new HtmlTree(HtmlTag.DIV); div.addStyle(HtmlStyle.contentContainer); @@ -198,6 +200,7 @@ /** * {@inheritDoc} */ + @Override public Content getSummaryHeader() { HtmlTree ul = new HtmlTree(HtmlTag.UL); ul.addStyle(HtmlStyle.blockList); @@ -207,6 +210,7 @@ /** * {@inheritDoc} */ + @Override public void addClassesSummary(SortedSet classes, String label, String tableSummary, List tableHeader, Content summaryContentTree) { if(!classes.isEmpty()) { @@ -252,6 +256,7 @@ /** * {@inheritDoc} */ + @Override public void addPackageDescription(Content packageContentTree) { if (!utils.getBody(packageElement).isEmpty()) { packageContentTree.addContent( @@ -273,6 +278,7 @@ /** * {@inheritDoc} */ + @Override public void addPackageTags(Content packageContentTree) { Content htmlTree = (configuration.allowTag(HtmlTag.SECTION)) ? sectionTree @@ -283,6 +289,7 @@ /** * {@inheritDoc} */ + @Override public void addPackageContent(Content contentTree, Content packageContentTree) { if (configuration.allowTag(HtmlTag.MAIN)) { packageContentTree.addContent(sectionTree); @@ -296,6 +303,7 @@ /** * {@inheritDoc} */ + @Override public void addPackageFooter(Content contentTree) { Content htmlTree = (configuration.allowTag(HtmlTag.FOOTER)) ? HtmlTree.FOOTER() @@ -310,7 +318,8 @@ /** * {@inheritDoc} */ - public void printDocument(Content contentTree) throws IOException { + @Override + public void printDocument(Content contentTree) throws DocFileIOException { printHtmlDocument(configuration.metakeywords.getMetaKeywords(packageElement), true, contentTree); } @@ -320,6 +329,7 @@ * * @return a content tree for the class use link */ + @Override protected Content getNavLinkClassUse() { Content useLink = getHyperLink(DocPaths.PACKAGE_USE, contents.useLabel, "", ""); @@ -332,6 +342,7 @@ * * @return a content tree for the previous link */ + @Override public Content getNavLinkPrevious() { Content li; if (prev == null) { @@ -349,6 +360,7 @@ * * @return a content tree for the next link */ + @Override public Content getNavLinkNext() { Content li; if (next == null) { @@ -367,6 +379,7 @@ * * @return a content tree for the tree link */ + @Override protected Content getNavLinkTree() { Content useLink = getHyperLink(DocPaths.PACKAGE_TREE, contents.treeLabel, "", ""); @@ -392,6 +405,7 @@ * * @return a content tree for the package link */ + @Override protected Content getNavLinkPackage() { Content li = HtmlTree.LI(HtmlStyle.navBarCell1Rev, contents.packageLabel); return li; diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriterImpl.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import javax.lang.model.element.TypeElement; @@ -39,8 +38,8 @@ import jdk.javadoc.internal.doclets.toolkit.SerializedFormWriter; import jdk.javadoc.internal.doclets.toolkit.SerializedFormWriter.SerialFieldWriter; import jdk.javadoc.internal.doclets.toolkit.SerializedFormWriter.SerialMethodWriter; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** * Generate the Serialized Form Information Page. @@ -64,11 +63,8 @@ /** * @param configuration the configuration data for the doclet - * @throws IOException - * @throws DocletAbortException */ - public SerializedFormWriterImpl(ConfigurationImpl configuration) - throws IOException { + public SerializedFormWriterImpl(ConfigurationImpl configuration) { super(configuration, DocPaths.SERIALIZED_FORM); visibleClasses = configuration.docEnv.getIncludedTypeElements(); } @@ -277,7 +273,8 @@ /** * {@inheritDoc} */ - public void printDocument(Content serializedTree) throws IOException { + @Override + public void printDocument(Content serializedTree) throws DocFileIOException { printHtmlDocument(null, true, serializedTree); } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SingleIndexWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SingleIndexWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SingleIndexWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.*; import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle; @@ -33,10 +32,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder; @@ -62,42 +60,37 @@ * Construct the SingleIndexWriter with filename "index-all.html" and the * {@link IndexBuilder} * + * @param configuration the configuration for this doclet * @param filename Name of the index file to be generated. * @param indexbuilder Unicode based Index from {@link IndexBuilder} */ public SingleIndexWriter(ConfigurationImpl configuration, DocPath filename, - IndexBuilder indexbuilder) throws IOException { + IndexBuilder indexbuilder) { super(configuration, filename, indexbuilder); } /** * Generate single index file, for all Unicode characters. * + * @param configuration the configuration for this doclet * @param indexbuilder IndexBuilder built by {@link IndexBuilder} - * @throws DocletAbortException + * @throws DocFileIOException if there is a problem generating the index */ public static void generate(ConfigurationImpl configuration, - IndexBuilder indexbuilder) { - SingleIndexWriter indexgen; + IndexBuilder indexbuilder) throws DocFileIOException { DocPath filename = DocPaths.INDEX_ALL; - try { - indexgen = new SingleIndexWriter(configuration, - filename, indexbuilder); - indexgen.generateIndexFile(); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + SingleIndexWriter indexgen = new SingleIndexWriter(configuration, + filename, indexbuilder); + indexgen.generateIndexFile(); } /** * Generate the contents of each index file, with Header, Footer, * Member Field, Method and Constructor Description. + * @throws DocFileIOException if there is a problem generating the index */ - protected void generateIndexFile() throws IOException { + protected void generateIndexFile() throws DocFileIOException { String title = configuration.getText("doclet.Window_Single_Index"); HtmlTree body = getBody(true, getWindowTitle(title)); HtmlTree htmlTree = (configuration.allowTag(HtmlTag.HEADER)) diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SourceToHTMLConverter.java Mon Aug 22 16:32:40 2016 -0700 @@ -42,10 +42,11 @@ import jdk.javadoc.internal.doclets.toolkit.Content; import jdk.javadoc.internal.doclets.toolkit.Messages; import jdk.javadoc.internal.doclets.toolkit.util.DocFile; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; +import jdk.javadoc.internal.doclets.toolkit.util.SimpleDocletException; import jdk.javadoc.internal.doclets.toolkit.util.Utils; /** @@ -79,7 +80,7 @@ private final DocletEnvironment docEnv; - private DocPath outputdir; + private final DocPath outputdir; /** * Relative path from the documentation root to the file that is being @@ -102,13 +103,15 @@ * @param configuration the configuration. * @param docEnv the DocletEnvironment to convert. * @param outputdir the name of the directory to output to. + * @throws DocFileIOException if there is a problem generating an output file + * @throws SimpleDocletException if there is a problem reading a source file */ public static void convertRoot(ConfigurationImpl configuration, DocletEnvironment docEnv, - DocPath outputdir) { + DocPath outputdir) throws DocFileIOException, SimpleDocletException { new SourceToHTMLConverter(configuration, docEnv, outputdir).generate(); } - void generate() { + void generate() throws DocFileIOException, SimpleDocletException { if (docEnv == null || outputdir == null) { return; } @@ -129,12 +132,15 @@ } /** - * Convert the Classes in the given Package to an HTML. + * Convert the Classes in the given Package to an HTML file. * * @param pkg the Package to convert. * @param outputdir the name of the directory to output to. + * @throws DocFileIOException if there is a problem generating an output file + * @throws SimpleDocletException if there is a problem reading a source file */ - public void convertPackage(PackageElement pkg, DocPath outputdir) { + public void convertPackage(PackageElement pkg, DocPath outputdir) + throws DocFileIOException, SimpleDocletException { if (pkg == null) { return; } @@ -152,16 +158,20 @@ * Convert the given Class to an HTML. * * @param te the class to convert. - * @param outputdir the name of the directory to output to. + * @param outputdir the name of the directory to output to + * @throws DocFileIOException if there is a problem generating the output file + * @throws SimpleDocletException if there is a problem reading the source file */ - public void convertClass(TypeElement te, DocPath outputdir) { + public void convertClass(TypeElement te, DocPath outputdir) + throws DocFileIOException, SimpleDocletException { if (te == null) { return; } + FileObject fo = utils.getFileObject(te); + if (fo == null) + return; + try { - FileObject fo = utils.getFileObject(te); - if (fo == null) - return; Reader r = fo.openReader(true); int lineno = 1; String line; @@ -182,7 +192,8 @@ body.addContent((configuration.allowTag(HtmlTag.MAIN)) ? HtmlTree.MAIN(div) : div); writeToFile(body, outputdir.resolve(DocPath.forClass(utils, te))); } catch (IOException e) { - throw new DocletAbortException(e); + String message = configuration.resources.getText("doclet.exception.read.file", fo.getName()); + throw new SimpleDocletException(message, e); } } @@ -192,7 +203,7 @@ * @param body the documentation content to be written to the file. * @param path the path for the file. */ - private void writeToFile(Content body, DocPath path) throws IOException { + private void writeToFile(Content body, DocPath path) throws DocFileIOException { Content htmlDocType = configuration.isOutputHtml5() ? DocType.HTML5 : DocType.TRANSITIONAL; @@ -207,6 +218,8 @@ DocFile df = DocFile.createFileForOutput(configuration, path); try (Writer w = df.openWriter()) { htmlDocument.write(w, true); + } catch (IOException e) { + throw new DocFileIOException(df, DocFileIOException.Mode.WRITE, e); } } @@ -287,9 +300,10 @@ } /** - * Given a Doc, return an anchor name for it. + * Given an element, return an anchor name for it. * - * @param d the Doc to check. + * @param utils the utility class, used to get the line number of the element + * @param e the element to check. * @return the name of the anchor. */ public static String getAnchorName(Utils utils, Element e) { diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SplitIndexWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SplitIndexWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SplitIndexWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.*; import java.util.ArrayList; import java.util.Collection; import java.util.List; @@ -38,10 +37,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder; @@ -71,20 +69,24 @@ */ protected int next; - private List indexElements; + private final List indexElements; /** * Construct the SplitIndexWriter. Uses path to this file and relative path * from this file. * + * @param configuration the configuration for this doclet * @param path Path to the file which is getting generated. * @param indexbuilder Unicode based Index from {@link IndexBuilder} + * @param elements the collection of characters for which to generate index files + * @param prev the previous character that was indexed + * @param next the next character to be indexed */ public SplitIndexWriter(ConfigurationImpl configuration, DocPath path, IndexBuilder indexbuilder, Collection elements, - int prev, int next) throws IOException { + int prev, int next) { super(configuration, path, indexbuilder); this.indexElements = new ArrayList<>(elements); this.prev = prev; @@ -95,34 +97,26 @@ * Generate separate index files, for each Unicode character, listing all * the members starting with the particular unicode character. * + * @param configuration the configuration for this doclet * @param indexbuilder IndexBuilder built by {@link IndexBuilder} - * @throws DocletAbortException + * @throws DocFileIOException if there is a problem generating the index files */ public static void generate(ConfigurationImpl configuration, - IndexBuilder indexbuilder) { - SplitIndexWriter indexgen; - DocPath filename = DocPath.empty; + IndexBuilder indexbuilder) throws DocFileIOException { DocPath path = DocPaths.INDEX_FILES; - try { - Set keys = new TreeSet<>(indexbuilder.getIndexMap().keySet()); - keys.addAll(configuration.tagSearchIndexKeys); - ListIterator li = new ArrayList<>(keys).listIterator(); - while (li.hasNext()) { - Object ch = li.next(); - filename = DocPaths.indexN(li.nextIndex()); - indexgen = new SplitIndexWriter(configuration, - path.resolve(filename), - indexbuilder, keys, li.previousIndex(), li.nextIndex()); - indexgen.generateIndexFile((Character) ch); - if (!li.hasNext()) { - indexgen.createSearchIndexFiles(); - } + Set keys = new TreeSet<>(indexbuilder.getIndexMap().keySet()); + keys.addAll(configuration.tagSearchIndexKeys); + ListIterator li = new ArrayList<>(keys).listIterator(); + while (li.hasNext()) { + Object ch = li.next(); + DocPath filename = DocPaths.indexN(li.nextIndex()); + SplitIndexWriter indexgen = new SplitIndexWriter(configuration, + path.resolve(filename), + indexbuilder, keys, li.previousIndex(), li.nextIndex()); + indexgen.generateIndexFile((Character) ch); + if (!li.hasNext()) { + indexgen.createSearchIndexFiles(); } - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename.getPath()); - throw new DocletAbortException(exc); } } @@ -132,8 +126,9 @@ * * @param unicode Unicode character referring to the character for the * index. + * @throws DocFileIOException if there is a problem generating an index file */ - protected void generateIndexFile(Character unicode) throws IOException { + protected void generateIndexFile(Character unicode) throws DocFileIOException { String title = configuration.getText("doclet.Window_Split_Index", unicode.toString()); HtmlTree body = getBody(true, getWindowTitle(title)); @@ -188,6 +183,7 @@ * * @return a content tree for the link */ + @Override public Content getNavLinkPrevious() { Content prevletterLabel = contents.prevLetter; if (prev == -1) { @@ -205,6 +201,7 @@ * * @return a content tree for the link */ + @Override public Content getNavLinkNext() { Content nextletterLabel = contents.nextLetter; if (next == -1) { diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TreeWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TreeWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TreeWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.IOException; import java.util.SortedSet; import javax.lang.model.element.PackageElement; @@ -36,11 +35,10 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree; import jdk.javadoc.internal.doclets.formats.html.markup.StringContent; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.Messages; import jdk.javadoc.internal.doclets.toolkit.util.ClassTree; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** * Generate Class Hierarchy page for all the Classes in this run. Use @@ -67,7 +65,7 @@ * True if there are no packages specified on the command line, * False otherwise. */ - private boolean classesonly; + private final boolean classesOnly; /** * Constructor to construct TreeWriter object. @@ -76,39 +74,33 @@ * @param filename String filename * @param classtree the tree being built. */ - public TreeWriter(ConfigurationImpl configuration, - DocPath filename, ClassTree classtree) throws IOException { + public TreeWriter(ConfigurationImpl configuration, DocPath filename, ClassTree classtree) { super(configuration, filename, classtree); packages = configuration.packages; - classesonly = packages.isEmpty(); + classesOnly = packages.isEmpty(); } /** * Create a TreeWriter object and use it to generate the * "overview-tree.html" file. * + * @param configuration the configuration for this doclet * @param classtree the class tree being documented. - * @throws DocletAbortException + * @throws DocFileIOException if there is a problem generating the overview tree page */ public static void generate(ConfigurationImpl configuration, - ClassTree classtree) { - TreeWriter treegen; + ClassTree classtree) throws DocFileIOException { DocPath filename = DocPaths.OVERVIEW_TREE; - try { - treegen = new TreeWriter(configuration, filename, classtree); - treegen.generateTreeFile(); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), filename); - throw new DocletAbortException(exc); - } + TreeWriter treegen = new TreeWriter(configuration, filename, classtree); + treegen.generateTreeFile(); } /** * Generate the interface hierarchy and class hierarchy. + * + * @throws DocFileIOException if there is a problem generating the overview tree page */ - public void generateTreeFile() throws IOException { + public void generateTreeFile() throws DocFileIOException { HtmlTree body = getTreeHeader(); Content headContent = contents.hierarchyForAllPackages; Content heading = HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, false, @@ -152,7 +144,7 @@ if (isUnnamedPackage()) { return; } - if (!classesonly) { + if (!classesOnly) { Content span = HtmlTree.SPAN(HtmlStyle.packageHierarchyLabel, contents.packageHierarchies); contentTree.addContent(span); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/WriterFactoryImpl.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/WriterFactoryImpl.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/WriterFactoryImpl.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html; -import java.io.IOException; import javax.lang.model.element.ModuleElement; import javax.lang.model.element.PackageElement; @@ -69,7 +68,7 @@ * {@inheritDoc} */ @Override - public ConstantsSummaryWriter getConstantsSummaryWriter() throws Exception { + public ConstantsSummaryWriter getConstantsSummaryWriter() { return new ConstantsSummaryWriterImpl(configuration); } @@ -78,7 +77,7 @@ */ @Override public PackageSummaryWriter getPackageSummaryWriter(PackageElement packageElement, - PackageElement prevPkg, PackageElement nextPkg) throws Exception { + PackageElement prevPkg, PackageElement nextPkg) { return new PackageWriterImpl(configuration, packageElement, prevPkg, nextPkg); } @@ -86,7 +85,7 @@ * {@inheritDoc} */ public ModuleSummaryWriter getModuleSummaryWriter(ModuleElement mdle, - ModuleElement prevModule, ModuleElement nextModule) throws Exception { + ModuleElement prevModule, ModuleElement nextModule) { return new ModuleWriterImpl(configuration, mdle, prevModule, nextModule); } @@ -96,7 +95,7 @@ */ @Override public ClassWriter getClassWriter(TypeElement typeElement, TypeElement prevClass, - TypeElement nextClass, ClassTree classTree) throws IOException { + TypeElement nextClass, ClassTree classTree) { return new ClassWriterImpl(configuration, typeElement, prevClass, nextClass, classTree); } @@ -105,7 +104,7 @@ */ @Override public AnnotationTypeWriter getAnnotationTypeWriter(TypeElement annotationType, - TypeMirror prevType, TypeMirror nextType) throws Exception { + TypeMirror prevType, TypeMirror nextType) { return new AnnotationTypeWriterImpl(configuration, annotationType, prevType, nextType); } @@ -113,8 +112,8 @@ * {@inheritDoc} */ @Override - public AnnotationTypeFieldWriter - getAnnotationTypeFieldWriter(AnnotationTypeWriter annotationTypeWriter) throws Exception { + public AnnotationTypeFieldWriter getAnnotationTypeFieldWriter( + AnnotationTypeWriter annotationTypeWriter) { TypeElement te = annotationTypeWriter.getAnnotationTypeElement(); return new AnnotationTypeFieldWriterImpl( (SubWriterHolderWriter) annotationTypeWriter, te); @@ -124,9 +123,8 @@ * {@inheritDoc} */ @Override - public AnnotationTypeOptionalMemberWriter - getAnnotationTypeOptionalMemberWriter( - AnnotationTypeWriter annotationTypeWriter) throws Exception { + public AnnotationTypeOptionalMemberWriter getAnnotationTypeOptionalMemberWriter( + AnnotationTypeWriter annotationTypeWriter) { TypeElement te = annotationTypeWriter.getAnnotationTypeElement(); return new AnnotationTypeOptionalMemberWriterImpl( (SubWriterHolderWriter) annotationTypeWriter, te); @@ -136,8 +134,8 @@ * {@inheritDoc} */ @Override - public AnnotationTypeRequiredMemberWriter - getAnnotationTypeRequiredMemberWriter(AnnotationTypeWriter annotationTypeWriter) throws Exception { + public AnnotationTypeRequiredMemberWriter getAnnotationTypeRequiredMemberWriter( + AnnotationTypeWriter annotationTypeWriter) { TypeElement te = annotationTypeWriter.getAnnotationTypeElement(); return new AnnotationTypeRequiredMemberWriterImpl( (SubWriterHolderWriter) annotationTypeWriter, te); @@ -147,8 +145,7 @@ * {@inheritDoc} */ @Override - public EnumConstantWriterImpl getEnumConstantWriter(ClassWriter classWriter) - throws Exception { + public EnumConstantWriterImpl getEnumConstantWriter(ClassWriter classWriter) { return new EnumConstantWriterImpl((SubWriterHolderWriter) classWriter, classWriter.getTypeElement()); } @@ -157,8 +154,7 @@ * {@inheritDoc} */ @Override - public FieldWriterImpl getFieldWriter(ClassWriter classWriter) - throws Exception { + public FieldWriterImpl getFieldWriter(ClassWriter classWriter) { return new FieldWriterImpl((SubWriterHolderWriter) classWriter, classWriter.getTypeElement()); } @@ -166,8 +162,7 @@ * {@inheritDoc} */ @Override - public PropertyWriterImpl getPropertyWriter(ClassWriter classWriter) - throws Exception { + public PropertyWriterImpl getPropertyWriter(ClassWriter classWriter) { return new PropertyWriterImpl((SubWriterHolderWriter) classWriter, classWriter.getTypeElement()); } @@ -176,8 +171,7 @@ * {@inheritDoc} */ @Override - public MethodWriterImpl getMethodWriter(ClassWriter classWriter) - throws Exception { + public MethodWriterImpl getMethodWriter(ClassWriter classWriter) { return new MethodWriterImpl((SubWriterHolderWriter) classWriter, classWriter.getTypeElement()); } @@ -185,8 +179,7 @@ * {@inheritDoc} */ @Override - public ConstructorWriterImpl getConstructorWriter(ClassWriter classWriter) - throws Exception { + public ConstructorWriterImpl getConstructorWriter(ClassWriter classWriter) { return new ConstructorWriterImpl((SubWriterHolderWriter) classWriter, classWriter.getTypeElement()); } @@ -195,9 +188,8 @@ * {@inheritDoc} */ @Override - public MemberSummaryWriter getMemberSummaryWriter( - ClassWriter classWriter, VisibleMemberMap.Kind memberType) - throws Exception { + public MemberSummaryWriter getMemberSummaryWriter(ClassWriter classWriter, + VisibleMemberMap.Kind memberType) { switch (memberType) { case CONSTRUCTORS: return getConstructorWriter(classWriter); @@ -221,9 +213,8 @@ * {@inheritDoc} */ @Override - public MemberSummaryWriter getMemberSummaryWriter( - AnnotationTypeWriter annotationTypeWriter, VisibleMemberMap.Kind memberType) - throws Exception { + public MemberSummaryWriter getMemberSummaryWriter(AnnotationTypeWriter annotationTypeWriter, + VisibleMemberMap.Kind memberType) { switch (memberType) { case ANNOTATION_TYPE_FIELDS: return (AnnotationTypeFieldWriterImpl) @@ -243,7 +234,7 @@ * {@inheritDoc} */ @Override - public SerializedFormWriter getSerializedFormWriter() throws Exception { + public SerializedFormWriter getSerializedFormWriter() { return new SerializedFormWriterImpl(configuration); } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Comment.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Comment.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Comment.java Mon Aug 22 16:32:40 2016 -0700 @@ -29,7 +29,6 @@ import java.io.Writer; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; /** @@ -59,25 +58,21 @@ * This method is not supported by the class. * * @param content content that needs to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ public void addContent(Content content) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** * This method is not supported by the class. * * @param stringContent string content that needs to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ @Override public void addContent(CharSequence stringContent) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/DocType.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/DocType.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/DocType.java Mon Aug 22 16:32:40 2016 -0700 @@ -29,7 +29,6 @@ import java.io.Writer; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; /** @@ -73,25 +72,21 @@ * This method is not supported by the class. * * @param content content that needs to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ public void addContent(Content content) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** * This method is not supported by the class. * * @param stringContent string content that needs to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ @Override public void addContent(CharSequence stringContent) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/FixedStringContent.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/FixedStringContent.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/FixedStringContent.java Mon Aug 22 16:32:40 2016 -0700 @@ -28,7 +28,6 @@ import java.io.Writer; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; /** @@ -57,13 +56,11 @@ * This method is not supported by the class. * * @param content content that needs to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ @Override public void addContent(Content content) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** @@ -71,13 +68,11 @@ * HTML characters for the string content that is added. * * @param strContent string content to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ @Override public void addContent(CharSequence strContent) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.formats.html.markup; -import java.io.*; import java.util.*; import javax.lang.model.element.ModuleElement; @@ -38,6 +37,7 @@ import jdk.javadoc.internal.doclets.toolkit.Content; import jdk.javadoc.internal.doclets.toolkit.Messages; import jdk.javadoc.internal.doclets.toolkit.util.DocFile; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocLink; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; @@ -66,6 +66,7 @@ * Constructor. Initializes the destination file name through the super * class HtmlWriter. * + * @param configuration the configuration for this doclet * @param filename String file name. */ public HtmlDocWriter(Configuration configuration, DocPath filename) { @@ -78,6 +79,7 @@ /** * Accessor for configuration. + * @return the configuration for this doclet */ public abstract Configuration configuration(); @@ -289,13 +291,9 @@ DocLink mtFrameLink = new DocLink(DocPaths.moduleTypeFrame(mdle)); DocLink cFrameLink = new DocLink(DocPaths.moduleSummary(mdle)); HtmlTree anchor = HtmlTree.A(mdlLink.toString(), label); - StringBuilder onclickStr = new StringBuilder("updateModuleFrame('") - .append(mtFrameLink.toString()) - .append("','") - .append(cFrameLink.toString()) - .append("');"); + String onclickStr = "updateModuleFrame('" + mtFrameLink + "','" + cFrameLink + "');"; anchor.addAttr(HtmlAttr.TARGET, target); - anchor.addAttr(HtmlAttr.ONCLICK, onclickStr.toString()); + anchor.addAttr(HtmlAttr.ONCLICK, onclickStr); return anchor; } @@ -318,9 +316,10 @@ * @param title Title of this HTML document * @param configuration the configuration object * @param body the body content tree to be added to the HTML document + * @throws DocFileIOException if there is an error writing the frames document */ public void printFramesDocument(String title, ConfigurationImpl configuration, - HtmlTree body) throws IOException { + HtmlTree body) throws DocFileIOException { Content htmlDocType = configuration.isOutputHtml5() ? DocType.HTML5 : DocType.TRANSITIONAL; @@ -345,6 +344,7 @@ /** * Returns a link to the stylesheet file. * + * @param configuration the configuration for this doclet * @return an HtmlTree for the lINK tag which provides the stylesheet location */ public HtmlTree getStyleSheetProperties(ConfigurationImpl configuration) { diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocument.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocument.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlDocument.java Mon Aug 22 16:32:40 2016 -0700 @@ -30,7 +30,6 @@ import java.util.*; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; /** * Class for generating an HTML document for javadoc output. @@ -86,13 +85,11 @@ * This method is not supported by the class. * * @param stringContent string content that needs to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ @Override public void addContent(CharSequence stringContent) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -32,6 +32,7 @@ import jdk.javadoc.internal.doclets.toolkit.Content; import jdk.javadoc.internal.doclets.toolkit.Resources; import jdk.javadoc.internal.doclets.toolkit.util.DocFile; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPath; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; import jdk.javadoc.internal.doclets.toolkit.util.MethodTypes; @@ -147,9 +148,11 @@ resources.getText("doclet.Type")); } - public void write(Content c) throws IOException { + public void write(Content c) throws DocFileIOException { try (Writer writer = docFile.openWriter()) { c.write(writer, true); + } catch (IOException e) { + throw new DocFileIOException(docFile, DocFileIOException.Mode.WRITE, e); } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/RawHtml.java Mon Aug 22 16:32:40 2016 -0700 @@ -29,7 +29,6 @@ import java.io.Writer; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; /** @@ -61,25 +60,21 @@ * This method is not supported by the class. * * @param content content that needs to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ public void addContent(Content content) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** * This method is not supported by the class. * * @param stringContent string content that needs to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ @Override public void addContent(CharSequence stringContent) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/StringContent.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/StringContent.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/StringContent.java Mon Aug 22 16:32:40 2016 -0700 @@ -29,7 +29,6 @@ import java.io.Writer; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; /** @@ -44,7 +43,7 @@ */ public class StringContent extends Content { - private StringBuilder stringContent; + private final StringBuilder stringContent; /** * Constructor to construct StringContent object. @@ -67,13 +66,11 @@ * This method is not supported by the class. * * @param content content that needs to be added - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it - * is not supported. + * @throws UnsupportedOperationException always */ @Override public void addContent(Content content) { - throw new DocletAbortException("not supported"); + throw new UnsupportedOperationException(); } /** diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties Mon Aug 22 16:32:40 2016 -0700 @@ -189,7 +189,6 @@ doclet.Error_in_packagelist=Error in using -group option: {0} {1} doclet.Groupname_already_used=In -group option, groupname already used: {0} doclet.Same_package_name_used=Package name format used twice: {0} -doclet.exception_encountered=Exception encountered while processing {1}\n{0} # option specifiers doclet.usage.d.parameters= diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AbstractDoclet.java Mon Aug 22 16:32:40 2016 -0700 @@ -34,12 +34,17 @@ import jdk.javadoc.doclet.Doclet; import jdk.javadoc.doclet.DocletEnvironment; +import jdk.javadoc.doclets.StandardDoclet; +import jdk.javadoc.internal.doclets.formats.html.HtmlDoclet; import jdk.javadoc.internal.doclets.toolkit.builders.AbstractBuilder; import jdk.javadoc.internal.doclets.toolkit.builders.BuilderFactory; import jdk.javadoc.internal.doclets.toolkit.util.ClassTree; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; +import jdk.javadoc.internal.doclets.toolkit.util.InternalException; import jdk.javadoc.internal.doclets.toolkit.util.PackageListWriter; +import jdk.javadoc.internal.doclets.toolkit.util.ResourceIOException; +import jdk.javadoc.internal.doclets.toolkit.util.SimpleDocletException; import jdk.javadoc.internal.doclets.toolkit.util.Utils; import static javax.tools.Diagnostic.Kind.*; @@ -107,30 +112,61 @@ return false; } + boolean dumpOnError = false; // set true to always show stack traces + try { startGeneration(docEnv); - } catch (Configuration.Fault f) { - configuration.reporter.print(ERROR, f.getMessage()); - return false; - } catch (DocletAbortException e) { - Throwable cause = e.getCause(); - if (cause != null) { - if (cause.getLocalizedMessage() != null) { - configuration.reporter.print(ERROR, cause.getLocalizedMessage()); - } else { - configuration.reporter.print(ERROR, cause.toString()); - } + return true; + + } catch (DocFileIOException e) { + switch (e.mode) { + case READ: + messages.error("doclet.exception.read.file", + e.fileName.getPath(), e.getCause()); + break; + case WRITE: + messages.error("doclet.exception.write.file", + e.fileName.getPath(), e.getCause()); } - return false; - } catch (Exception exc) { - exc.printStackTrace(System.err); - return false; + dumpStack(dumpOnError, e); + + } catch (ResourceIOException e) { + messages.error("doclet.exception.read.resource", + e.resource.getPath(), e.getCause()); + dumpStack(dumpOnError, e); + + } catch (SimpleDocletException e) { + configuration.reporter.print(ERROR, e.getMessage()); + dumpStack(dumpOnError, e); + + } catch (InternalException e) { + configuration.reporter.print(ERROR, e.getMessage()); + reportInternalError(e.getCause()); + + } catch (DocletException | RuntimeException | Error e) { + messages.error("doclet.internal.exception", e); + reportInternalError(e); } - return true; + + return false; + } + + private void reportInternalError(Throwable t) { + if (getClass().equals(StandardDoclet.class) || getClass().equals(HtmlDoclet.class)) { + System.err.println(configuration.getResources().getText("doclet.internal.report.bug")); + } + dumpStack(true, t); + } + + private void dumpStack(boolean enabled, Throwable t) { + if (enabled && t != null) { + t.printStackTrace(System.err); + } } /** * Returns the SourceVersion indicating the features supported by this doclet. + * * @return SourceVersion */ @Override @@ -141,6 +177,7 @@ /** * Create the configuration instance and returns it. + * * @return the configuration of the doclet. */ public abstract Configuration configuration(); @@ -152,8 +189,9 @@ * first and then can be used in the later generation. * * @see jdk.doclet.DocletEnvironment + * @throws DocletException if there is a problem while generating the documentation */ - private void startGeneration(DocletEnvironment docEnv) throws Configuration.Fault, Exception { + private void startGeneration(DocletEnvironment docEnv) throws DocletException { if (docEnv.getIncludedTypeElements().isEmpty()) { messages.error("doclet.No_Public_Classes_To_Document"); return; @@ -179,10 +217,12 @@ /** * Generate additional documentation that is added to the API documentation. * - * @param docEnv the DocletEnvironment. - * @param classtree the data structure representing the class tree. + * @param docEnv the DocletEnvironment + * @param classtree the data structure representing the class tree + * @throws DocletException if there is a problem while generating the documentation */ - protected void generateOtherFiles(DocletEnvironment docEnv, ClassTree classtree) throws Exception { + protected void generateOtherFiles(DocletEnvironment docEnv, ClassTree classtree) + throws DocletException { BuilderFactory builderFactory = configuration.getBuilderFactory(); AbstractBuilder constantsSummaryBuilder = builderFactory.getConstantsSummaryBuilder(); constantsSummaryBuilder.build(); @@ -193,50 +233,59 @@ /** * Generate the module documentation. * + * @throws DocletException if there is a problem while generating the documentation + * */ - protected abstract void generateModuleFiles() throws Exception; + protected abstract void generateModuleFiles() throws DocletException; /** * Generate the package documentation. * - * @param classtree the data structure representing the class tree. + * @param classtree the data structure representing the class tree + * @throws DocletException if there is a problem while generating the documentation */ - protected abstract void generatePackageFiles(ClassTree classtree) throws Exception; + protected abstract void generatePackageFiles(ClassTree classtree) throws DocletException; /** * Generate the class documentation. * - * @param classtree the data structure representing the class tree. + * @param arr the set of types to be documented + * @param classtree the data structure representing the class tree + * @throws DocletException if there is a problem while generating the documentation */ - protected abstract void generateClassFiles(SortedSet arr, ClassTree classtree); + protected abstract void generateClassFiles(SortedSet arr, ClassTree classtree) + throws DocletException; /** * Iterate through all classes and construct documentation for them. * - * @param docEnv the DocletEnvironment. - * @param classtree the data structure representing the class tree. + * @param docEnv the DocletEnvironment + * @param classtree the data structure representing the class tree + * @throws DocletException if there is a problem while generating the documentation */ - protected void generateClassFiles(DocletEnvironment docEnv, ClassTree classtree) { + protected void generateClassFiles(DocletEnvironment docEnv, ClassTree classtree) + throws DocletException { generateClassFiles(classtree); SortedSet packages = new TreeSet<>(utils.makePackageComparator()); packages.addAll(configuration.getSpecifiedPackages()); configuration.modulePackages.values().stream().forEach(pset -> { packages.addAll(pset); }); - packages.stream().forEach((pkg) -> { + for (PackageElement pkg : packages) { generateClassFiles(utils.getAllClasses(pkg), classtree); - }); + } } /** * Generate the class files for single classes specified on the command line. * - * @param classtree the data structure representing the class tree. + * @param classtree the data structure representing the class tree + * @throws DocletException if there is a problem while generating the documentation */ - private void generateClassFiles(ClassTree classtree) { + private void generateClassFiles(ClassTree classtree) throws DocletException { SortedSet packages = configuration.typeElementCatalog.packages(); - packages.stream().forEach((pkg) -> { + for (PackageElement pkg : packages) { generateClassFiles(configuration.typeElementCatalog.allClasses(pkg), classtree); - }); + } } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AnnotationTypeWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AnnotationTypeWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/AnnotationTypeWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,9 +25,9 @@ package jdk.javadoc.internal.doclets.toolkit; -import java.io.*; +import javax.lang.model.element.TypeElement; -import javax.lang.model.element.TypeElement; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; /** * The interface for writing annotation type output. @@ -152,8 +152,9 @@ * Print the document. * * @param contentTree content tree that will be printed as a document + * @throws DocFileIOException if there is a problem while writing the document */ - public void printDocument(Content contentTree) throws IOException; + public void printDocument(Content contentTree) throws DocFileIOException; /** * Return the {@link TypeElement} being documented. diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ClassWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ClassWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ClassWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,9 +25,9 @@ package jdk.javadoc.internal.doclets.toolkit; -import java.io.*; +import javax.lang.model.element.TypeElement; -import javax.lang.model.element.TypeElement; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; /** * The interface for writing class output. @@ -193,8 +193,9 @@ * Print the document. * * @param contentTree content tree that will be printed as a document + * @throws DocFileIOException if there is a problem while writing the document */ - public void printDocument(Content contentTree) throws IOException; + public void printDocument(Content contentTree) throws DocFileIOException; /** * Return the TypeElement being documented. diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Configuration.java Mon Aug 22 16:32:40 2016 -0700 @@ -44,11 +44,12 @@ import jdk.javadoc.internal.doclets.toolkit.taglets.TagletManager; import jdk.javadoc.internal.doclets.toolkit.util.DocFile; import jdk.javadoc.internal.doclets.toolkit.util.DocFileFactory; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.DocletConstants; import jdk.javadoc.internal.doclets.toolkit.util.Extern; import jdk.javadoc.internal.doclets.toolkit.util.Group; import jdk.javadoc.internal.doclets.toolkit.util.MetaKeywords; +import jdk.javadoc.internal.doclets.toolkit.util.SimpleDocletException; import jdk.javadoc.internal.doclets.toolkit.util.TypeElementCatalog; import jdk.javadoc.internal.doclets.toolkit.util.Utils; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap.GetterSetter; @@ -73,21 +74,6 @@ public abstract class Configuration { /** - * Exception used to report a problem during setOptions. - */ - public static class Fault extends Exception { - private static final long serialVersionUID = 0; - - Fault(String msg) { - super(msg); - } - - Fault(String msg, Exception cause) { - super(msg, cause); - } - } - - /** * The factory for builders. */ protected BuilderFactory builderFactory; @@ -105,7 +91,7 @@ /** * The default path to the builder XML. */ - private static final String DEFAULT_BUILDER_XML = "resources/doclet.xml"; + public static final String DEFAULT_BUILDER_XML = "resources/doclet.xml"; /** * The path to Taglets @@ -302,13 +288,17 @@ /** * Return the build date for the doclet. + * + * @return the build date */ public abstract String getDocletSpecificBuildDate(); /** - * This method should be defined in all those doclets(configurations), + * This method should be defined in all those doclets (configurations), * which want to derive themselves from this Configuration. This method * can be used to finish up the options setup. + * + * @return true if successful and false otherwise */ public abstract boolean finishOptionSettings(); @@ -638,8 +628,8 @@ * when this is called all the option have been set, this method, * initializes certain components before anything else is started. */ - private void finishOptionSettings0() throws Fault { - ensureOutputDirExists(); + private void finishOptionSettings0() throws DocletException { + initDestDirectory(); if (urlForLink != null && pkglistUrlForLink != null) extern.link(urlForLink, pkglistUrlForLink, reporter, false); if (urlForLinkOffline != null && pkglistUrlForLinkOffline != null) @@ -658,43 +648,42 @@ * Set the command line options supported by this configuration. * * @return true if the options are set successfully - * @throws DocletAbortException + * @throws DocletException if there is a problem while setting the options */ - public boolean setOptions() throws Fault { - try { - initPackages(); - initModules(); - finishOptionSettings0(); - if (!finishOptionSettings()) - return false; + public boolean setOptions() throws DocletException { + initPackages(); + initModules(); + finishOptionSettings0(); + if (!finishOptionSettings()) + return false; - } catch (Fault f) { - throw new DocletAbortException(f.getMessage()); - } return true; } - private void ensureOutputDirExists() throws Fault { - DocFile destDir = DocFile.createFileForDirectory(this, destDirName); - if (!destDir.exists()) { - //Create the output directory (in case it doesn't exist yet) - if (!destDirName.isEmpty()) + private void initDestDirectory() throws DocletException { + if (!destDirName.isEmpty()) { + DocFile destDir = DocFile.createFileForDirectory(this, destDirName); + if (!destDir.exists()) { + //Create the output directory (in case it doesn't exist yet) reporter.print(NOTE, getText("doclet.dest_dir_create", destDirName)); - destDir.mkdirs(); - } else if (!destDir.isDirectory()) { - throw new Fault(getText( - "doclet.destination_directory_not_directory_0", - destDir.getPath())); - } else if (!destDir.canWrite()) { - throw new Fault(getText( - "doclet.destination_directory_not_writable_0", - destDir.getPath())); + destDir.mkdirs(); + } else if (!destDir.isDirectory()) { + throw new SimpleDocletException(getText( + "doclet.destination_directory_not_directory_0", + destDir.getPath())); + } else if (!destDir.canWrite()) { + throw new SimpleDocletException(getText( + "doclet.destination_directory_not_writable_0", + destDir.getPath())); + } } + DocFileFactory.getFactory(this).setDestDir(destDirName); } /** * Initialize the taglet manager. The strings to initialize the simple custom tags should * be in the following format: "[tag name]:[location str]:[heading]". + * * @param customTagStrs the set two dimensional arrays of strings. These arrays contain * either -tag or -taglet arguments. */ @@ -819,7 +808,7 @@ if (!checkOutputFileEncoding(docencoding)) { return false; } - }; + } } if (!docencodingfound && (encoding != null && !encoding.isEmpty())) { if (!checkOutputFileEncoding(encoding)) { @@ -858,6 +847,7 @@ /** * Return true if the given doc-file subdirectory should be excluded and * false otherwise. + * * @param docfilesubdir the doc-files subdirectory to check. * @return true if the directory is excluded. */ @@ -867,7 +857,9 @@ /** * Return true if the given qualifier should be excluded and false otherwise. + * * @param qualifier the qualifier to check. + * @return true if the qualifier should be excluded */ public boolean shouldExcludeQualifier(String qualifier){ if (excludedQualifiers.contains("all") || @@ -888,6 +880,7 @@ /** * Return the qualified name of the Element if its qualifier is not excluded. * Otherwise return the unqualified Element name. + * * @param te the TypeElement to check. * @return the class name */ @@ -931,6 +924,7 @@ * Convenience method to obtain a resource from the doclet's * {@link Resources resources}. * Equivalent to getResources.getText(key);. + * * @param key the key for the desired string * @return the string for the given key * @throws MissingResourceException if the key is not found in either @@ -942,6 +936,7 @@ * Convenience method to obtain a resource from the doclet's * {@link Resources resources}. * Equivalent to getResources.getText(key, args);. + * * @param key the key for the desired string * @param args values to be substituted into the resulting string * @return the string for the given key @@ -1009,6 +1004,7 @@ /** * Return the doclet specific instance of a writer factory. + * * @return the {@link WriterFactory} for the doclet. */ public abstract WriterFactory getWriterFactory(); @@ -1017,9 +1013,9 @@ * Return the input stream to the builder XML. * * @return the input steam to the builder XML. - * @throws FileNotFoundException when the given XML file cannot be found. + * @throws DocFileIOException when the given XML file cannot be found or opened. */ - public InputStream getBuilderXML() throws IOException { + public InputStream getBuilderXML() throws DocFileIOException { return builderXMLPath == null ? Configuration.class.getResourceAsStream(DEFAULT_BUILDER_XML) : DocFile.createFileForInput(this, builderXMLPath).openInputStream(); @@ -1027,6 +1023,7 @@ /** * Return the Locale for this document. + * * @return the current locale */ public abstract Locale getLocale(); @@ -1040,6 +1037,7 @@ /** * Return the current file manager. + * * @return JavaFileManager */ public abstract JavaFileManager getFileManager(); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ConstantsSummaryWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ConstantsSummaryWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ConstantsSummaryWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,13 +25,14 @@ package jdk.javadoc.internal.doclets.toolkit; -import java.io.*; import java.util.*; import javax.lang.model.element.PackageElement; import javax.lang.model.element.TypeElement; import javax.lang.model.element.VariableElement; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; + /** * The interface for writing constants summary output. * @@ -144,7 +145,8 @@ * Print the constants summary document. * * @param contentTree content tree which should be printed + * @throws DocFileIOException if there is a problem while writing the document */ - public abstract void printDocument(Content contentTree) throws IOException; + public abstract void printDocument(Content contentTree) throws DocFileIOException; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Content.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Content.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/Content.java Mon Aug 22 16:32:40 2016 -0700 @@ -30,9 +30,6 @@ import java.io.Writer; import java.util.Objects; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; - - /** * A class to create content for javadoc output pages. * @@ -57,7 +54,7 @@ write(out, true); } catch (IOException e) { // cannot happen from StringWriter - throw new DocletAbortException(e); + throw new AssertionError(e); } return out.toString(); } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/DocletException.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/DocletException.java Mon Aug 22 16:32:40 2016 -0700 @@ -0,0 +1,72 @@ +/* + * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package jdk.javadoc.internal.doclets.toolkit; + + +/** + * Supertype for all checked doclet exceptions. + * + *

This is NOT part of any supported API. + * If you write code that depends on this, you do so at your own risk. + * This code and its internal interfaces are subject to change or + * deletion without notice. + * + * @apiNote This is primarily intended for the benefit of the builder API + * in {@code jdk.javadoc.internal.doclets.toolkit.builders}. + */ +public class DocletException extends Exception { + + private static final long serialVersionUID = 1L; + + /** + * Creates a DocletException with a given detail message. + * + * The message may or may not be intended for presentation to the end user. + * + * @param message the detail message. + */ + protected DocletException(String message) { + super(message); + if (message == null || message.isEmpty()) { + throw new IllegalArgumentException(); + } + } + + /** + * Creates a DocletException with a given detail message and underlying cause. + * + * The message may or may not be intended for presentation to the end user. + * + * @param message the detail message. + * @param cause the underlying cause + */ + protected DocletException(String message, Throwable cause) { + super(message, cause); + if (message == null || message.isEmpty()) { + throw new IllegalArgumentException(); + } + } +} diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ModuleSummaryWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ModuleSummaryWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/ModuleSummaryWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,10 +25,7 @@ package jdk.javadoc.internal.doclets.toolkit; -import java.io.*; -import java.util.Set; - -import javax.lang.model.element.PackageElement; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; /** * The interface for writing module summary output. @@ -130,6 +127,7 @@ * Print the module summary document. * * @param contentTree the content tree that will be printed + * @throws DocFileIOException if there is a problem while writing the document */ - public abstract void printDocument(Content contentTree) throws IOException; + public abstract void printDocument(Content contentTree) throws DocFileIOException; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/PackageSummaryWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/PackageSummaryWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/PackageSummaryWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,13 +25,13 @@ package jdk.javadoc.internal.doclets.toolkit; -import java.io.*; - import java.util.List; import java.util.SortedSet; import javax.lang.model.element.TypeElement; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; + /** * The interface for writing package summary output. * @@ -118,7 +118,8 @@ * Print the package summary document. * * @param contentTree the content tree that will be printed + * @throws DocFileIOException if there is a problem while writing the document */ - public abstract void printDocument(Content contentTree) throws IOException; + public abstract void printDocument(Content contentTree) throws DocFileIOException; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/SerializedFormWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/SerializedFormWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/SerializedFormWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,13 +25,12 @@ package jdk.javadoc.internal.doclets.toolkit; -import java.io.*; - import javax.lang.model.element.ExecutableElement; import javax.lang.model.element.TypeElement; import javax.lang.model.element.VariableElement; import com.sun.source.doctree.DocTree; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; /** * The interface for writing serialized form output. @@ -124,15 +123,17 @@ public Content getClassContentHeader(); /** - * Return an instance of a SerialFieldWriter. + * Return an instance of a SerialFieldWriter for a class. * + * @param typeElement the class * @return an instance of a SerialFieldWriter. */ public SerialFieldWriter getSerialFieldWriter(TypeElement typeElement); /** - * Return an instance of a SerialMethodWriter. + * Return an instance of a SerialMethodWriter for a class. * + * @param typeElement the class * @return an instance of a SerialMethodWriter. */ public SerialMethodWriter getSerialMethodWriter(TypeElement typeElement); @@ -156,8 +157,9 @@ * Print the serialized form document. * * @param serializedTree the content tree that will be printed + * @throws DocFileIOException if there is a problem while writing the document */ - public abstract void printDocument(Content serializedTree) throws IOException; + public abstract void printDocument(Content serializedTree) throws DocFileIOException; /** * Write the serialized form for a given field. @@ -199,7 +201,7 @@ /** * Adds the description text for this member. * - * @param field the field to document. + * @param field the field to document * @param contentTree content tree to which the member description will be added */ public void addMemberDescription(VariableElement field, Content contentTree); @@ -207,7 +209,8 @@ /** * Adds the description text for this member represented by the tag. * - * @param serialFieldTag the field to document (represented by tag). + * @param field the field to document + * @param serialFieldTag the field to document (represented by tag) * @param contentTree content tree to which the member description will be added */ public void addMemberDescription(VariableElement field, DocTree serialFieldTag, Content contentTree); @@ -215,7 +218,7 @@ /** * Adds the tag information for this member. * - * @param field the field to document. + * @param field the field to document * @param contentTree content tree to which the member tags will be added */ public void addMemberTags(VariableElement field, Content contentTree); @@ -223,11 +226,11 @@ /** * Adds the member header. * - * @param fieldType the type of the field. + * @param fieldType the type of the field * @param fieldTypeStr the type of the field in string format. We will - * print this out if we can't link to the type. - * @param fieldDimensions the dimensions of the field. - * @param fieldName the name of the field. + * print this out if we can't link to the type + * @param fieldDimensions the dimensions of the field + * @param fieldName the name of the field * @param contentTree content tree to which the member header will be added */ public void addMemberHeader(TypeElement fieldType, String fieldTypeStr, @@ -239,7 +242,7 @@ * for deprecation info, inline comment or tags, * do not print overview details. * - * @param field the field to check overview details for. + * @param field the field to check overview details for * @return true if overview details need to be printed */ public boolean shouldPrintOverview(VariableElement field); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WriterFactory.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WriterFactory.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WriterFactory.java Mon Aug 22 16:32:40 2016 -0700 @@ -52,8 +52,7 @@ * @return the writer for the constant summary. Return null if this * writer is not supported by the doclet. */ - public abstract ConstantsSummaryWriter getConstantsSummaryWriter() - throws Exception; + public abstract ConstantsSummaryWriter getConstantsSummaryWriter(); /** * Return the writer for the package summary. @@ -65,8 +64,7 @@ * writer is not supported by the doclet. */ public abstract PackageSummaryWriter getPackageSummaryWriter(PackageElement - packageElement, PackageElement prevPkg, PackageElement nextPkg) - throws Exception; + packageElement, PackageElement prevPkg, PackageElement nextPkg); /** * Return the writer for the module summary. @@ -78,8 +76,7 @@ * writer is not supported by the doclet. */ public abstract ModuleSummaryWriter getModuleSummaryWriter( - ModuleElement mdle, ModuleElement prevModule, ModuleElement nextModule) - throws Exception; + ModuleElement mdle, ModuleElement prevModule, ModuleElement nextModule); /** * Return the writer for a class. @@ -92,8 +89,7 @@ * writer is not supported by the doclet. */ public abstract ClassWriter getClassWriter(TypeElement typeElement, - TypeElement prevClass, TypeElement nextClass, ClassTree classTree) - throws Exception; + TypeElement prevClass, TypeElement nextClass, ClassTree classTree); /** * Return the writer for an annotation type. @@ -105,8 +101,7 @@ * writer is not supported by the doclet. */ public abstract AnnotationTypeWriter getAnnotationTypeWriter( - TypeElement annotationType, TypeMirror prevType, TypeMirror nextType) - throws Exception; + TypeElement annotationType, TypeMirror prevType, TypeMirror nextType); /** * Return the method writer for a given class. @@ -115,8 +110,7 @@ * @return the method writer for the give class. Return null if this * writer is not supported by the doclet. */ - public abstract MethodWriter getMethodWriter(ClassWriter classWriter) - throws Exception; + public abstract MethodWriter getMethodWriter(ClassWriter classWriter); /** * Return the annotation type field writer for a given annotation type. @@ -128,7 +122,7 @@ */ public abstract AnnotationTypeFieldWriter getAnnotationTypeFieldWriter( - AnnotationTypeWriter annotationTypeWriter) throws Exception; + AnnotationTypeWriter annotationTypeWriter); /** * Return the annotation type optional member writer for a given annotation @@ -141,7 +135,7 @@ */ public abstract AnnotationTypeOptionalMemberWriter getAnnotationTypeOptionalMemberWriter( - AnnotationTypeWriter annotationTypeWriter) throws Exception; + AnnotationTypeWriter annotationTypeWriter); /** * Return the annotation type required member writer for a given annotation type. @@ -153,7 +147,7 @@ */ public abstract AnnotationTypeRequiredMemberWriter getAnnotationTypeRequiredMemberWriter( - AnnotationTypeWriter annotationTypeWriter) throws Exception; + AnnotationTypeWriter annotationTypeWriter); /** * Return the enum constant writer for a given class. @@ -163,7 +157,7 @@ * writer is not supported by the doclet. */ public abstract EnumConstantWriter getEnumConstantWriter( - ClassWriter classWriter) throws Exception; + ClassWriter classWriter); /** * Return the field writer for a given class. @@ -172,8 +166,7 @@ * @return the field writer for the give class. Return null if this * writer is not supported by the doclet. */ - public abstract FieldWriter getFieldWriter(ClassWriter classWriter) - throws Exception; + public abstract FieldWriter getFieldWriter(ClassWriter classWriter); /** * Return the property writer for a given class. @@ -182,8 +175,7 @@ * @return the property writer for the give class. Return null if this * writer is not supported by the doclet. */ - public abstract PropertyWriter getPropertyWriter(ClassWriter classWriter) - throws Exception; + public abstract PropertyWriter getPropertyWriter(ClassWriter classWriter); /** * Return the constructor writer for a given class. @@ -193,8 +185,7 @@ * writer is not supported by the doclet. */ public abstract ConstructorWriter getConstructorWriter( - ClassWriter classWriter) - throws Exception; + ClassWriter classWriter); /** * Return the specified member summary writer for a given class. @@ -206,11 +197,9 @@ * writer is not supported by the doclet. * * @see VisibleMemberMap - * @throws IllegalArgumentException if memberType is unknown. */ public abstract MemberSummaryWriter getMemberSummaryWriter( - ClassWriter classWriter, VisibleMemberMap.Kind memberType) - throws Exception; + ClassWriter classWriter, VisibleMemberMap.Kind memberType); /** * Return the specified member summary writer for a given annotation type. @@ -223,16 +212,14 @@ * writer is not supported by the doclet. * * @see VisibleMemberMap - * @throws IllegalArgumentException if memberType is unknown. */ public abstract MemberSummaryWriter getMemberSummaryWriter( - AnnotationTypeWriter annotationTypeWriter, VisibleMemberMap.Kind memberType) - throws Exception; + AnnotationTypeWriter annotationTypeWriter, VisibleMemberMap.Kind memberType); /** * Return the writer for the serialized form. * * @return the writer for the serialized form. */ - public SerializedFormWriter getSerializedFormWriter() throws Exception; + public SerializedFormWriter getSerializedFormWriter(); } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AbstractBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AbstractBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AbstractBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.toolkit.builders; -import java.io.*; import java.lang.reflect.*; import java.util.*; @@ -33,8 +32,11 @@ import jdk.javadoc.internal.doclets.toolkit.Configuration; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.Messages; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; +import jdk.javadoc.internal.doclets.toolkit.Resources; +import jdk.javadoc.internal.doclets.toolkit.util.InternalException; +import jdk.javadoc.internal.doclets.toolkit.util.SimpleDocletException; import jdk.javadoc.internal.doclets.toolkit.util.Utils; import static javax.tools.Diagnostic.Kind.*; @@ -91,6 +93,7 @@ protected final Configuration configuration; protected final Messages messages; + protected final Resources resources; protected final Utils utils; /** @@ -109,12 +112,12 @@ /** * Construct a Builder. - * @param configuration the configuration used in this run - * of the doclet. + * @param c a context providing information used in this run of the doclet */ public AbstractBuilder(Context c) { this.configuration = c.configuration; this.messages = configuration.getMessages(); + this.resources = configuration.getResources(); this.utils = configuration.utils; this.containingPackagesSeen = c.containingPackagesSeen; this.layoutParser = c.layoutParser; @@ -130,39 +133,55 @@ /** * Build the documentation. * - * @throws IOException there was a problem writing the output. + * @throws DocletException if there is a problem building the documentation */ - public abstract void build() throws IOException; + public abstract void build() throws DocletException; /** * Build the documentation, as specified by the given XML element. * * @param node the XML element that specifies which component to document. * @param contentTree content tree to which the documentation will be added + * @throws DocletException if there is a problem building the documentation */ - protected void build(XMLNode node, Content contentTree) { + protected void build(XMLNode node, Content contentTree) throws DocletException { String component = node.name; try { - invokeMethod("build" + component, - new Class[]{XMLNode.class, Content.class}, - new Object[]{node, contentTree}); + String methodName = "build" + component; + if (DEBUG) { + configuration.reporter.print(ERROR, + "DEBUG: " + getClass().getName() + "." + methodName); + } + Method method = getClass().getMethod(methodName, XMLNode.class, Content.class); + method.invoke(this, node, contentTree); + } catch (NoSuchMethodException e) { - e.printStackTrace(System.err); - configuration.reporter.print(ERROR, "Unknown element: " + component); - throw new DocletAbortException(e); + // Use SimpleDocletException instead of InternalException because there is nothing + // informative about about the place the exception occurred, here in this method. + // The problem is either a misconfigured doclet.xml file or a missing method in the + // user-supplied(?) doclet + String message = resources.getText("doclet.builder.unknown.component", component); + throw new SimpleDocletException(message, e); + } catch (InvocationTargetException e) { Throwable cause = e.getCause(); - if (cause instanceof DocletAbortException) { - throw (DocletAbortException) cause; + if (cause instanceof DocletException) { + throw (DocletException) cause; } else { - throw new DocletAbortException(e.getCause()); + // use InternalException, so that a stacktrace showing the position of + // the internal exception is generated + String message = resources.getText("doclet.builder.exception.in.component", component, + e.getCause()); + throw new InternalException(message, e.getCause()); } - } catch (Exception e) { - e.printStackTrace(System.err); - configuration.reporter.print(ERROR, "Exception " + - e.getClass().getName() + - " thrown while processing element: " + component); - throw new DocletAbortException(e); + + } catch (ReflectiveOperationException e) { + // Use SimpleDocletException instead of InternalException because there is nothing + // informative about about the place the exception occurred, here in this method. + // The problem is specific to the method being invoked, such as illegal access + // or illegal argument. + String message = resources.getText("doclet.builder.exception.in.component", component, e); + throw new SimpleDocletException(message, e.getCause()); } } @@ -171,29 +190,10 @@ * * @param node the XML element that specifies which components to document. * @param contentTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the children */ - protected void buildChildren(XMLNode node, Content contentTree) { + protected void buildChildren(XMLNode node, Content contentTree) throws DocletException { for (XMLNode child : node.children) build(child, contentTree); } - - /** - * Given the name and parameters, invoke the method in the builder. This - * method is required to invoke the appropriate build method as instructed - * by the builder XML file. - * - * @param methodName the name of the method that we would like to invoke. - * @param paramClasses the types for each parameter. - * @param params the parameters of the method. - */ - protected void invokeMethod(String methodName, Class[] paramClasses, - Object[] params) - throws Exception { - if (DEBUG) { - configuration.reporter.print(ERROR, "DEBUG: " + - this.getClass().getName() + "." + methodName); - } - Method method = this.getClass().getMethod(methodName, paramClasses); - method.invoke(this, params); - } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AbstractMemberBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AbstractMemberBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AbstractMemberBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -26,7 +26,7 @@ package jdk.javadoc.internal.doclets.toolkit.builders; import jdk.javadoc.internal.doclets.toolkit.Content; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; +import jdk.javadoc.internal.doclets.toolkit.DocletException; /** * The superclass for all member builders. Member builders are only executed @@ -44,7 +44,7 @@ /** * Construct a SubBuilder. - * @param configuration the configuration used in this run + * @param context a context object, providing information used in this run * of the doclet. */ public AbstractMemberBuilder(Context context) { @@ -54,32 +54,33 @@ /** * This method is not supported by sub-builders. * - * @throws DocletAbortException this method will always throw a - * DocletAbortException because it is not supported. + * @throws AssertionError always */ - public void build() throws DocletAbortException { - //You may not call the build method in a subbuilder. - throw new DocletAbortException("not supported"); + @Override + public void build() { + // You may not call the build method in a subbuilder. + throw new AssertionError(); } /** - * Build the sub component if there is anything to document. + * Builds the sub component if there is anything to document. * * @param node the XML element that specifies which components to document. * @param contentTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ @Override - public void build(XMLNode node, Content contentTree) { + public void build(XMLNode node, Content contentTree) throws DocletException { if (hasMembersToDocument()) { super.build(node, contentTree); } } /** - * Return true if this subbuilder has anything to document. + * Returns true if this subbuilder has anything to document. * - * @return true if this subbuilder has anything to document. + * @return true if this subbuilder has anything to document */ public abstract boolean hasMembersToDocument(); } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,13 +25,12 @@ package jdk.javadoc.internal.doclets.toolkit.builders; -import java.io.*; - import javax.lang.model.element.PackageElement; import javax.lang.model.element.TypeElement; import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeWriter; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; /** @@ -83,54 +82,59 @@ } /** - * Construct a new ClassBuilder. + * Construct a new AnnotationTypeBuilder. * * @param context the build context. * @param annotationTypeDoc the class being documented. * @param writer the doclet specific writer. + * @return an AnnotationTypeBuilder */ public static AnnotationTypeBuilder getInstance(Context context, TypeElement annotationTypeDoc, - AnnotationTypeWriter writer) - throws Exception { + AnnotationTypeWriter writer) { return new AnnotationTypeBuilder(context, annotationTypeDoc, writer); } /** * {@inheritDoc} */ - public void build() throws IOException { + @Override + public void build() throws DocletException { build(layoutParser.parseXML(ROOT), contentTree); } /** * {@inheritDoc} */ + @Override public String getName() { return ROOT; } /** - * Build the annotation type documentation. - * - * @param node the XML element that specifies which components to document - * @param contentTree the content tree to which the documentation will be added - */ - public void buildAnnotationTypeDoc(XMLNode node, Content contentTree) throws Exception { - contentTree = writer.getHeader(configuration.getText("doclet.AnnotationType") + - " " + utils.getSimpleName(annotationType)); - Content annotationContentTree = writer.getAnnotationContentHeader(); - buildChildren(node, annotationContentTree); - writer.addAnnotationContentTree(contentTree, annotationContentTree); - writer.addFooter(contentTree); - writer.printDocument(contentTree); - copyDocFiles(); - } + * Build the annotation type documentation. + * + * @param node the XML element that specifies which components to document + * @param contentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem building the documentation + */ + public void buildAnnotationTypeDoc(XMLNode node, Content contentTree) throws DocletException { + contentTree = writer.getHeader(configuration.getText("doclet.AnnotationType") + + " " + utils.getSimpleName(annotationType)); + Content annotationContentTree = writer.getAnnotationContentHeader(); + buildChildren(node, annotationContentTree); + writer.addAnnotationContentTree(contentTree, annotationContentTree); + writer.addFooter(contentTree); + writer.printDocument(contentTree); + copyDocFiles(); + } - /** - * Copy the doc files for the current TypeElement if necessary. - */ - private void copyDocFiles() { + /** + * Copy the doc files for the current TypeElement if necessary. + * + * @throws DocletException if there is a problem building the documentation + */ + private void copyDocFiles() throws DocletException { PackageElement containingPackage = utils.containingPackage(annotationType); if((configuration.packages == null || !configuration.packages.contains(containingPackage) && @@ -141,15 +145,17 @@ utils.copyDocFiles(containingPackage); containingPackagesSeen.add(containingPackage); } - } + } /** * Build the annotation information tree documentation. * * @param node the XML element that specifies which components to document * @param annotationContentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem building the documentation */ - public void buildAnnotationTypeInfo(XMLNode node, Content annotationContentTree) { + public void buildAnnotationTypeInfo(XMLNode node, Content annotationContentTree) + throws DocletException { Content annotationInfoTree = writer.getAnnotationInfoTreeHeader(); buildChildren(node, annotationInfoTree); annotationContentTree.addContent(writer.getAnnotationInfo(annotationInfoTree)); @@ -201,9 +207,9 @@ * * @param node the XML element that specifies which components to document * @param annotationContentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem building the documentation */ - public void buildMemberSummary(XMLNode node, Content annotationContentTree) - throws Exception { + public void buildMemberSummary(XMLNode node, Content annotationContentTree) throws DocletException { Content memberSummaryTree = writer.getMemberTreeHeader(); configuration.getBuilderFactory(). getMemberSummaryBuilder(writer).buildChildren(node, memberSummaryTree); @@ -215,8 +221,10 @@ * * @param node the XML element that specifies which components to document * @param annotationContentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem building the documentation */ - public void buildAnnotationTypeMemberDetails(XMLNode node, Content annotationContentTree) { + public void buildAnnotationTypeMemberDetails(XMLNode node, Content annotationContentTree) + throws DocletException { Content memberDetailsTree = writer.getMemberTreeHeader(); buildChildren(node, memberDetailsTree); if (memberDetailsTree.isValid()) { @@ -229,9 +237,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem building the documentation */ public void buildAnnotationTypeFieldDetails(XMLNode node, Content memberDetailsTree) - throws Exception { + throws DocletException { configuration.getBuilderFactory(). getAnnotationTypeFieldsBuilder(writer).buildChildren(node, memberDetailsTree); } @@ -241,9 +250,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem building the documentation */ public void buildAnnotationTypeOptionalMemberDetails(XMLNode node, Content memberDetailsTree) - throws Exception { + throws DocletException { configuration.getBuilderFactory(). getAnnotationTypeOptionalMemberBuilder(writer).buildChildren(node, memberDetailsTree); } @@ -253,9 +263,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem building the documentation */ public void buildAnnotationTypeRequiredMemberDetails(XMLNode node, Content memberDetailsTree) - throws Exception { + throws DocletException { configuration.getBuilderFactory(). getAnnotationTypeRequiredMemberBuilder(writer).buildChildren(node, memberDetailsTree); } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeFieldBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeFieldBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeFieldBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -33,6 +33,7 @@ import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeFieldWriter; import jdk.javadoc.internal.doclets.toolkit.Configuration; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; @@ -100,6 +101,7 @@ * @param context the build context. * @param typeElement the class whose members are being documented. * @param writer the doclet specific writer. + * @return the new AnnotationTypeFieldBuilder */ public static AnnotationTypeFieldBuilder getInstance( Context context, TypeElement typeElement, @@ -138,7 +140,8 @@ } /** - * summaryOrder.size() + * Returns whether or not there are members to document. + * @return whether or not there are members to document */ @Override public boolean hasMembersToDocument() { @@ -150,8 +153,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildAnnotationTypeField(XMLNode node, Content memberDetailsTree) { + public void buildAnnotationTypeField(XMLNode node, Content memberDetailsTree) + throws DocletException { buildAnnotationTypeMember(node, memberDetailsTree); } @@ -160,8 +165,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildAnnotationTypeMember(XMLNode node, Content memberDetailsTree) { + public void buildAnnotationTypeMember(XMLNode node, Content memberDetailsTree) + throws DocletException { if (writer == null) { return; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeOptionalMemberBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeOptionalMemberBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeOptionalMemberBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -30,6 +30,7 @@ import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeOptionalMemberWriter; import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeRequiredMemberWriter; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; @@ -67,6 +68,7 @@ * @param context the build context. * @param typeElement the class whose members are being documented. * @param writer the doclet specific writer. + * @return the new AnnotationTypeMemberBuilder */ public static AnnotationTypeOptionalMemberBuilder getInstance( Context context, TypeElement typeElement, @@ -88,8 +90,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildAnnotationTypeOptionalMember(XMLNode node, Content memberDetailsTree) { + public void buildAnnotationTypeOptionalMember(XMLNode node, Content memberDetailsTree) + throws DocletException { buildAnnotationTypeMember(node, memberDetailsTree); } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeRequiredMemberBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeRequiredMemberBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/AnnotationTypeRequiredMemberBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -33,6 +33,7 @@ import jdk.javadoc.internal.doclets.toolkit.AnnotationTypeRequiredMemberWriter; import jdk.javadoc.internal.doclets.toolkit.Configuration; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; @@ -139,7 +140,8 @@ } /** - * summaryOrder.size() + * Returns whether or not there are members to document. + * @return whether or not there are members to document */ @Override public boolean hasMembersToDocument() { @@ -151,8 +153,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildAnnotationTypeRequiredMember(XMLNode node, Content memberDetailsTree) { + public void buildAnnotationTypeRequiredMember(XMLNode node, Content memberDetailsTree) + throws DocletException { buildAnnotationTypeMember(node, memberDetailsTree); } @@ -162,7 +166,8 @@ * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added */ - public void buildAnnotationTypeMember(XMLNode node, Content memberDetailsTree) { + public void buildAnnotationTypeMember(XMLNode node, Content memberDetailsTree) + throws DocletException { if (writer == null) { return; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/BuilderFactory.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/BuilderFactory.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/BuilderFactory.java Mon Aug 22 16:32:40 2016 -0700 @@ -83,7 +83,7 @@ * Return the builder that builds the constant summary. * @return the builder that builds the constant summary. */ - public AbstractBuilder getConstantsSummaryBuilder() throws Exception { + public AbstractBuilder getConstantsSummaryBuilder() { return ConstantsSummaryBuilder.getInstance(context, writerFactory.getConstantsSummaryWriter()); } @@ -97,7 +97,7 @@ * @return the builder that builds the constant summary. */ public AbstractBuilder getPackageSummaryBuilder(PackageElement pkg, PackageElement prevPkg, - PackageElement nextPkg) throws Exception { + PackageElement nextPkg) { return PackageSummaryBuilder.getInstance(context, pkg, writerFactory.getPackageSummaryWriter(pkg, prevPkg, nextPkg)); } @@ -111,7 +111,7 @@ * @return the builder that builds the module summary. */ public AbstractBuilder getModuleSummaryBuilder(ModuleElement mdle, ModuleElement prevModule, - ModuleElement nextModule) throws Exception { + ModuleElement nextModule) { return ModuleSummaryBuilder.getInstance(context, mdle, writerFactory.getModuleSummaryWriter(mdle, prevModule, nextModule)); } @@ -127,8 +127,7 @@ * writer is not supported by the doclet. */ public AbstractBuilder getClassBuilder(TypeElement typeElement, - TypeElement prevClass, TypeElement nextClass, ClassTree classTree) - throws Exception { + TypeElement prevClass, TypeElement nextClass, ClassTree classTree) { return ClassBuilder.getInstance(context, typeElement, writerFactory.getClassWriter(typeElement, prevClass, nextClass, classTree)); } @@ -143,8 +142,7 @@ * writer is not supported by the doclet. */ public AbstractBuilder getAnnotationTypeBuilder( - TypeElement annotationType, TypeMirror prevType, TypeMirror nextType) - throws Exception { + TypeElement annotationType, TypeMirror prevType, TypeMirror nextType) { return AnnotationTypeBuilder.getInstance(context, annotationType, writerFactory.getAnnotationTypeWriter(annotationType, prevType, nextType)); } @@ -154,8 +152,7 @@ * * @return an instance of the method builder for the given class. */ - public AbstractBuilder getMethodBuilder(ClassWriter classWriter) - throws Exception { + public AbstractBuilder getMethodBuilder(ClassWriter classWriter) { return MethodBuilder.getInstance(context, classWriter.getTypeElement(), writerFactory.getMethodWriter(classWriter)); } @@ -168,8 +165,7 @@ * annotation type. */ public AbstractBuilder getAnnotationTypeFieldsBuilder( - AnnotationTypeWriter annotationTypeWriter) - throws Exception { + AnnotationTypeWriter annotationTypeWriter) { return AnnotationTypeFieldBuilder.getInstance(context, annotationTypeWriter.getAnnotationTypeElement(), writerFactory.getAnnotationTypeFieldWriter(annotationTypeWriter)); @@ -183,8 +179,7 @@ * annotation type. */ public AbstractBuilder getAnnotationTypeOptionalMemberBuilder( - AnnotationTypeWriter annotationTypeWriter) - throws Exception { + AnnotationTypeWriter annotationTypeWriter) { return AnnotationTypeOptionalMemberBuilder.getInstance(context, annotationTypeWriter.getAnnotationTypeElement(), writerFactory.getAnnotationTypeOptionalMemberWriter(annotationTypeWriter)); @@ -198,8 +193,7 @@ * annotation type. */ public AbstractBuilder getAnnotationTypeRequiredMemberBuilder( - AnnotationTypeWriter annotationTypeWriter) - throws Exception { + AnnotationTypeWriter annotationTypeWriter) { return AnnotationTypeRequiredMemberBuilder.getInstance(context, annotationTypeWriter.getAnnotationTypeElement(), writerFactory.getAnnotationTypeRequiredMemberWriter(annotationTypeWriter)); @@ -210,8 +204,7 @@ * * @return an instance of the enum constants builder for the given class. */ - public AbstractBuilder getEnumConstantsBuilder(ClassWriter classWriter) - throws Exception { + public AbstractBuilder getEnumConstantsBuilder(ClassWriter classWriter) { return EnumConstantBuilder.getInstance(context, classWriter.getTypeElement(), writerFactory.getEnumConstantWriter(classWriter)); } @@ -221,7 +214,7 @@ * * @return an instance of the field builder for the given class. */ - public AbstractBuilder getFieldBuilder(ClassWriter classWriter) throws Exception { + public AbstractBuilder getFieldBuilder(ClassWriter classWriter) { return FieldBuilder.getInstance(context, classWriter.getTypeElement(), writerFactory.getFieldWriter(classWriter)); } @@ -231,7 +224,7 @@ * * @return an instance of the field builder for the given class. */ - public AbstractBuilder getPropertyBuilder(ClassWriter classWriter) throws Exception { + public AbstractBuilder getPropertyBuilder(ClassWriter classWriter) { final PropertyWriter propertyWriter = writerFactory.getPropertyWriter(classWriter); return PropertyBuilder.getInstance(context, @@ -244,8 +237,7 @@ * * @return an instance of the constructor builder for the given class. */ - public AbstractBuilder getConstructorBuilder(ClassWriter classWriter) - throws Exception { + public AbstractBuilder getConstructorBuilder(ClassWriter classWriter) { return ConstructorBuilder.getInstance(context, classWriter.getTypeElement(), writerFactory.getConstructorWriter(classWriter)); } @@ -255,8 +247,7 @@ * * @return an instance of the member summary builder for the given class. */ - public AbstractBuilder getMemberSummaryBuilder(ClassWriter classWriter) - throws Exception { + public AbstractBuilder getMemberSummaryBuilder(ClassWriter classWriter) { return MemberSummaryBuilder.getInstance(classWriter, context); } @@ -267,9 +258,7 @@ * @return an instance of the member summary builder for the given * annotation type. */ - public AbstractBuilder getMemberSummaryBuilder( - AnnotationTypeWriter annotationTypeWriter) - throws Exception { + public AbstractBuilder getMemberSummaryBuilder(AnnotationTypeWriter annotationTypeWriter) { return MemberSummaryBuilder.getInstance(annotationTypeWriter, context); } @@ -278,8 +267,7 @@ * * @return the builder that builds the serialized form. */ - public AbstractBuilder getSerializedFormBuilder() - throws Exception { + public AbstractBuilder getSerializedFormBuilder() { return SerializedFormBuilder.getInstance(context); } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ClassBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ClassBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ClassBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,13 +25,13 @@ package jdk.javadoc.internal.doclets.toolkit.builders; -import java.io.*; - import javax.lang.model.element.PackageElement; import javax.lang.model.element.TypeElement; import jdk.javadoc.internal.doclets.toolkit.ClassWriter; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; import jdk.javadoc.internal.doclets.toolkit.util.Utils; /** @@ -105,11 +105,12 @@ } /** - * Construct a new ClassBuilder. + * Constructs a new ClassBuilder. * * @param context the build context * @param typeElement the class being documented. * @param writer the doclet specific writer. + * @return the new ClassBuilder */ public static ClassBuilder getInstance(Context context, TypeElement typeElement, ClassWriter writer) { @@ -119,13 +120,15 @@ /** * {@inheritDoc} */ - public void build() throws IOException { + @Override + public void build() throws DocletException { build(layoutParser.parseXML(ROOT), contentTree); } /** * {@inheritDoc} */ + @Override public String getName() { return ROOT; } @@ -135,8 +138,9 @@ * * @param node the XML element that specifies which components to document * @param contentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildClassDoc(XMLNode node, Content contentTree) throws Exception { + public void buildClassDoc(XMLNode node, Content contentTree) throws DocletException { String key; if (isInterface) { key = "doclet.Interface"; @@ -170,15 +174,16 @@ * * @param node the XML element that specifies which components to document * @param classContentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildClassInfo(XMLNode node, Content classContentTree) { + public void buildClassInfo(XMLNode node, Content classContentTree) throws DocletException { Content classInfoTree = writer.getClassInfoTreeHeader(); buildChildren(node, classInfoTree); classContentTree.addContent(writer.getClassInfo(classInfoTree)); } /** - * Build the typeparameters of this class. + * Build the type parameters of this class. * * @param node the XML element that specifies which components to document * @param classInfoTree the content tree to which the documentation will be added @@ -269,8 +274,10 @@ /** * Copy the doc files. + * + * @throws DocFileIOException if there is a problem while copying the files */ - private void copyDocFiles() { + private void copyDocFiles() throws DocFileIOException { PackageElement containingPackage = utils.containingPackage(typeElement); if((configuration.packages == null || !configuration.packages.contains(containingPackage)) && @@ -318,8 +325,9 @@ * * @param node the XML element that specifies which components to document * @param classContentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildMemberSummary(XMLNode node, Content classContentTree) throws Exception { + public void buildMemberSummary(XMLNode node, Content classContentTree) throws DocletException { Content memberSummaryTree = writer.getMemberTreeHeader(); configuration.getBuilderFactory(). getMemberSummaryBuilder(writer).buildChildren(node, memberSummaryTree); @@ -331,8 +339,9 @@ * * @param node the XML element that specifies which components to document * @param classContentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildMemberDetails(XMLNode node, Content classContentTree) { + public void buildMemberDetails(XMLNode node, Content classContentTree) throws DocletException { Content memberDetailsTree = writer.getMemberTreeHeader(); buildChildren(node, memberDetailsTree); classContentTree.addContent(writer.getMemberDetailsTree(memberDetailsTree)); @@ -343,9 +352,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ public void buildEnumConstantsDetails(XMLNode node, - Content memberDetailsTree) throws Exception { + Content memberDetailsTree) throws DocletException { configuration.getBuilderFactory(). getEnumConstantsBuilder(writer).buildChildren(node, memberDetailsTree); } @@ -355,9 +365,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ public void buildFieldDetails(XMLNode node, - Content memberDetailsTree) throws Exception { + Content memberDetailsTree) throws DocletException { configuration.getBuilderFactory(). getFieldBuilder(writer).buildChildren(node, memberDetailsTree); } @@ -365,10 +376,12 @@ /** * Build the property documentation. * - * @param elements the XML elements that specify how a field is documented. + * @param node the XML element that specifies which components to document + * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ public void buildPropertyDetails(XMLNode node, - Content memberDetailsTree) throws Exception { + Content memberDetailsTree) throws DocletException { configuration.getBuilderFactory(). getPropertyBuilder(writer).buildChildren(node, memberDetailsTree); } @@ -378,9 +391,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ public void buildConstructorDetails(XMLNode node, - Content memberDetailsTree) throws Exception { + Content memberDetailsTree) throws DocletException { configuration.getBuilderFactory(). getConstructorBuilder(writer).buildChildren(node, memberDetailsTree); } @@ -390,9 +404,10 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ public void buildMethodDetails(XMLNode node, - Content memberDetailsTree) throws Exception { + Content memberDetailsTree) throws DocletException { configuration.getBuilderFactory(). getMethodBuilder(writer).buildChildren(node, memberDetailsTree); } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ConstantsSummaryBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ConstantsSummaryBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ConstantsSummaryBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.toolkit.builders; -import java.io.*; import java.util.*; import javax.lang.model.element.Element; @@ -35,6 +34,7 @@ import jdk.javadoc.internal.doclets.toolkit.ConstantsSummaryWriter; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; @@ -116,6 +116,7 @@ * * @param context the build context. * @param writer the writer for the summary. + * @return the new ConstantsSummaryBuilder */ public static ConstantsSummaryBuilder getInstance(Context context, ConstantsSummaryWriter writer) { @@ -124,9 +125,10 @@ /** * {@inheritDoc} + * @throws DocletException if there is a problem while building the documentation */ @Override - public void build() throws IOException { + public void build() throws DocletException { if (writer == null) { //Doclet does not support this output. return; @@ -147,8 +149,9 @@ * * @param node the XML element that specifies which components to document * @param contentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildConstantSummary(XMLNode node, Content contentTree) throws Exception { + public void buildConstantSummary(XMLNode node, Content contentTree) throws DocletException { contentTree = writer.getHeader(); buildChildren(node, contentTree); writer.addFooter(contentTree); @@ -177,8 +180,9 @@ * * @param node the XML element that specifies which components to document * @param contentTree the tree to which the summaries will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildConstantSummaries(XMLNode node, Content contentTree) { + public void buildConstantSummaries(XMLNode node, Content contentTree) throws DocletException { printedPackageHeaders.clear(); Content summariesTree = writer.getConstantSummaries(); for (PackageElement aPackage : configuration.packages) { @@ -211,8 +215,11 @@ * * @param node the XML element that specifies which components to document * @param summariesTree the tree to which the class constant summary will be added + * @throws DocletException if there is a problem while building the documentation + * */ - public void buildClassConstantSummary(XMLNode node, Content summariesTree) { + public void buildClassConstantSummary(XMLNode node, Content summariesTree) + throws DocletException { SortedSet classes = !currentPackage.isUnnamed() ? utils.getAllClasses(currentPackage) : configuration.typeElementCatalog.allUnnamedClasses(); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ConstructorBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ConstructorBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ConstructorBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -34,6 +34,7 @@ import jdk.javadoc.internal.doclets.toolkit.Configuration; import jdk.javadoc.internal.doclets.toolkit.ConstructorWriter; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; @@ -112,6 +113,7 @@ * @param context the build context. * @param typeElement the class whoses members are being documented. * @param writer the doclet specific writer. + * @return the new ConstructorBuilder */ public static ConstructorBuilder getInstance(Context context, TypeElement typeElement, ConstructorWriter writer) { @@ -139,6 +141,7 @@ * This information can be used for doclet specific documentation * generation. * + * @param typeElement the class * @return a list of constructors that will be documented. */ public SortedSet members(TypeElement typeElement) { @@ -159,8 +162,9 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException is there is a problem while building the documentation */ - public void buildConstructorDoc(XMLNode node, Content memberDetailsTree) { + public void buildConstructorDoc(XMLNode node, Content memberDetailsTree) throws DocletException { if (writer == null) { return; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/EnumConstantBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/EnumConstantBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/EnumConstantBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -33,6 +33,7 @@ import jdk.javadoc.internal.doclets.toolkit.Configuration; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.EnumConstantWriter; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; @@ -102,6 +103,7 @@ * @param context the build context. * @param typeElement the class whoses members are being documented. * @param writer the doclet specific writer. + * @return the new EnumConstantsBuilder */ public static EnumConstantBuilder getInstance(Context context, TypeElement typeElement, EnumConstantWriter writer) { @@ -138,7 +140,9 @@ } /** - * summaryOrder.size() + * Returns whether or not there are members to document. + * + * @return whether or not there are members to document */ @Override public boolean hasMembersToDocument() { @@ -150,8 +154,9 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException is there is a problem while building the documentation */ - public void buildEnumConstant(XMLNode node, Content memberDetailsTree) { + public void buildEnumConstant(XMLNode node, Content memberDetailsTree) throws DocletException { if (writer == null) { return; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/FieldBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/FieldBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/FieldBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -33,6 +33,7 @@ import jdk.javadoc.internal.doclets.toolkit.Configuration; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.FieldWriter; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; @@ -103,6 +104,7 @@ * @param context the build context. * @param typeElement the class whoses members are being documented. * @param writer the doclet specific writer. + * @return the new FieldBuilder */ public static FieldBuilder getInstance(Context context, TypeElement typeElement, @@ -140,7 +142,9 @@ } /** - * summaryOrder.size() + * Returns whether or not there are members to document. + * + * @return whether or not there are members to document */ @Override public boolean hasMembersToDocument() { @@ -152,8 +156,9 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildFieldDoc(XMLNode node, Content memberDetailsTree) { + public void buildFieldDoc(XMLNode node, Content memberDetailsTree) throws DocletException { if (writer == null) { return; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/LayoutParser.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/LayoutParser.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/LayoutParser.java Mon Aug 22 16:32:40 2016 -0700 @@ -31,7 +31,8 @@ import javax.xml.parsers.*; import jdk.javadoc.internal.doclets.toolkit.Configuration; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; +import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException; +import jdk.javadoc.internal.doclets.toolkit.util.SimpleDocletException; import org.xml.sax.*; import org.xml.sax.helpers.DefaultHandler; @@ -53,7 +54,7 @@ /** * The map of XML elements that have been parsed. */ - private Map xmlElementsMap; + private final Map xmlElementsMap; private XMLNode currentNode; private final Configuration configuration; private String currentRoot; @@ -77,33 +78,38 @@ /** * Parse the XML specifying the layout of the documentation. * + * @param root the name of the desired node * @return the list of XML elements parsed. + * @throws DocFileIOException if there is a problem reading a user-supplied build file + * @throws SimpleDocletException if there is a problem reading the system build file */ - public XMLNode parseXML(String root) { - if (xmlElementsMap.containsKey(root)) { - return xmlElementsMap.get(root); + public XMLNode parseXML(String root) throws DocFileIOException, SimpleDocletException { + if (!xmlElementsMap.containsKey(root)) { + try { + currentRoot = root; + isParsing = false; + SAXParserFactory factory = SAXParserFactory.newInstance(); + SAXParser saxParser = factory.newSAXParser(); + InputStream in = configuration.getBuilderXML(); + saxParser.parse(in, this); + } catch (IOException | ParserConfigurationException | SAXException e) { + String message = (configuration.builderXMLPath == null) + ? configuration.getResources().getText("doclet.exception.read.resource", + Configuration.DEFAULT_BUILDER_XML, e) + : configuration.getResources().getText("doclet.exception.read.file", + configuration.builderXMLPath, e); + throw new SimpleDocletException(message, e); + } } - try { - currentRoot = root; - isParsing = false; - SAXParserFactory factory = SAXParserFactory.newInstance(); - SAXParser saxParser = factory.newSAXParser(); - InputStream in = configuration.getBuilderXML(); - saxParser.parse(in, this); - return xmlElementsMap.get(root); - } catch (Throwable t) { - t.printStackTrace(); - throw new DocletAbortException(t); - } + return xmlElementsMap.get(root); } /** * {@inheritDoc} */ @Override - public void startElement(String namespaceURI, String sName, String qName, - Attributes attrs) - throws SAXException { + public void startElement(String namespaceURI, String sName, String qName, Attributes attrs) + throws SAXException { if (isParsing || qName.equals(currentRoot)) { isParsing = true; currentNode = new XMLNode(currentNode, qName); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MemberSummaryBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MemberSummaryBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MemberSummaryBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -42,7 +42,6 @@ import jdk.javadoc.internal.doclets.toolkit.WriterFactory; import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; import jdk.javadoc.internal.doclets.toolkit.util.DocFinder; -import jdk.javadoc.internal.doclets.toolkit.util.Utils; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; import jdk.javadoc.internal.doclets.toolkit.CommentUtils; @@ -107,8 +106,7 @@ * @param context the build context. */ public static MemberSummaryBuilder getInstance( - ClassWriter classWriter, Context context) - throws Exception { + ClassWriter classWriter, Context context) { MemberSummaryBuilder builder = new MemberSummaryBuilder(context, classWriter.getTypeElement()); WriterFactory wf = context.configuration.getWriterFactory(); @@ -129,8 +127,7 @@ * @param configuration the current configuration of the doclet. */ public static MemberSummaryBuilder getInstance( - AnnotationTypeWriter annotationTypeWriter, Context context) - throws Exception { + AnnotationTypeWriter annotationTypeWriter, Context context) { MemberSummaryBuilder builder = new MemberSummaryBuilder(context, annotationTypeWriter.getAnnotationTypeElement()); WriterFactory wf = context.configuration.getWriterFactory(); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MethodBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MethodBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MethodBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -35,6 +35,7 @@ import jdk.javadoc.internal.doclets.formats.html.ConfigurationImpl; import jdk.javadoc.internal.doclets.toolkit.Configuration; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.MethodWriter; import jdk.javadoc.internal.doclets.toolkit.util.DocFinder; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; @@ -156,8 +157,9 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildMethodDoc(XMLNode node, Content memberDetailsTree) { + public void buildMethodDoc(XMLNode node, Content memberDetailsTree) throws DocletException { if (writer == null) { return; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ModuleSummaryBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ModuleSummaryBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/ModuleSummaryBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,14 +25,12 @@ package jdk.javadoc.internal.doclets.toolkit.builders; -import java.io.IOException; -import java.util.Set; - import javax.lang.model.element.ModuleElement; import javax.lang.model.element.PackageElement; import javax.tools.StandardLocation; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.ModuleSummaryWriter; import jdk.javadoc.internal.doclets.toolkit.util.DocPaths; @@ -105,8 +103,11 @@ /** * Build the module summary. + * + * @throws DocletException if there is a problem while building the documentation */ - public void build() throws IOException { + @Override + public void build() throws DocletException { if (moduleWriter == null) { //Doclet does not support this output. return; @@ -117,6 +118,7 @@ /** * {@inheritDoc} */ + @Override public String getName() { return ROOT; } @@ -126,8 +128,9 @@ * * @param node the XML element that specifies which components to document * @param contentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildModuleDoc(XMLNode node, Content contentTree) throws Exception { + public void buildModuleDoc(XMLNode node, Content contentTree) throws DocletException { contentTree = moduleWriter.getModuleHeader(mdle.getSimpleName().toString()); buildChildren(node, contentTree); moduleWriter.addModuleFooter(contentTree); @@ -145,8 +148,9 @@ * @param node the XML element that specifies which components to document * @param contentTree the content tree to which the module contents * will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildContent(XMLNode node, Content contentTree) { + public void buildContent(XMLNode node, Content contentTree) throws DocletException { Content moduleContentTree = moduleWriter.getContentHeader(); buildChildren(node, moduleContentTree); moduleWriter.addModuleContent(contentTree, moduleContentTree); @@ -158,8 +162,9 @@ * @param node the XML element that specifies which components to document * @param moduleContentTree the module content tree to which the summaries will * be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildSummary(XMLNode node, Content moduleContentTree) { + public void buildSummary(XMLNode node, Content moduleContentTree) throws DocletException { Content summaryContentTree = moduleWriter.getSummaryHeader(); buildChildren(node, summaryContentTree); moduleContentTree.addContent(moduleWriter.getSummaryTree(summaryContentTree)); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/PackageSummaryBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/PackageSummaryBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/PackageSummaryBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,8 +25,6 @@ package jdk.javadoc.internal.doclets.toolkit.builders; -import java.io.*; - import java.util.Arrays; import java.util.List; import java.util.Set; @@ -36,6 +34,7 @@ import javax.lang.model.element.TypeElement; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.PackageSummaryWriter; @@ -104,8 +103,11 @@ /** * Build the package summary. + * + * @throws DocletException if there is a problem while building the documentation */ - public void build() throws IOException { + @Override + public void build() throws DocletException { if (packageWriter == null) { //Doclet does not support this output. return; @@ -116,6 +118,7 @@ /** * {@inheritDoc} */ + @Override public String getName() { return ROOT; } @@ -125,8 +128,9 @@ * * @param node the XML element that specifies which components to document * @param contentTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildPackageDoc(XMLNode node, Content contentTree) throws Exception { + public void buildPackageDoc(XMLNode node, Content contentTree) throws DocletException { contentTree = packageWriter.getPackageHeader(utils.getPackageName(packageElement)); buildChildren(node, contentTree); packageWriter.addPackageFooter(contentTree); @@ -140,8 +144,9 @@ * @param node the XML element that specifies which components to document * @param contentTree the content tree to which the package contents * will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildContent(XMLNode node, Content contentTree) { + public void buildContent(XMLNode node, Content contentTree) throws DocletException { Content packageContentTree = packageWriter.getContentHeader(); buildChildren(node, packageContentTree); packageWriter.addPackageContent(contentTree, packageContentTree); @@ -153,8 +158,9 @@ * @param node the XML element that specifies which components to document * @param packageContentTree the package content tree to which the summaries will * be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildSummary(XMLNode node, Content packageContentTree) { + public void buildSummary(XMLNode node, Content packageContentTree) throws DocletException { Content summaryContentTree = packageWriter.getSummaryHeader(); buildChildren(node, summaryContentTree); packageContentTree.addContent(summaryContentTree); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/PropertyBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/PropertyBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/PropertyBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -33,6 +33,7 @@ import jdk.javadoc.internal.doclets.toolkit.Configuration; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.PropertyWriter; import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberMap; @@ -103,6 +104,7 @@ * @param context the build context. * @param typeElement the class whoses members are being documented. * @param writer the doclet specific writer. + * @return the new PropertyBuilder */ public static PropertyBuilder getInstance(Context context, TypeElement typeElement, @@ -140,7 +142,9 @@ } /** - * summaryOrder.size() + * Returns whether or not there are members to document. + * + * @return whether or not there are members to document */ @Override public boolean hasMembersToDocument() { @@ -152,8 +156,9 @@ * * @param node the XML element that specifies which components to document * @param memberDetailsTree the content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildPropertyDoc(XMLNode node, Content memberDetailsTree) { + public void buildPropertyDoc(XMLNode node, Content memberDetailsTree) throws DocletException { if (writer == null) { return; } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.toolkit.builders; -import java.io.*; import java.util.*; import javax.lang.model.element.Element; @@ -37,9 +36,9 @@ import com.sun.source.doctree.DocTree; import com.sun.source.doctree.SerialFieldTree; import jdk.javadoc.internal.doclets.toolkit.Content; +import jdk.javadoc.internal.doclets.toolkit.DocletException; import jdk.javadoc.internal.doclets.toolkit.SerializedFormWriter; import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper; -import jdk.javadoc.internal.doclets.toolkit.util.DocletAbortException; import jdk.javadoc.internal.doclets.toolkit.util.Utils; /** @@ -114,7 +113,9 @@ /** * Construct a new SerializedFormBuilder. + * * @param context the build context. + * @return the new SerializedFormBuilder */ public static SerializedFormBuilder getInstance(Context context) { return new SerializedFormBuilder(context); @@ -122,22 +123,21 @@ /** * Build the serialized form. + * + * @throws DocletException if there is a problem while building the documentation */ - public void build() throws IOException { + @Override + public void build() throws DocletException { SortedSet rootclasses = new TreeSet<>(utils.makeGeneralPurposeComparator()); rootclasses.addAll(configuration.docEnv.getIncludedTypeElements()); if (!serialClassFoundToDocument(rootclasses)) { //Nothing to document. return; } - try { - writer = configuration.getWriterFactory().getSerializedFormWriter(); - if (writer == null) { - //Doclet does not support this output. - return; - } - } catch (Exception e) { - throw new DocletAbortException(e); + writer = configuration.getWriterFactory().getSerializedFormWriter(); + if (writer == null) { + //Doclet does not support this output. + return; } build(layoutParser.parseXML(NAME), contentTree); } @@ -145,6 +145,7 @@ /** * {@inheritDoc} */ + @Override public String getName() { return NAME; } @@ -154,8 +155,9 @@ * * @param node the XML element that specifies which components to document * @param serializedTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildSerializedForm(XMLNode node, Content serializedTree) throws Exception { + public void buildSerializedForm(XMLNode node, Content serializedTree) throws DocletException { serializedTree = writer.getHeader(configuration.getText( "doclet.Serialized_Form")); buildChildren(node, serializedTree); @@ -168,8 +170,10 @@ * * @param node the XML element that specifies which components to document * @param serializedTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildSerializedFormSummaries(XMLNode node, Content serializedTree) { + public void buildSerializedFormSummaries(XMLNode node, Content serializedTree) + throws DocletException { Content serializedSummariesTree = writer.getSerializedSummariesHeader(); for (PackageElement pkg : configuration.packages) { currentPackage = pkg; @@ -184,8 +188,9 @@ * * @param node the XML element that specifies which components to document * @param serializedSummariesTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildPackageSerializedForm(XMLNode node, Content serializedSummariesTree) { + public void buildPackageSerializedForm(XMLNode node, Content serializedSummariesTree) throws DocletException { Content packageSerializedTree = writer.getPackageSerializedHeader(); SortedSet classes = utils.getAllClassesUnfiltered(currentPackage); if (classes.isEmpty()) { @@ -217,8 +222,10 @@ * * @param node the XML element that specifies which components to document * @param packageSerializedTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildClassSerializedForm(XMLNode node, Content packageSerializedTree) { + public void buildClassSerializedForm(XMLNode node, Content packageSerializedTree) + throws DocletException { Content classSerializedTree = writer.getClassSerializedHeader(); SortedSet typeElements = utils.getAllClassesUnfiltered(currentPackage); for (TypeElement typeElement : typeElements) { @@ -262,8 +269,9 @@ * * @param node the XML element that specifies which components to document * @param classTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildClassContent(XMLNode node, Content classTree) { + public void buildClassContent(XMLNode node, Content classTree) throws DocletException { Content classContentTree = writer.getClassContentHeader(); buildChildren(node, classContentTree); classTree.addContent(classContentTree); @@ -275,8 +283,9 @@ * * @param node the XML element that specifies which components to document * @param classContentTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildSerializableMethods(XMLNode node, Content classContentTree) { + public void buildSerializableMethods(XMLNode node, Content classContentTree) throws DocletException { Content serializableMethodTree = methodWriter.getSerializableMethodsHeader(); SortedSet members = utils.serializationMethods(currentTypeElement); if (!members.isEmpty()) { @@ -329,8 +338,9 @@ * * @param node the XML element that specifies which components to document * @param methodsContentTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildMethodInfo(XMLNode node, Content methodsContentTree) { + public void buildMethodInfo(XMLNode node, Content methodsContentTree) throws DocletException { if(configuration.nocomment){ return; } @@ -411,8 +421,10 @@ * * @param node the XML element that specifies which components to document * @param classContentTree content tree to which the documentation will be added + * @throws DocletException if there is a problem while building the documentation */ - public void buildSerializableFields(XMLNode node, Content classContentTree) { + public void buildSerializableFields(XMLNode node, Content classContentTree) + throws DocletException { SortedSet members = utils.serializableFields(currentTypeElement); if (!members.isEmpty()) { Content serializableFieldsTree = fieldWriter.getSerializableFieldsHeader(); @@ -533,10 +545,12 @@ } /** - * Return true if the given Element should be included + * Returns true if the given Element should be included * in the serialized form. * - * @param element the Element object to check for serializability. + * @param utils the utils object + * @param element the Element object to check for serializability + * @return true if the element should be included in the serial form */ public static boolean serialInclude(Utils utils, Element element) { if (element == null) { @@ -548,7 +562,7 @@ } /** - * Return true if the given TypeElement should be included + * Returns true if the given TypeElement should be included * in the serialized form. * * @param te the TypeElement object to check for serializability. diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties Mon Aug 22 16:32:40 2016 -0700 @@ -14,17 +14,29 @@ doclet.Option_doclint_no_qualifiers=Access qualifiers not permitted for -Xdoclint arguments doclet.Option_doclint_invalid_arg=Invalid argument for -Xdoclint option doclet.Option_doclint_package_invalid_arg=Invalid argument for -Xdoclint/package option -doclet.exception_encountered= {0} encountered \n\ -\twhile attempting to create file: {1} -doclet.perform_copy_exception_encountered= {0} encountered while \n\ -performing copy. +doclet.builder.exception.in.component=An exception occurred while building a component: {0}\n\ +\t({1}) +doclet.builder.unknown.component=Unknown component referenced in doclet build file: {0} +doclet.error.initializing.dest.dir=Error initializing destination directory: {0} +doclet.exception.read.file=Error reading file: {0}\n\ +\t({1}) +doclet.exception.write.file=Error writing file: {0}\n\ +\t({1}) +doclet.exception.read.resource=Error reading system resource: {0}\n\ +\t({1}) +doclet.internal.exception=An internal exception has occurred. \n\ +\t({0}) +doclet.internal.report.bug=\ +Please file a bug against the javadoc tool via the Java bug reporting page\n\ +(http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com)\n\ +for duplicates. Include error messages and the following diagnostic in your report. Thank you. doclet.File_not_found=File not found: {0} doclet.Copy_Overwrite_warning=File {0} not copied to {1} due to existing file with same name... doclet.Copying_File_0_To_Dir_1=Copying file {0} to directory {1}... doclet.Copying_File_0_To_File_1=Copying file {0} to file {1}... doclet.No_Public_Classes_To_Document=No public or protected classes found to document. -doclet.destination_directory_not_directory_0=Destination directory is not a directory {0} -doclet.destination_directory_not_writable_0=Destination directory not writable {0} +doclet.destination_directory_not_directory_0=Destination directory is not a directory: {0} +doclet.destination_directory_not_writable_0=Destination directory not writable: {0} doclet.Encoding_not_supported=Encoding not supported: {0} doclet.Building_Tree=Building tree for all the packages and classes... doclet.Building_Index=Building index for all the packages and classes... diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFile.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFile.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFile.java Mon Aug 22 16:32:40 2016 -0700 @@ -26,13 +26,10 @@ package jdk.javadoc.internal.doclets.toolkit.util; import java.io.BufferedReader; -import java.io.BufferedWriter; -import java.io.FileNotFoundException; import java.io.IOException; import java.io.InputStream; import java.io.InputStreamReader; import java.io.OutputStream; -import java.io.OutputStreamWriter; import java.io.UnsupportedEncodingException; import java.io.Writer; @@ -68,8 +65,6 @@ return DocFileFactory.getFactory(configuration).createFileForOutput(path); } - private final Configuration configuration; - /** * The location for this file. Maybe null if the file was created without * a location or path. @@ -95,63 +90,85 @@ } /** Create a DocFile without a location or path */ - protected DocFile(Configuration configuration) { - this.configuration = configuration; + protected DocFile() { this.location = null; this.path = null; } /** Create a DocFile for a given location and relative path. */ - protected DocFile(Configuration configuration, Location location, DocPath path) { - this.configuration = configuration; + protected DocFile(Location location, DocPath path) { this.location = location; this.path = path; } - /** Open an input stream for the file. */ - public abstract InputStream openInputStream() throws IOException; + /** + * Open an input stream for the file. + * + * @return an open input stream for the file + * @throws DocFileIOException if there is a problem opening the stream + */ + public abstract InputStream openInputStream() throws DocFileIOException; /** * Open an output stream for the file. * The file must have been created with a location of * {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} * and a corresponding relative path. + * + * @return an open output stream for the file + * @throws DocFileIOException if there is a problem opening the stream + * @throws UnsupportedEncodingException if the configured encoding is not supported */ - public abstract OutputStream openOutputStream() throws IOException, UnsupportedEncodingException; + public abstract OutputStream openOutputStream() throws DocFileIOException, UnsupportedEncodingException; /** * Open an writer for the file, using the encoding (if any) given in the * doclet configuration. * The file must have been created with a location of * {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path. + * + * @return an open output stream for the file + * @throws DocFileIOException if there is a problem opening the stream + * @throws UnsupportedEncodingException if the configured encoding is not supported */ - public abstract Writer openWriter() throws IOException, UnsupportedEncodingException; + public abstract Writer openWriter() throws DocFileIOException, UnsupportedEncodingException; /** * Copy the contents of another file directly to this file. + * + * @param fromFile the file to be copied + * @throws DocFileIOException if there is a problem file copying the file */ - public void copyFile(DocFile fromFile) throws IOException { - try (OutputStream output = openOutputStream(); - InputStream input = fromFile.openInputStream()) { - byte[] bytearr = new byte[1024]; - int len; - while ((len = input.read(bytearr)) != -1) { - output.write(bytearr, 0, len); + public void copyFile(DocFile fromFile) throws DocFileIOException { + try (OutputStream output = openOutputStream()) { + try (InputStream input = fromFile.openInputStream()) { + byte[] bytearr = new byte[1024]; + int len; + while ((len = read(fromFile, input, bytearr)) != -1) { + write(this, output, bytearr, len); + } + } catch (IOException e) { + throw new DocFileIOException(fromFile, DocFileIOException.Mode.READ, e); } - } - catch (FileNotFoundException | SecurityException exc) { + } catch (IOException e) { + throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); } } /** * Copy the contents of a resource file to this file. + * * @param resource the path of the resource, relative to the package of this class * @param overwrite whether or not to overwrite the file if it already exists * @param replaceNewLine if false, the file is copied as a binary file; * if true, the file is written line by line, using the platform line * separator + * + * @throws DocFileIOException if there is a problem while writing the copy + * @throws ResourceIOException if there is a problem while reading the resource */ - public void copyResource(DocPath resource, boolean overwrite, boolean replaceNewLine) { + public void copyResource(DocPath resource, boolean overwrite, boolean replaceNewLine) + throws DocFileIOException, ResourceIOException { if (exists() && !overwrite) return; @@ -160,30 +177,35 @@ if (in == null) return; - try (OutputStream out = openOutputStream()) { - if (!replaceNewLine) { - byte[] buf = new byte[2048]; - int n; - while ((n = in.read(buf)) > 0) - out.write(buf, 0, n); + try { + if (replaceNewLine) { + try (BufferedReader reader = new BufferedReader(new InputStreamReader(in))) { + try (Writer writer = openWriter()) { + String line; + while ((line = readResourceLine(resource, reader)) != null) { + write(this, writer, line); + write(this, writer, DocletConstants.NL); + } + } catch (IOException e) { + throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); + } + } } else { - try (BufferedReader reader = new BufferedReader(new InputStreamReader(in)); - BufferedWriter writer = new BufferedWriter(configuration.docencoding == null - ? new OutputStreamWriter(out) - : new OutputStreamWriter(out, configuration.docencoding))) { - String line; - while ((line = reader.readLine()) != null) { - writer.write(line); - writer.write(DocletConstants.NL); + try (OutputStream out = openOutputStream()) { + byte[] buf = new byte[2048]; + int n; + while ((n = readResource(resource, in, buf)) > 0) { + write(this, out, buf, n); } + } catch (IOException e) { + throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); } } } finally { in.close(); } } catch (IOException e) { - e.printStackTrace(System.err); - throw new DocletAbortException(e); + throw new ResourceIOException(resource, e); } } @@ -214,8 +236,12 @@ /** Return true if this file is the same as another. */ public abstract boolean isSameFile(DocFile other); - /** If the file is a directory, list its contents. */ - public abstract Iterable list() throws IOException; + /** If the file is a directory, list its contents. + * + * @return the contents of the directory + * @throws DocFileIOException if there is a problem while listing the directory + */ + public abstract Iterable list() throws DocFileIOException; /** Create the file as a directory, including any parent directories. */ public abstract boolean mkdirs(); @@ -242,4 +268,92 @@ * {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} is supported. */ public abstract DocFile resolveAgainst(Location locn); + + + /** + * Reads from an input stream opened from a given file into a given buffer. + * If an IOException occurs, it is wrapped in a DocFileIOException. + * + * @param inFile the file for the stream + * @param input the stream + * @param buf the buffer + * @return the number of bytes read, or -1 if at end of file + * @throws DocFileIOException if an exception occurred while reading the stream + */ + private static int read(DocFile inFile, InputStream input, byte[] buf) throws DocFileIOException { + try { + return input.read(buf); + } catch (IOException e) { + throw new DocFileIOException(inFile, DocFileIOException.Mode.READ, e); + } + } + + /** + * Writes to an output stream for a given file from a given buffer. + * If an IOException occurs, it is wrapped in a DocFileIOException. + * + * @param outFile the file for the stream + * @param out the stream + * @param buf the buffer + * @throws DocFileIOException if an exception occurred while writing the stream + */ + private static void write(DocFile outFile, OutputStream out, byte[] buf, int len) throws DocFileIOException { + try { + out.write(buf, 0, len); + } catch (IOException e) { + throw new DocFileIOException(outFile, DocFileIOException.Mode.WRITE, e); + } + } + + /** + * Writes text to an output stream for a given file from a given buffer. + * If an IOException occurs, it is wrapped in a DocFileIOException. + * + * @param outFile the file for the stream + * @param out the stream + * @param text the text to be written + * @throws DocFileIOException if an exception occurred while writing the stream + */ + private static void write(DocFile outFile, Writer out, String text) throws DocFileIOException { + try { + out.write(text); + } catch (IOException e) { + throw new DocFileIOException(outFile, DocFileIOException.Mode.WRITE, e); + } + } + + /** + * Reads from an input stream opened from a given resource into a given buffer. + * If an IOException occurs, it is wrapped in a ResourceIOException. + * + * @param resource the resource for the stream + * @param in the stream + * @param buf the buffer + * @return the number of bytes read, or -1 if at end of file + * @throws ResourceIOException if an exception occurred while reading the stream + */ + private static int readResource(DocPath resource, InputStream in, byte[] buf) throws ResourceIOException { + try { + return in.read(buf); + } catch (IOException e) { + throw new ResourceIOException(resource, e); + } + } + + /** + * Reads a line of characters from an input stream opened from a given resource. + * If an IOException occurs, it is wrapped in a ResourceIOException. + * + * @param resource the resource for the stream + * @param in the stream + * @return the line of text, or {@code null} if at end of stream + * @throws ResourceIOException if an exception occurred while reading the stream + */ + private static String readResourceLine(DocPath docPath, BufferedReader in) throws ResourceIOException { + try { + return in.readLine(); + } catch (IOException e) { + throw new ResourceIOException(docPath, e); + } + } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFileFactory.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFileFactory.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFileFactory.java Mon Aug 22 16:32:40 2016 -0700 @@ -31,6 +31,7 @@ import javax.tools.StandardLocation; import jdk.javadoc.internal.doclets.toolkit.Configuration; +import jdk.javadoc.internal.doclets.toolkit.DocletException; /** * Factory for DocFile objects. @@ -45,8 +46,11 @@ /** * Get the appropriate factory, based on the file manager given in the * configuration. + * + * @param configuration the configuration for this doclet + * @return the factory associated with this configuration */ - static synchronized DocFileFactory getFactory(Configuration configuration) { + public static synchronized DocFileFactory getFactory(Configuration configuration) { DocFileFactory f = configuration.docFileFactory; if (f == null) { JavaFileManager fm = configuration.getFileManager(); @@ -66,6 +70,8 @@ this.configuration = configuration; } + public abstract void setDestDir(String dir) throws DocletException; + /** Create a DocFile for a directory. */ abstract DocFile createFileForDirectory(String file); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFileIOException.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFileIOException.java Mon Aug 22 16:32:40 2016 -0700 @@ -0,0 +1,82 @@ +/* + * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package jdk.javadoc.internal.doclets.toolkit.util; + +import java.io.IOException; + +import jdk.javadoc.internal.doclets.toolkit.DocletException; + + +/** + * Wraps an IOException and the filename to which it applies. + * + *

This is NOT part of any supported API. + * If you write code that depends on this, you do so at your own risk. + * This code and its internal interfaces are subject to change or + * deletion without notice. + * + * @apiNote This exception should be thrown by a doclet when an IO exception occurs + * and the file is known that was in use when the exception occurred. + */ +public class DocFileIOException extends DocletException { + /** + * A hint for the type of operation being performed when the exception occurred. + * + * @apiNote This may be used as a hint when reporting a message to the end user. + */ + public enum Mode { + /** The file was being opened for reading, or being read when the exception occurred. */ + READ, + /** The file was being opened for writing, or being written when the exception occurred. */ + WRITE + }; + + /** + * The file that was in use when the exception occurred. + */ + public final DocFile fileName; + + /** + * The mode in which the file was being used when the exception occurred. + */ + public final Mode mode; + + private static final long serialVersionUID = 1L; + + /** + * Creates an exception to wrap an IO exception, the file which caused it, and the manner + * in which the file was being used. + * + * @param fileName the file in use when the exception occurred + * @param mode the manner in which the file was being used + * @param cause the underlying exception + */ + public DocFileIOException(DocFile fileName, Mode mode, IOException cause) { + super(mode + ":" + fileName.getPath(), cause); + this.fileName = fileName; + this.mode = mode; + } +} diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocletAbortException.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocletAbortException.java Wed Jul 05 22:07:34 2017 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,44 +0,0 @@ -/* - * Copyright (c) 1997, 2015, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA - * or visit www.oracle.com if you need additional information or have any - * questions. - */ - -package jdk.javadoc.internal.doclets.toolkit.util; - -/** - *

This is NOT part of any supported API. - * If you write code that depends on this, you do so at your own risk. - * This code and its internal interfaces are subject to change or - * deletion without notice. - */ -public class DocletAbortException extends RuntimeException { - private static final long serialVersionUID = -9131058909576418984L; - - public DocletAbortException(String message) { - super(message); - } - - public DocletAbortException(Throwable cause) { - super(cause); - } -} diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java Mon Aug 22 16:32:40 2016 -0700 @@ -117,6 +117,7 @@ /** * String representation of "this" with packagename and the path. */ + @Override public String toString() { return packageName + (relative? " -> " : " => ") + path; } @@ -130,6 +131,7 @@ * Determine if a element item is externally documented. * * @param element an Element. + * @return true if the element is externally documented */ public boolean isExternal(Element element) { if (packageToItemMap == null) { @@ -176,8 +178,11 @@ * file. * @param reporter The DocErrorReporter used to report errors. * @param linkoffline True if -linkoffline is used and false if -link is used. + * @return true if successful, false otherwise + * @throws DocFileIOException if there is a problem reading a package list file */ - public boolean link(String url, String pkglisturl, Reporter reporter, boolean linkoffline) { + public boolean link(String url, String pkglisturl, Reporter reporter, boolean linkoffline) + throws DocFileIOException { this.linkoffline = linkoffline; try { url = adjustEndFileSeparator(url); @@ -251,9 +256,11 @@ * * @param path URL or directory path to the packages. * @param pkgListPath Path to the local "package-list" file. + * @throws Fault if an error occurs that can be treated as a warning + * @throws DocFileIOException if there is a problem opening the package list file */ private void readPackageListFromFile(String path, DocFile pkgListPath) - throws Fault { + throws Fault, DocFileIOException { DocFile file = pkgListPath.resolve(DocPaths.PACKAGE_LIST); if (! (file.isAbsolute() || linkoffline)){ file = file.resolveAgainst(DocumentationTool.Location.DOCUMENTATION_OUTPUT); @@ -279,35 +286,33 @@ * @param input InputStream from the "package-list" file. * @param path URL or the directory path to the packages. * @param relative Is path relative? + * @throws IOException if there is a problem reading or closing the stream */ private void readPackageList(InputStream input, String path, boolean relative) throws IOException { - BufferedReader in = new BufferedReader(new InputStreamReader(input)); - StringBuilder strbuf = new StringBuilder(); - try { + try (BufferedReader in = new BufferedReader(new InputStreamReader(input))) { + StringBuilder strbuf = new StringBuilder(); int c; while ((c = in.read()) >= 0) { - char ch = (char)c; + char ch = (char) c; if (ch == '\n' || ch == '\r') { if (strbuf.length() > 0) { String packname = strbuf.toString(); - String packpath = path + - packname.replace('.', '/') + '/'; - new Item(packname, packpath, relative); + String packpath = path + + packname.replace('.', '/') + '/'; + Item ignore = new Item(packname, packpath, relative); strbuf.setLength(0); } } else { strbuf.append(ch); } } - } finally { - input.close(); } } public boolean isUrl (String urlCandidate) { try { - new URL(urlCandidate); + URL ignore = new URL(urlCandidate); //No exception was thrown, so this must really be a URL. return true; } catch (MalformedURLException e) { diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/InternalException.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/InternalException.java Mon Aug 22 16:32:40 2016 -0700 @@ -0,0 +1,53 @@ +/* + * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package jdk.javadoc.internal.doclets.toolkit.util; + +import jdk.javadoc.internal.doclets.toolkit.DocletException; + + +/** + * An exception with a user-friendly detail message for an unexpected/internal exception. + * + *

This is NOT part of any supported API. + * If you write code that depends on this, you do so at your own risk. + * This code and its internal interfaces are subject to change or + * deletion without notice. + */ +public class InternalException extends DocletException { + + private static final long serialVersionUID = 1L; + + /** + * Creates an exception with a user-friendly detail message, and underlying cause. + * A stacktrace for the cause may be presented to the user. + * + * @param message a localized detail message, suitable for direct presentation to the end user + * @param cause the underlying cause for the exception + */ + public InternalException(String message, Throwable cause) { + super(message, cause); + } +} diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PackageListWriter.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PackageListWriter.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/PackageListWriter.java Mon Aug 22 16:32:40 2016 -0700 @@ -26,13 +26,11 @@ package jdk.javadoc.internal.doclets.toolkit.util; import java.io.*; -import java.util.*; import javax.lang.model.element.PackageElement; import jdk.javadoc.doclet.DocletEnvironment; import jdk.javadoc.internal.doclets.toolkit.Configuration; -import jdk.javadoc.internal.doclets.toolkit.Messages; /** @@ -45,18 +43,19 @@ * * @author Atul M Dambalkar */ -public class PackageListWriter extends PrintWriter { +public class PackageListWriter { private final Configuration configuration; private final Utils utils; + private final DocFile file; /** * Constructor. * * @param configuration the current configuration of the doclet. */ - public PackageListWriter(Configuration configuration) throws IOException { - super(DocFile.createFileForOutput(configuration, DocPaths.PACKAGE_LIST).openWriter()); + public PackageListWriter(Configuration configuration) { + file = DocFile.createFileForOutput(configuration, DocPaths.PACKAGE_LIST); this.configuration = configuration; this.utils = configuration.utils; } @@ -65,32 +64,25 @@ * Generate the package index. * * @param configuration the current configuration of the doclet. - * @throws DocletAbortException + * @throws DocFileIOException if there is a problem writing the output */ - public static void generate(Configuration configuration) { - PackageListWriter packgen; - try { - packgen = new PackageListWriter(configuration); - packgen.generatePackageListFile(configuration.docEnv); - packgen.close(); - } catch (IOException exc) { - Messages messages = configuration.getMessages(); - messages.error("doclet.exception_encountered", - exc.toString(), DocPaths.PACKAGE_LIST); - throw new DocletAbortException(exc); + public static void generate(Configuration configuration) throws DocFileIOException { + PackageListWriter packgen = new PackageListWriter(configuration); + packgen.generatePackageListFile(configuration.docEnv); + } + + protected void generatePackageListFile(DocletEnvironment docEnv) throws DocFileIOException { + try (BufferedWriter out = new BufferedWriter(file.openWriter())) { + for (PackageElement pkg : configuration.packages) { + // if the -nodeprecated option is set and the package is marked as + // deprecated, do not include it in the packages list. + if (!(configuration.nodeprecated && utils.isDeprecated(pkg))) { + out.write(pkg.toString()); + out.newLine(); + } + } + } catch (IOException e) { + throw new DocFileIOException(file, DocFileIOException.Mode.WRITE, e); } } - - protected void generatePackageListFile(DocletEnvironment docEnv) { - ArrayList names = new ArrayList<>(); - for (PackageElement pkg : configuration.packages) { - // if the -nodeprecated option is set and the package is marked as - // deprecated, do not include it in the packages list. - if (!(configuration.nodeprecated && utils.isDeprecated(pkg))) - names.add(pkg); - } - names.stream().forEach((name) -> { - println(name); - }); - } } diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ResourceIOException.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/ResourceIOException.java Mon Aug 22 16:32:40 2016 -0700 @@ -0,0 +1,63 @@ +/* + * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package jdk.javadoc.internal.doclets.toolkit.util; + +import java.io.IOException; + +import jdk.javadoc.internal.doclets.toolkit.DocletException; + + +/** + * Wraps an IOException and the path for the resource to which it applies. + * + *

This is NOT part of any supported API. + * If you write code that depends on this, you do so at your own risk. + * This code and its internal interfaces are subject to change or + * deletion without notice. + * + * @apiNote This exception should be thrown by a doclet when an IO exception occurs + * and the file is known that was in use when the exception occurred. + */ +public class ResourceIOException extends DocletException { + + /** + * The resource that was in use when the exception occurred. + */ + public final DocPath resource; + + private static final long serialVersionUID = 1L; + + /** + * Creates an exception to wrap an IO exception, the resource which caused it. + * + * @param resource the resource in use when the exception occurred + * @param cause the underlying exception + */ + public ResourceIOException(DocPath resource, IOException cause) { + super(resource.getPath(), cause); + this.resource = resource; + } +} diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/SimpleDocletException.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/SimpleDocletException.java Mon Aug 22 16:32:40 2016 -0700 @@ -0,0 +1,62 @@ +/* + * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package jdk.javadoc.internal.doclets.toolkit.util; + +import jdk.javadoc.internal.doclets.toolkit.DocletException; + + +/** + * An exception with a user-friendly detail message. + * + *

This is NOT part of any supported API. + * If you write code that depends on this, you do so at your own risk. + * This code and its internal interfaces are subject to change or + * deletion without notice. + */ +public class SimpleDocletException extends DocletException { + + private static final long serialVersionUID = 1L; + + /** + * Creates an exception with a user-friendly detail message. + * + * @param message a localized detail message, suitable for direct presentation to the end user + */ + public SimpleDocletException(String message) { + super(message); + } + + /** + * Creates an exception with a user-friendly detail message, and underlying cause. + * The cause may be used for debugging but in normal use, should not be presented to the user. + * + * @param message a localized detail message, suitable for direct presentation to the end user + * @param cause the underlying cause for the exception + */ + public SimpleDocletException(String message, Throwable cause) { + super(message, cause); + } +} diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/StandardDocFileFactory.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/StandardDocFileFactory.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/StandardDocFileFactory.java Mon Aug 22 16:32:40 2016 -0700 @@ -42,6 +42,7 @@ import java.util.Arrays; import java.util.LinkedHashSet; import java.util.List; +import java.util.Objects; import java.util.Set; import javax.tools.DocumentationTool; @@ -72,32 +73,43 @@ fileManager = (StandardJavaFileManager) configuration.getFileManager(); } + @Override + public void setDestDir(String destDirName) throws SimpleDocletException { + if (destDir != null) + throw new AssertionError("destDir already initialized: " + destDir); + + if (!destDirName.isEmpty() + || !fileManager.hasLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT)) { + try { + String dirName = destDirName.isEmpty() ? "." : destDirName; + Path dir = Paths.get(dirName); + fileManager.setLocationFromPaths(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(dir)); + } catch (IOException e) { + // generic IOException from file manager, setting location, e.g. file not a directory + String message = configuration.getResources().getText("doclet.error.initializing.dest.dir", e); + throw new SimpleDocletException(message, e); + } + } + + destDir = fileManager.getLocationAsPaths(DocumentationTool.Location.DOCUMENTATION_OUTPUT).iterator().next(); + } + private Path getDestDir() { - if (destDir == null) { - if (!configuration.destDirName.isEmpty() - || !fileManager.hasLocation(DocumentationTool.Location.DOCUMENTATION_OUTPUT)) { - try { - String dirName = configuration.destDirName.isEmpty() ? "." : configuration.destDirName; - Path dir = Paths.get(dirName); - fileManager.setLocationFromPaths(DocumentationTool.Location.DOCUMENTATION_OUTPUT, Arrays.asList(dir)); - } catch (IOException e) { - throw new DocletAbortException(e); - } - } - - destDir = fileManager.getLocationAsPaths(DocumentationTool.Location.DOCUMENTATION_OUTPUT).iterator().next(); - } + Objects.requireNonNull(destDir, "destDir not initialized"); return destDir; } + @Override public DocFile createFileForDirectory(String file) { return new StandardDocFile(Paths.get(file)); } + @Override public DocFile createFileForInput(String file) { return new StandardDocFile(Paths.get(file)); } + @Override public DocFile createFileForOutput(DocPath path) { return new StandardDocFile(DocumentationTool.Location.DOCUMENTATION_OUTPUT, path); } @@ -125,38 +137,53 @@ } class StandardDocFile extends DocFile { - private Path file; + private final Path file; /** Create a StandardDocFile for a given file. */ private StandardDocFile(Path file) { - super(configuration); this.file = file; } /** Create a StandardDocFile for a given location and relative path. */ private StandardDocFile(Location location, DocPath path) { - super(configuration, location, path); + super(location, path); Assert.check(location == DocumentationTool.Location.DOCUMENTATION_OUTPUT); this.file = newFile(getDestDir(), path.getPath()); } - /** Open an input stream for the file. */ - public InputStream openInputStream() throws IOException { - JavaFileObject fo = getJavaFileObjectForInput(file); - return new BufferedInputStream(fo.openInputStream()); + /** + * Open an input stream for the file. + * + * @throws DocFileIOException if there is a problem while opening stream + */ + @Override + public InputStream openInputStream() throws DocFileIOException { + try { + JavaFileObject fo = getJavaFileObjectForInput(file); + return new BufferedInputStream(fo.openInputStream()); + } catch (IOException e) { + throw new DocFileIOException(this, DocFileIOException.Mode.READ, e); + } } /** * Open an output stream for the file. * The file must have been created with a location of * {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path. + * + * @throws DocFileIOException if there is a problem while opening stream */ - public OutputStream openOutputStream() throws IOException, UnsupportedEncodingException { + @Override + public OutputStream openOutputStream() throws DocFileIOException { if (location != DocumentationTool.Location.DOCUMENTATION_OUTPUT) throw new IllegalStateException(); - OutputStream out = getFileObjectForOutput(path).openOutputStream(); - return new BufferedOutputStream(out); + try { + OutputStream out = getFileObjectForOutput(path).openOutputStream(); + return new BufferedOutputStream(out); + } catch (IOException e) { + throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); + } } /** @@ -164,60 +191,77 @@ * doclet configuration. * The file must have been created with a location of * {@link DocumentationTool.Location#DOCUMENTATION_OUTPUT} and a corresponding relative path. + * + * @throws DocFileIOException if there is a problem while opening stream + * @throws UnsupportedEncodingException if the configured encoding is not supported */ - public Writer openWriter() throws IOException, UnsupportedEncodingException { + @Override + public Writer openWriter() throws DocFileIOException, UnsupportedEncodingException { if (location != DocumentationTool.Location.DOCUMENTATION_OUTPUT) throw new IllegalStateException(); - OutputStream out = getFileObjectForOutput(path).openOutputStream(); - if (configuration.docencoding == null) { - return new BufferedWriter(new OutputStreamWriter(out)); - } else { - return new BufferedWriter(new OutputStreamWriter(out, configuration.docencoding)); + try { + OutputStream out = getFileObjectForOutput(path).openOutputStream(); + if (configuration.docencoding == null) { + return new BufferedWriter(new OutputStreamWriter(out)); + } else { + return new BufferedWriter(new OutputStreamWriter(out, configuration.docencoding)); + } + } catch (IOException e) { + throw new DocFileIOException(this, DocFileIOException.Mode.WRITE, e); } } /** Return true if the file can be read. */ + @Override public boolean canRead() { return Files.isReadable(file); } /** Return true if the file can be written. */ + @Override public boolean canWrite() { return Files.isWritable(file); } /** Return true if the file exists. */ + @Override public boolean exists() { return Files.exists(file); } /** Return the base name (last component) of the file name. */ + @Override public String getName() { return file.getFileName().toString(); } /** Return the file system path for this file. */ + @Override public String getPath() { return file.toString(); } /** Return true is file has an absolute path name. */ + @Override public boolean isAbsolute() { return file.isAbsolute(); } /** Return true is file identifies a directory. */ + @Override public boolean isDirectory() { return Files.isDirectory(file); } /** Return true is file identifies a file. */ + @Override public boolean isFile() { return Files.isRegularFile(file); } /** Return true if this file is the same as another. */ + @Override public boolean isSameFile(DocFile other) { if (!(other instanceof StandardDocFile)) return false; @@ -230,17 +274,21 @@ } /** If the file is a directory, list its contents. */ - public Iterable list() throws IOException { - List files = new ArrayList(); + @Override + public Iterable list() throws DocFileIOException { + List files = new ArrayList<>(); try (DirectoryStream ds = Files.newDirectoryStream(file)) { for (Path f: ds) { files.add(new StandardDocFile(f)); } + } catch (IOException e) { + throw new DocFileIOException(this, DocFileIOException.Mode.READ, e); } return files; } /** Create the file as a directory, including any parent directories. */ + @Override public boolean mkdirs() { try { Files.createDirectories(file); @@ -256,6 +304,7 @@ * If this file has a path set, the new file will have a corresponding * new path. */ + @Override public DocFile resolve(DocPath p) { return resolve(p.getPath()); } @@ -266,6 +315,7 @@ * If this file has a path set, the new file will have a corresponding * new path. */ + @Override public DocFile resolve(String p) { if (location == null && path == null) { return new StandardDocFile(file.resolve(p)); @@ -279,6 +329,7 @@ * @param locn Currently, only * {@link DocumentationTool.Location.DOCUMENTATION_OUTPUT} is supported. */ + @Override public DocFile resolveAgainst(Location locn) { if (locn != DocumentationTool.Location.DOCUMENTATION_OUTPUT) throw new IllegalArgumentException(); diff -r e17429a7e843 -r 1c355ea550ed langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java --- a/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java Wed Jul 05 22:07:34 2017 +0200 +++ b/langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java Mon Aug 22 16:32:40 2016 -0700 @@ -25,7 +25,6 @@ package jdk.javadoc.internal.doclets.toolkit.util; -import java.io.*; import java.lang.annotation.Documented; import java.lang.ref.SoftReference; import java.text.CollationKey; @@ -78,6 +77,7 @@ import com.sun.tools.javac.util.DefinedBy.Api; import jdk.javadoc.internal.doclets.toolkit.CommentUtils.DocCommentDuo; import jdk.javadoc.internal.doclets.toolkit.Configuration; +import jdk.javadoc.internal.doclets.toolkit.Messages; import jdk.javadoc.internal.doclets.toolkit.WorkArounds; import static javax.lang.model.element.ElementKind.*; @@ -85,9 +85,6 @@ import static javax.lang.model.type.TypeKind.*; import static com.sun.source.doctree.DocTree.Kind.*; - -import jdk.javadoc.internal.doclets.toolkit.Messages; - import static jdk.javadoc.internal.doclets.toolkit.builders.ConstantsSummaryBuilder.MAX_CONSTANT_VALUE_INDEX_LENGTH; @@ -274,48 +271,52 @@ * {@link SourcePath} and if given directory is found in the source * directory structure, copy the entire directory, to the generated * documentation hierarchy. - * @param pe + * + * @param pe the package containing the doc files to be copied + * @throws DocFileIOException if there is a problem while copying the documentation files */ - public void copyDocFiles(PackageElement pe) { + public void copyDocFiles(PackageElement pe) throws DocFileIOException { copyDocFiles(DocPath.forPackage(pe).resolve(DocPaths.DOC_FILES)); } - public void copyDocFiles(DocPath dir) { - try { - boolean first = true; - for (DocFile f : DocFile.list(configuration, StandardLocation.SOURCE_PATH, dir)) { - if (!f.isDirectory()) { - continue; - } - DocFile srcdir = f; - DocFile destdir = DocFile.createFileForOutput(configuration, dir); - if (srcdir.isSameFile(destdir)) { - continue; - } + /** + * This method is obsolete, should not be used, and should be deleted. + * It does not take module locations into account! + * + * @throws DocFileIOException if there is a problem while copying the documentation files + */ + public void copyDocFiles(DocPath dir) throws DocFileIOException { + boolean first = true; + for (DocFile f : DocFile.list(configuration, StandardLocation.SOURCE_PATH, dir)) { + if (!f.isDirectory()) { + continue; + } + DocFile srcdir = f; + DocFile destdir = DocFile.createFileForOutput(configuration, dir); + if (srcdir.isSameFile(destdir)) { + continue; + } for (DocFile srcfile: srcdir.list()) { - DocFile destfile = destdir.resolve(srcfile.getName()); - if (srcfile.isFile()) { - if (destfile.exists() && !first) { - messages.warning("doclet.Copy_Overwrite_warning", - srcfile.getPath(), destdir.getPath()); - } else { - messages.notice("doclet.Copying_File_0_To_Dir_1", - srcfile.getPath(), destdir.getPath()); - destfile.copyFile(srcfile); - } - } else if (srcfile.isDirectory()) { - if (configuration.copydocfilesubdirs - && !configuration.shouldExcludeDocFileDir(srcfile.getName())) { - copyDocFiles(dir.resolve(srcfile.getName())); - } + DocFile destfile = destdir.resolve(srcfile.getName()); + if (srcfile.isFile()) { + if (destfile.exists() && !first) { + messages.warning("doclet.Copy_Overwrite_warning", + srcfile.getPath(), destdir.getPath()); + } else { + messages.notice("doclet.Copying_File_0_To_Dir_1", + srcfile.getPath(), destdir.getPath()); + destfile.copyFile(srcfile); + } + } else if (srcfile.isDirectory()) { + if (configuration.copydocfilesubdirs + && !configuration.shouldExcludeDocFileDir(srcfile.getName())) { + copyDocFiles(dir.resolve(srcfile.getName())); } } - - first = false; } - } catch (SecurityException | IOException exc) { - throw new DocletAbortException(exc); + + first = false; } } @@ -1567,42 +1568,45 @@ return secondaryCollator.compare(s1, s2); } - public void copyDocFiles(Configuration configuration, Location locn, DocPath dir) { - try { - boolean first = true; - for (DocFile f : DocFile.list(configuration, locn, dir)) { - if (!f.isDirectory()) { - continue; - } - DocFile srcdir = f; - DocFile destdir = DocFile.createFileForOutput(configuration, dir); - if (srcdir.isSameFile(destdir)) { - continue; - } - - for (DocFile srcfile: srcdir.list()) { - DocFile destfile = destdir.resolve(srcfile.getName()); - if (srcfile.isFile()) { - if (destfile.exists() && !first) { - messages.warning("doclet.Copy_Overwrite_warning", - srcfile.getPath(), destdir.getPath()); - } else { - messages.notice("doclet.Copying_File_0_To_Dir_1", - srcfile.getPath(), destdir.getPath()); - destfile.copyFile(srcfile); - } - } else if (srcfile.isDirectory()) { - if (configuration.copydocfilesubdirs - && !configuration.shouldExcludeDocFileDir(srcfile.getName())) { - copyDocFiles(configuration, locn, dir.resolve(srcfile.getName())); - } + /** + * @param configuration the configuration for this doclet + * @param locn the location from which to read files + * @param dir the path for the files to be copied + * @throws DocFileIOException if there is a problem copying the files + */ + public void copyDocFiles(Configuration configuration, Location locn, DocPath dir) + throws DocFileIOException { + boolean first = true; + for (DocFile f : DocFile.list(configuration, locn, dir)) { + if (!f.isDirectory()) { + continue; + } + DocFile srcdir = f; + DocFile destdir = DocFile.createFileForOutput(configuration, dir); + if (srcdir.isSameFile(destdir)) { + continue; + } + + for (DocFile srcfile: srcdir.list()) { + DocFile destfile = destdir.resolve(srcfile.getName()); + if (srcfile.isFile()) { + if (destfile.exists() && !first) { + messages.warning("doclet.Copy_Overwrite_warning", + srcfile.getPath(), destdir.getPath()); + } else { + messages.notice("doclet.Copying_File_0_To_Dir_1", + srcfile.getPath(), destdir.getPath()); + destfile.copyFile(srcfile); + } + } else if (srcfile.isDirectory()) { + if (configuration.copydocfilesubdirs + && !configuration.shouldExcludeDocFileDir(srcfile.getName())) { + copyDocFiles(configuration, locn, dir.resolve(srcfile.getName())); } } - - first = false; } - } catch (SecurityException | IOException exc) { - throw new DocletAbortException(exc); + + first = false; } } diff -r e17429a7e843 -r 1c355ea550ed langtools/test/jdk/javadoc/doclet/testIOException/TestIOException.java --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/langtools/test/jdk/javadoc/doclet/testIOException/TestIOException.java Mon Aug 22 16:32:40 2016 -0700 @@ -0,0 +1,179 @@ +/* + * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/* + * @test + * @bug 8164130 + * @summary test IOException handling + * @library ../lib + * @modules jdk.javadoc/jdk.javadoc.internal.tool + * @build JavadocTester + * @run main TestIOException + */ + +import java.io.File; +import java.io.FileWriter; + +public class TestIOException extends JavadocTester { + + public static void main(String... args) throws Exception { + TestIOException tester = new TestIOException(); + tester.runTests(); + } + + @Test + void testReadOnlyDirectory() { + File outDir = new File("out1"); + if (!outDir.mkdir()) { + throw new Error("Cannot create directory"); + } + if (!outDir.setReadOnly()) { + throw new Error("could not set directory read-only"); + } + if (outDir.canWrite()) { + throw new Error("directory is writable"); + } + + try { + javadoc("-d", outDir.toString(), + new File(testSrc, "TestIOException.java").getPath()); + checkExit(Exit.FAILED); + checkOutput(Output.OUT, true, + "Destination directory not writable: " + outDir); + } finally { + outDir.setWritable(true); + } + } + + @Test + void testReadOnlyFile() throws Exception { + File outDir = new File("out2"); + if (!outDir.mkdir()) { + throw new Error("Cannot create directory"); + } + File index = new File(outDir, "index.html"); + try (FileWriter fw = new FileWriter(index)) { } + if (!index.setReadOnly()) { + throw new Error("could not set index read-only"); + } + if (index.canWrite()) { + throw new Error("index is writable"); + } + + try { + setOutputDirectoryCheck(DirectoryCheck.NONE); + javadoc("-d", outDir.toString(), + new File(testSrc, "TestIOException.java").getPath()); + + checkExit(Exit.FAILED); + checkOutput(Output.OUT, true, + "Error writing file: " + index); + } finally { + setOutputDirectoryCheck(DirectoryCheck.EMPTY); + index.setWritable(true); + } + } + + @Test + void testReadOnlySubdirectory() throws Exception { + // init source file + File srcDir = new File("src4"); + File src_p = new File(srcDir, "p"); + src_p.mkdirs(); + File src_p_C = new File(src_p, "C.java"); + try (FileWriter fw = new FileWriter(src_p_C)) { + fw.write("package p; public class C { }"); + } + + // create an unwritable package output directory + File outDir = new File("out3"); + File pkgOutDir = new File(outDir, "p"); + if (!pkgOutDir.mkdirs()) { + throw new Error("Cannot create directory"); + } + if (!pkgOutDir.setReadOnly()) { + throw new Error("could not set directory read-only"); + } + if (pkgOutDir.canWrite()) { + throw new Error("directory is writable"); + } + + // run javadoc and check results + try { + setOutputDirectoryCheck(DirectoryCheck.NONE); + javadoc("-d", outDir.toString(), + src_p_C.getPath()); + checkExit(Exit.FAILED); + checkOutput(Output.OUT, true, + "Error writing file: " + new File(pkgOutDir, "C.html")); + } finally { + setOutputDirectoryCheck(DirectoryCheck.EMPTY); + pkgOutDir.setWritable(true); + } + } + + @Test + void testReadOnlyDocFilesDir() throws Exception { + // init source files + File srcDir = new File("src4"); + File src_p = new File(srcDir, "p"); + src_p.mkdirs(); + File src_p_C = new File(src_p, "C.java"); + try (FileWriter fw = new FileWriter(src_p_C)) { + fw.write("package p; public class C { }"); + } + File src_p_docfiles = new File(src_p, "doc-files"); + src_p_docfiles.mkdir(); + try (FileWriter fw = new FileWriter(new File(src_p_docfiles, "info.txt"))) { + fw.write("info"); + } + + // create an unwritable doc-files output directory + File outDir = new File("out4"); + File pkgOutDir = new File(outDir, "p"); + File docFilesOutDir = new File(pkgOutDir, "doc-files"); + if (!docFilesOutDir.mkdirs()) { + throw new Error("Cannot create directory"); + } + if (!docFilesOutDir.setReadOnly()) { + throw new Error("could not set directory read-only"); + } + if (docFilesOutDir.canWrite()) { + throw new Error("directory is writable"); + } + + try { + setOutputDirectoryCheck(DirectoryCheck.NONE); + javadoc("-d", outDir.toString(), + "-sourcepath", srcDir.getPath(), + "p"); + checkExit(Exit.FAILED); + checkOutput(Output.OUT, true, + "Error writing file: " + new File(docFilesOutDir, "info.txt")); + } finally { + setOutputDirectoryCheck(DirectoryCheck.EMPTY); + docFilesOutDir.setWritable(true); + } + } +} +