--- 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;
--- 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<SearchIndexItem> searchIndex) {
+ List<SearchIndexItem> 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);
- }
- }
}
--- 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) { }
}
--- 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;
--- 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) {
--- 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,
--- 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);
--- 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));
--- 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);
--- 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.*;
--- 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);
}
}
--- 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;
--- 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()");
--- 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))
--- 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<String> files = Arrays.asList(
"jquery-1.10.2.js",
"jquery-ui.js",
@@ -232,7 +233,8 @@
* {@inheritDoc}
*/
@Override // defined by AbstractDoclet
- protected void generateClassFiles(SortedSet<TypeElement> arr, ClassTree classtree) {
+ protected void generateClassFiles(SortedSet<TypeElement> arr, ClassTree classtree)
+ throws DocletException {
List<TypeElement> list = new ArrayList<>(arr);
ListIterator<TypeElement> 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<PackageElement> 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);
}
}
--- 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<String> 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;
}
--- 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;
--- 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);
}
/**
--- 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);
}
/**
--- 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<ModuleElement, Set<PackageElement>> modules, String text,
String tableSummary, Content body, ModuleElement mdle) {
}
+ @Override
protected void addModulesList(Map<ModuleElement, Set<PackageElement>> modules, String text,
String tableSummary, Content body) {
}
--- 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);
}
/**
--- 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);
}
--- 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
*/
--- 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<PackageElement> 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);
--- 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<String, SortedSet<PackageElement>> groupPackageMap;
+ private final Map<String, SortedSet<PackageElement>> groupPackageMap;
/**
* List to store the order groups as specified on the command line.
*/
- private List<String> groupList;
+ private final List<String> 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<PackageElement> list = groupPackageMap.get(groupname);
@@ -133,6 +121,7 @@
/**
* {@inheritDoc}
*/
+ @Override
protected void addPackagesList(Collection<PackageElement> 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()
--- 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);
--- 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<String> 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);
--- 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<TypeElement> classes, String label,
String tableSummary, List<String> 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;
--- 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);
}
--- 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))
--- 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 <code>Doc</code>, return an anchor name for it.
+ * Given an element, return an anchor name for it.
*
- * @param d the <code>Doc</code> 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) {
--- 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<Character> indexElements;
+ private final List<Character> 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<Character> 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<Character> keys = new TreeSet<>(indexbuilder.getIndexMap().keySet());
- keys.addAll(configuration.tagSearchIndexKeys);
- ListIterator<Character> 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<Character> keys = new TreeSet<>(indexbuilder.getIndexMap().keySet());
+ keys.addAll(configuration.tagSearchIndexKeys);
+ ListIterator<Character> 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) {
--- 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);
--- 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);
}
}
--- 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();
}
/**
--- 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();
}
/**
--- 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();
}
/**
--- 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) {
--- 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();
}
/**
--- 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);
}
}
--- 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();
}
/**
--- 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();
}
/**
--- 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=<directory>
--- 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<TypeElement> arr, ClassTree classtree);
+ protected abstract void generateClassFiles(SortedSet<TypeElement> 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<PackageElement> 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<PackageElement> packages = configuration.typeElementCatalog.packages();
- packages.stream().forEach((pkg) -> {
+ for (PackageElement pkg : packages) {
generateClassFiles(configuration.typeElementCatalog.allClasses(pkg), classtree);
- });
+ }
}
}
--- 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.
--- 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.
--- 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 <code>getResources.getText(key);</code>.
+ *
* @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 <code>getResources.getText(key, args);</code>.
+ *
* @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();
--- 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;
}
--- 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();
}
--- /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.
+ *
+ * <p><b>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.</b>
+ *
+ * @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();
+ }
+ }
+}
--- 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;
}
--- 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;
}
--- 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);
--- 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();
}
--- 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);
- }
}
--- 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();
}
--- 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);
}
--- 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;
}
--- 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);
}
--- 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;
}
--- 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);
}
}
--- 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);
}
--- 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<TypeElement> classes = !currentPackage.isUnnamed()
? utils.getAllClasses(currentPackage)
: configuration.typeElementCatalog.allUnnamedClasses();
--- 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<Element> 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;
}
--- 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;
}
--- 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;
}
--- 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<String,XMLNode> xmlElementsMap;
+ private final Map<String,XMLNode> 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);
--- 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();
--- 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;
}
--- 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));
--- 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);
--- 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;
}
--- 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<TypeElement> 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<TypeElement> 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<TypeElement> 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<ExecutableElement> 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<VariableElement> 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.
--- 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...
--- 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<DocFile> 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<DocFile> 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);
+ }
+ }
}
--- 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);
--- /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.
+ *
+ * <p><b>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.</b>
+ *
+ * @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;
+ }
+}
--- 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;
-
-/**
- * <p><b>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.</b>
- */
-public class DocletAbortException extends RuntimeException {
- private static final long serialVersionUID = -9131058909576418984L;
-
- public DocletAbortException(String message) {
- super(message);
- }
-
- public DocletAbortException(Throwable cause) {
- super(cause);
- }
-}
--- 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 <code>DocErrorReporter</code> 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) {
--- /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.
+ *
+ * <p><b>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.</b>
+ */
+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);
+ }
+}
--- 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<PackageElement> 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);
- });
- }
}
--- /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.
+ *
+ * <p><b>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.</b>
+ *
+ * @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;
+ }
+}
--- /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.
+ *
+ * <p><b>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.</b>
+ */
+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);
+ }
+}
--- 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<DocFile> list() throws IOException {
- List<DocFile> files = new ArrayList<DocFile>();
+ @Override
+ public Iterable<DocFile> list() throws DocFileIOException {
+ List<DocFile> files = new ArrayList<>();
try (DirectoryStream<Path> 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();
--- 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;
}
}
--- /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);
+ }
+ }
+}
+