/**
* Constructor.
*
* @param filename the file to be generated.
* @throws IOException
* @throws DocletAbortException
*/
public PackageUseWriter(
ConfigurationImpl configuration, ClassUseMapper mapper, DocPath filename, PackageDoc pkgdoc)
throws IOException {
super(configuration, DocPath.forPackage(pkgdoc).resolve(filename));
this.pkgdoc = pkgdoc;
// by examining all classes in this package, find what packages
// use these classes - produce a map between using package and
// used classes.
ClassDoc[] content = pkgdoc.allClasses();
for (int i = 0; i < content.length; ++i) {
ClassDoc usedClass = content[i];
Set<ClassDoc> usingClasses = mapper.classToClass.get(usedClass.qualifiedName());
if (usingClasses != null) {
for (Iterator<ClassDoc> it = usingClasses.iterator(); it.hasNext(); ) {
ClassDoc usingClass = it.next();
PackageDoc usingPackage = usingClass.containingPackage();
Set<ClassDoc> usedClasses = usingPackageToUsedClasses.get(usingPackage.name());
if (usedClasses == null) {
usedClasses = new TreeSet<ClassDoc>();
usingPackageToUsedClasses.put(Util.getPackageName(usingPackage), usedClasses);
}
usedClasses.add(usedClass);
}
}
}
}
/**
* Add the list of classes that use the given package.
*
* @param contentTree the content tree to which the class list will be added
*/
protected void addClassList(Content contentTree) throws IOException {
String[] classTableHeader =
new String[] {
configuration.getText(
"doclet.0_and_1",
configuration.getText("doclet.Class"),
configuration.getText("doclet.Description"))
};
Iterator<String> itp = usingPackageToUsedClasses.keySet().iterator();
while (itp.hasNext()) {
String packageName = itp.next();
PackageDoc usingPackage = configuration.root.packageNamed(packageName);
HtmlTree li = new HtmlTree(HtmlTag.LI);
li.addStyle(HtmlStyle.blockList);
if (usingPackage != null) {
li.addContent(getMarkerAnchor(usingPackage.name()));
}
String tableSummary =
configuration.getText(
"doclet.Use_Table_Summary", configuration.getText("doclet.classes"));
Content table =
HtmlTree.TABLE(
HtmlStyle.useSummary,
0,
3,
0,
tableSummary,
getTableCaption(
configuration.getResource(
"doclet.ClassUse_Classes.in.0.used.by.1",
getPackageLink(pkgdoc, Util.getPackageName(pkgdoc)),
getPackageLink(usingPackage, Util.getPackageName(usingPackage)))));
table.addContent(getSummaryTableHeader(classTableHeader, "col"));
Content tbody = new HtmlTree(HtmlTag.TBODY);
Iterator<ClassDoc> itc = usingPackageToUsedClasses.get(packageName).iterator();
for (int i = 0; itc.hasNext(); i++) {
HtmlTree tr = new HtmlTree(HtmlTag.TR);
if (i % 2 == 0) {
tr.addStyle(HtmlStyle.altColor);
} else {
tr.addStyle(HtmlStyle.rowColor);
}
addClassRow(itc.next(), packageName, tr);
tbody.addContent(tr);
}
table.addContent(tbody);
li.addContent(table);
contentTree.addContent(li);
}
}
/**
* Build the package serialized form for the current package being processed.
*
* @param node the XML element that specifies which components to document
* @param serializedSummariesTree content tree to which the documentation will be added
*/
public void buildPackageSerializedForm(XMLNode node, Content serializedSummariesTree) {
Content packageSerializedTree = writer.getPackageSerializedHeader();
String foo = currentPackage.name();
ClassDoc[] classes = currentPackage.allClasses(false);
if (classes == null || classes.length == 0) {
return;
}
if (!serialInclude(currentPackage)) {
return;
}
if (!serialClassFoundToDocument(classes)) {
return;
}
buildChildren(node, packageSerializedTree);
serializedSummariesTree.addContent(packageSerializedTree);
}
/** Copy the doc files for the current ClassDoc if necessary. */
private void copyDocFiles() {
PackageDoc containingPackage = annotationTypeDoc.containingPackage();
if ((configuration.packages == null
|| Arrays.binarySearch(configuration.packages, containingPackage) < 0)
&& !containingPackagesSeen.contains(containingPackage.name())) {
// Only copy doc files dir if the containing package is not
// documented AND if we have not documented a class from the same
// package already. Otherwise, we are making duplicate copies.
Util.copyDocFiles(
configuration,
Util.getPackageSourcePath(configuration, annotationTypeDoc.containingPackage())
+ DirectoryManager.getDirectoryPath(annotationTypeDoc.containingPackage())
+ File.separator,
DocletConstants.DOC_FILES_DIR_NAME,
true);
containingPackagesSeen.add(containingPackage.name());
}
}
/**
* Add the class list that use the given class.
*
* @param contentTree the content tree to which the class list will be added
*/
protected void addClassList(Content contentTree) throws IOException {
HtmlTree ul = new HtmlTree(HtmlTag.UL);
ul.addStyle(HtmlStyle.blockList);
for (PackageDoc pkg : pkgSet) {
Content li = HtmlTree.LI(HtmlStyle.blockList, getMarkerAnchor(pkg.name()));
Content link =
getResource(
"doclet.ClassUse_Uses.of.0.in.1",
getLink(
new LinkInfoImpl(configuration, LinkInfoImpl.Kind.CLASS_USE_HEADER, classdoc)),
getPackageLink(pkg, Util.getPackageName(pkg)));
Content heading = HtmlTree.HEADING(HtmlConstants.SUMMARY_HEADING, link);
li.addContent(heading);
addClassUse(pkg, li);
ul.addContent(li);
}
Content li = HtmlTree.LI(HtmlStyle.blockList, ul);
contentTree.addContent(li);
}
/**
* Add the package annotation list.
*
* @param contentTree the content tree to which the package annotation list will be added
*/
protected void addPackageAnnotationList(Content contentTree) throws IOException {
if ((!classdoc.isAnnotationType())
|| pkgToPackageAnnotations == null
|| pkgToPackageAnnotations.isEmpty()) {
return;
}
Content table =
HtmlTree.TABLE(
HtmlStyle.useSummary,
0,
3,
0,
useTableSummary,
getTableCaption(
configuration.getResource(
"doclet.ClassUse_PackageAnnotation",
getLink(
new LinkInfoImpl(
configuration, LinkInfoImpl.Kind.CLASS_USE_HEADER, classdoc)))));
table.addContent(getSummaryTableHeader(packageTableHeader, "col"));
Content tbody = new HtmlTree(HtmlTag.TBODY);
Iterator<PackageDoc> it = pkgToPackageAnnotations.iterator();
for (int i = 0; it.hasNext(); i++) {
PackageDoc pkg = it.next();
HtmlTree tr = new HtmlTree(HtmlTag.TR);
if (i % 2 == 0) {
tr.addStyle(HtmlStyle.altColor);
} else {
tr.addStyle(HtmlStyle.rowColor);
}
Content tdFirst =
HtmlTree.TD(HtmlStyle.colFirst, getPackageLink(pkg, new StringContent(pkg.name())));
tr.addContent(tdFirst);
HtmlTree tdLast = new HtmlTree(HtmlTag.TD);
tdLast.addStyle(HtmlStyle.colLast);
addSummaryComment(pkg, tdLast);
tr.addContent(tdLast);
tbody.addContent(tr);
}
table.addContent(tbody);
Content li = HtmlTree.LI(HtmlStyle.blockList, table);
contentTree.addContent(li);
}
private Map<String, List<ProgramElementDoc>> pkgDivide(
Map<String, ? extends List<? extends ProgramElementDoc>> classMap) {
Map<String, List<ProgramElementDoc>> map = new HashMap<>();
List<? extends ProgramElementDoc> list = classMap.get(classdoc.qualifiedName());
if (list != null) {
Collections.sort(list);
for (ProgramElementDoc doc : list) {
PackageDoc pkg = doc.containingPackage();
pkgSet.add(pkg);
List<ProgramElementDoc> inPkg = map.get(pkg.name());
if (inPkg == null) {
inPkg = new ArrayList<>();
map.put(pkg.name(), inPkg);
}
inPkg.add(doc);
}
}
return map;
}
/**
* Add the package use information.
*
* @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(PackageDoc pkg, Content contentTree) throws IOException {
Content tdFirst =
HtmlTree.TD(
HtmlStyle.colFirst,
getHyperLink(pkg.name(), new StringContent(Util.getPackageName(pkg))));
contentTree.addContent(tdFirst);
HtmlTree tdLast = new HtmlTree(HtmlTag.TD);
tdLast.addStyle(HtmlStyle.colLast);
addSummaryComment(pkg, tdLast);
contentTree.addContent(tdLast);
}
/**
* Convert the Classes in the given Package to an HTML.
*
* @param pd the Package to convert.
* @param outputdir the name of the directory to output to.
*/
public void convertPackage(PackageDoc pd, DocPath outputdir) {
if (pd == null) {
return;
}
for (ClassDoc cd : pd.allClasses()) {
// If -nodeprecated option is set and the class is marked as deprecated,
// do not convert the package files to HTML. We do not check for
// containing package deprecation since it is already check in
// the calling method above.
if (!(configuration.nodeprecated && utils.isDeprecated(cd))) convertClass(cd, outputdir);
}
}
/** Generate the package use list. */
protected void generatePackageUseFile() throws IOException {
Content body = getPackageUseHeader();
HtmlTree div = new HtmlTree(HtmlTag.DIV);
div.addStyle(HtmlStyle.contentContainer);
if (usingPackageToUsedClasses.isEmpty()) {
div.addContent(getResource("doclet.ClassUse_No.usage.of.0", pkgdoc.name()));
} else {
addPackageUse(div);
}
body.addContent(div);
addNavLinks(false, body);
addBottom(body);
printHtmlDocument(null, true, body);
}
/**
* Add the package use information.
*
* @param pkg the package that used the given package
* @param contentTree the content tree to which the information will be added
*/
protected void addPackageUse(PackageDoc pkg, Content contentTree) throws IOException {
Content tdFirst =
HtmlTree.TD(
HtmlStyle.colFirst,
getHyperLink(Util.getPackageName(pkg), new StringContent(Util.getPackageName(pkg))));
contentTree.addContent(tdFirst);
HtmlTree tdLast = new HtmlTree(HtmlTag.TD);
tdLast.addStyle(HtmlStyle.colLast);
if (pkg != null && pkg.name().length() != 0) {
addSummaryComment(pkg, tdLast);
} else {
tdLast.addContent(getSpace());
}
contentTree.addContent(tdLast);
}
/**
* Get the header for the package use listing.
*
* @return a content tree representing the package use header
*/
protected Content getPackageUseHeader() {
String packageText = configuration.getText("doclet.Package");
String name = pkgdoc.name();
String title = configuration.getText("doclet.Window_ClassUse_Header", packageText, name);
Content bodyTree = getBody(true, getWindowTitle(title));
addTop(bodyTree);
addNavLinks(true, bodyTree);
ContentBuilder headContent = new ContentBuilder();
headContent.addContent(getResource("doclet.ClassUse_Title", packageText));
headContent.addContent(new HtmlTree(HtmlTag.BR));
headContent.addContent(name);
Content heading =
HtmlTree.HEADING(HtmlConstants.TITLE_HEADING, true, HtmlStyle.title, headContent);
Content div = HtmlTree.DIV(HtmlStyle.header, heading);
bodyTree.addContent(div);
return bodyTree;
}
/**
* Build the class serialized form.
*
* @param node the XML element that specifies which components to document
* @param packageSerializedTree content tree to which the documentation will be added
*/
public void buildClassSerializedForm(XMLNode node, Content packageSerializedTree) {
Content classSerializedTree = writer.getClassSerializedHeader();
ClassDoc[] classes = currentPackage.allClasses(false);
Arrays.sort(classes);
for (int j = 0; j < classes.length; j++) {
currentClass = classes[j];
fieldWriter = writer.getSerialFieldWriter(currentClass);
methodWriter = writer.getSerialMethodWriter(currentClass);
if (currentClass.isClass() && currentClass.isSerializable()) {
if (!serialClassInclude(currentClass)) {
continue;
}
Content classTree = writer.getClassHeader(currentClass);
buildChildren(node, classTree);
classSerializedTree.addContent(classTree);
}
}
packageSerializedTree.addContent(classSerializedTree);
}
/**
* Given a package, return it's file name without the extension.
*
* @param packageDoc the package to check.
* @return the file name of the given package.
*/
public static String getPackageFileHeadName(PackageDoc packageDoc) {
return packageDoc == null || packageDoc.name().length() == 0
? DocletConstants.DEFAULT_PACKAGE_FILE_NAME
: packageDoc.name();
}
/**
* Add the class use information.
*
* @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(PackageDoc pkg, Content contentTree) throws IOException {
Content classLink =
getLink(new LinkInfoImpl(configuration, LinkInfoImpl.Kind.CLASS_USE_HEADER, classdoc));
Content pkgLink = getPackageLink(pkg, Util.getPackageName(pkg));
classSubWriter.addUseInfo(
pkgToClassAnnotations.get(pkg.name()),
configuration.getResource("doclet.ClassUse_Annotation", classLink, pkgLink),
classUseTableSummary,
contentTree);
classSubWriter.addUseInfo(
pkgToClassTypeParameter.get(pkg.name()),
configuration.getResource("doclet.ClassUse_TypeParameter", classLink, pkgLink),
classUseTableSummary,
contentTree);
classSubWriter.addUseInfo(
pkgToSubclass.get(pkg.name()),
configuration.getResource("doclet.ClassUse_Subclass", classLink, pkgLink),
subclassUseTableSummary,
contentTree);
classSubWriter.addUseInfo(
pkgToSubinterface.get(pkg.name()),
configuration.getResource("doclet.ClassUse_Subinterface", classLink, pkgLink),
subinterfaceUseTableSummary,
contentTree);
classSubWriter.addUseInfo(
pkgToImplementingClass.get(pkg.name()),
configuration.getResource("doclet.ClassUse_ImplementingClass", classLink, pkgLink),
classUseTableSummary,
contentTree);
fieldSubWriter.addUseInfo(
pkgToField.get(pkg.name()),
configuration.getResource("doclet.ClassUse_Field", classLink, pkgLink),
fieldUseTableSummary,
contentTree);
fieldSubWriter.addUseInfo(
pkgToFieldAnnotations.get(pkg.name()),
configuration.getResource("doclet.ClassUse_FieldAnnotations", classLink, pkgLink),
fieldUseTableSummary,
contentTree);
fieldSubWriter.addUseInfo(
pkgToFieldTypeParameter.get(pkg.name()),
configuration.getResource("doclet.ClassUse_FieldTypeParameter", classLink, pkgLink),
fieldUseTableSummary,
contentTree);
methodSubWriter.addUseInfo(
pkgToMethodAnnotations.get(pkg.name()),
configuration.getResource("doclet.ClassUse_MethodAnnotations", classLink, pkgLink),
methodUseTableSummary,
contentTree);
methodSubWriter.addUseInfo(
pkgToMethodParameterAnnotations.get(pkg.name()),
configuration.getResource("doclet.ClassUse_MethodParameterAnnotations", classLink, pkgLink),
methodUseTableSummary,
contentTree);
methodSubWriter.addUseInfo(
pkgToMethodTypeParameter.get(pkg.name()),
configuration.getResource("doclet.ClassUse_MethodTypeParameter", classLink, pkgLink),
methodUseTableSummary,
contentTree);
methodSubWriter.addUseInfo(
pkgToMethodReturn.get(pkg.name()),
configuration.getResource("doclet.ClassUse_MethodReturn", classLink, pkgLink),
methodUseTableSummary,
contentTree);
methodSubWriter.addUseInfo(
pkgToMethodReturnTypeParameter.get(pkg.name()),
configuration.getResource("doclet.ClassUse_MethodReturnTypeParameter", classLink, pkgLink),
methodUseTableSummary,
contentTree);
methodSubWriter.addUseInfo(
pkgToMethodArgs.get(pkg.name()),
configuration.getResource("doclet.ClassUse_MethodArgs", classLink, pkgLink),
methodUseTableSummary,
contentTree);
methodSubWriter.addUseInfo(
pkgToMethodArgTypeParameter.get(pkg.name()),
configuration.getResource("doclet.ClassUse_MethodArgsTypeParameters", classLink, pkgLink),
methodUseTableSummary,
contentTree);
methodSubWriter.addUseInfo(
pkgToMethodThrows.get(pkg.name()),
configuration.getResource("doclet.ClassUse_MethodThrows", classLink, pkgLink),
methodUseTableSummary,
contentTree);
constrSubWriter.addUseInfo(
pkgToConstructorAnnotations.get(pkg.name()),
configuration.getResource("doclet.ClassUse_ConstructorAnnotations", classLink, pkgLink),
constructorUseTableSummary,
contentTree);
constrSubWriter.addUseInfo(
pkgToConstructorParameterAnnotations.get(pkg.name()),
configuration.getResource(
"doclet.ClassUse_ConstructorParameterAnnotations", classLink, pkgLink),
constructorUseTableSummary,
contentTree);
constrSubWriter.addUseInfo(
pkgToConstructorArgs.get(pkg.name()),
configuration.getResource("doclet.ClassUse_ConstructorArgs", classLink, pkgLink),
constructorUseTableSummary,
contentTree);
constrSubWriter.addUseInfo(
pkgToConstructorArgTypeParameter.get(pkg.name()),
configuration.getResource(
"doclet.ClassUse_ConstructorArgsTypeParameters", classLink, pkgLink),
constructorUseTableSummary,
contentTree);
constrSubWriter.addUseInfo(
pkgToConstructorThrows.get(pkg.name()),
configuration.getResource("doclet.ClassUse_ConstructorThrows", classLink, pkgLink),
constructorUseTableSummary,
contentTree);
}