60 * <p><b>This is NOT part of any supported API.
61 * If you write code that depends on this, you do so at your own risk.
62 * This code and its internal interfaces are subject to change or
63 * deletion without notice.</b>
64 */
65 public class SourceToHTMLConverter {
66
67 /**
68 * The number of trailing blank lines at the end of the page.
69 * This is inserted so that anchors at the bottom of small pages
70 * can be reached.
71 */
72 private static final int NUM_BLANK_LINES = 60;
73
74 /**
75 * New line to be added to the documentation.
76 */
77 private static final String NEW_LINE = DocletConstants.NL;
78
79 private final HtmlConfiguration configuration;
80 private final Messages messages;
81 private final Resources resources;
82 private final Utils utils;
83
84 private final DocletEnvironment docEnv;
85
86 private final DocPath outputdir;
87
88 /**
89 * Relative path from the documentation root to the file that is being
90 * generated.
91 */
92 private DocPath relativePath = DocPath.empty;
93
94 private SourceToHTMLConverter(HtmlConfiguration configuration, DocletEnvironment rd,
95 DocPath outputdir) {
96 this.configuration = configuration;
97 this.messages = configuration.getMessages();
98 this.resources = configuration.resources;
99 this.utils = configuration.utils;
100 this.docEnv = rd;
101 this.outputdir = outputdir;
102 }
103
104 /**
105 * Translate the TypeElements in the given DocletEnvironment to HTML representation.
106 *
107 * @param configuration the configuration.
108 * @param docEnv the DocletEnvironment to convert.
109 * @param outputdir the name of the directory to output to.
110 * @throws DocFileIOException if there is a problem generating an output file
111 * @throws SimpleDocletException if there is a problem reading a source file
112 */
113 public static void convertRoot(HtmlConfiguration configuration, DocletEnvironment docEnv,
114 DocPath outputdir) throws DocFileIOException, SimpleDocletException {
115 new SourceToHTMLConverter(configuration, docEnv, outputdir).generate();
116 }
117
118 void generate() throws DocFileIOException, SimpleDocletException {
119 if (docEnv == null || outputdir == null) {
120 return;
121 }
122 for (ModuleElement mdl : configuration.getSpecifiedModuleElements()) {
123 // If -nodeprecated option is set and the module is marked as deprecated,
124 // do not convert the module files to HTML.
125 if (!(configuration.nodeprecated && utils.isDeprecated(mdl)))
126 convertModule(mdl, outputdir);
127 }
128 for (PackageElement pkg : configuration.getSpecifiedPackageElements()) {
129 // If -nodeprecated option is set and the package is marked as deprecated,
130 // do not convert the package files to HTML.
131 if (!(configuration.nodeprecated && utils.isDeprecated(pkg)))
132 convertPackage(pkg, outputdir);
133 }
134 for (TypeElement te : configuration.getSpecifiedTypeElements()) {
135 // If -nodeprecated option is set and the class is marked as deprecated
136 // or the containing package is deprecated, do not convert the
137 // package files to HTML.
138 if (!(configuration.nodeprecated &&
139 (utils.isDeprecated(te) || utils.isDeprecated(utils.containingPackage(te)))))
140 convertClass(te, outputdir);
141 }
142 }
143
144 /**
145 * Convert the Classes in the given Package to an HTML file.
146 *
147 * @param pkg the Package to convert.
148 * @param outputdir the name of the directory to output to.
149 * @throws DocFileIOException if there is a problem generating an output file
150 * @throws SimpleDocletException if there is a problem reading a source file
151 */
152 public void convertPackage(PackageElement pkg, DocPath outputdir)
153 throws DocFileIOException, SimpleDocletException {
154 if (pkg == null) {
155 return;
156 }
157 for (Element te : utils.getAllClasses(pkg)) {
158 // If -nodeprecated option is set and the class is marked as deprecated,
159 // do not convert the package files to HTML. We do not check for
160 // containing package deprecation since it is already check in
161 // the calling method above.
162 if (!(configuration.nodeprecated && utils.isDeprecated(te)))
163 convertClass((TypeElement)te, outputdir);
164 }
165 }
166
167 /**
168 * Convert the documented packages contained in the given module to an HTML representation.
169 *
170 * @param mdl the module to convert.
171 * @param outputdir the name of the directory to output to.
172 * @throws DocFileIOException if there is a problem generating an output file
173 * @throws SimpleDocletException if there is a problem reading a source file
174 */
175 public void convertModule(ModuleElement mdl, DocPath outputdir)
176 throws DocFileIOException, SimpleDocletException {
177 if (mdl == null) {
178 return;
179 }
180 for (Element elem : mdl.getEnclosedElements()) {
181 if (elem instanceof PackageElement && configuration.docEnv.isIncluded(elem)
182 && !(configuration.nodeprecated && utils.isDeprecated(elem))) {
183 convertPackage((PackageElement) elem, outputdir);
184 }
185 }
186 }
187
188 /**
189 * Convert the given Class to an HTML.
190 *
191 * @param te the class to convert.
192 * @param outputdir the name of the directory to output to
193 * @throws DocFileIOException if there is a problem generating the output file
194 * @throws SimpleDocletException if there is a problem reading the source file
195 */
196 public void convertClass(TypeElement te, DocPath outputdir)
197 throws DocFileIOException, SimpleDocletException {
198 if (te == null) {
199 return;
200 }
201 FileObject fo = utils.getFileObject(te);
202 if (fo == null)
219 }
220 }
221 addBlankLines(pre);
222 Content div = HtmlTree.DIV(HtmlStyle.sourceContainer, pre);
223 body.add(HtmlTree.MAIN(div));
224 writeToFile(body, outputdir.resolve(configuration.docPaths.forClass(te)), te);
225 } catch (IOException e) {
226 String message = resources.getText("doclet.exception.read.file", fo.getName());
227 throw new SimpleDocletException(message, e);
228 }
229 }
230
231 /**
232 * Write the output to the file.
233 *
234 * @param body the documentation content to be written to the file.
235 * @param path the path for the file.
236 */
237 private void writeToFile(Content body, DocPath path, TypeElement te) throws DocFileIOException {
238 Head head = new Head(path, configuration.docletVersion, configuration.startTime)
239 // .setTimestamp(!configuration.notimestamp) // temporary: compatibility!
240 .setTitle(resources.getText("doclet.Window_Source_title"))
241 // .setCharset(configuration.charset) // temporary: compatibility!
242 .setDescription(HtmlDocletWriter.getDescription("source", te))
243 .setGenerator(HtmlDocletWriter.getGenerator(getClass()))
244 .addDefaultScript(false)
245 .setStylesheets(configuration.getMainStylesheet(), configuration.getAdditionalStylesheets());
246 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
247 head.toContent(), body);
248 HtmlDocument htmlDocument = new HtmlDocument(htmlTree);
249 messages.notice("doclet.Generating_0", path.getPath());
250 htmlDocument.write(DocFile.createFileForOutput(configuration, path));
251 }
252
253 /**
254 * Returns a link to the stylesheet file.
255 *
256 * @param head an HtmlTree to which the stylesheet links will be added
257 */
258 public void addStyleSheetProperties(Content head) {
259 String filename = configuration.stylesheetfile;
260 DocPath stylesheet;
261 if (filename.length() > 0) {
262 DocFile file = DocFile.createFileForInput(configuration, filename);
263 stylesheet = DocPath.create(file.getName());
264 } else {
265 stylesheet = DocPaths.STYLESHEET;
266 }
267 DocPath p = relativePath.resolve(stylesheet);
268 HtmlTree link = HtmlTree.LINK("stylesheet", "text/css", p.getPath(), "Style");
269 head.add(link);
270 addStylesheets(head);
271 }
272
273 protected void addStylesheets(Content tree) {
274 List<String> stylesheets = configuration.additionalStylesheets;
275 if (!stylesheets.isEmpty()) {
276 stylesheets.forEach((ssheet) -> {
277 DocFile file = DocFile.createFileForInput(configuration, ssheet);
278 DocPath ssheetPath = DocPath.create(file.getName());
279 HtmlTree slink = HtmlTree.LINK("stylesheet", "text/css", relativePath.resolve(ssheetPath).getPath(),
280 "Style");
281 tree.add(slink);
282 });
283 }
284 }
285
286 /**
287 * Get the header.
288 *
289 * @return the header content for the HTML file
290 */
291 private static Content getHeader() {
292 return new HtmlTree(HtmlTag.BODY).put(HtmlAttr.CLASS, "source");
293 }
294
|
60 * <p><b>This is NOT part of any supported API.
61 * If you write code that depends on this, you do so at your own risk.
62 * This code and its internal interfaces are subject to change or
63 * deletion without notice.</b>
64 */
65 public class SourceToHTMLConverter {
66
67 /**
68 * The number of trailing blank lines at the end of the page.
69 * This is inserted so that anchors at the bottom of small pages
70 * can be reached.
71 */
72 private static final int NUM_BLANK_LINES = 60;
73
74 /**
75 * New line to be added to the documentation.
76 */
77 private static final String NEW_LINE = DocletConstants.NL;
78
79 private final HtmlConfiguration configuration;
80 private final HtmlOptions options;
81 private final Messages messages;
82 private final Resources resources;
83 private final Utils utils;
84
85 private final DocletEnvironment docEnv;
86
87 private final DocPath outputdir;
88
89 /**
90 * Relative path from the documentation root to the file that is being
91 * generated.
92 */
93 private DocPath relativePath = DocPath.empty;
94
95 private SourceToHTMLConverter(HtmlConfiguration configuration, DocletEnvironment rd,
96 DocPath outputdir) {
97 this.configuration = configuration;
98 this.options = configuration.getOptions();
99 this.messages = configuration.getMessages();
100 this.resources = configuration.resources;
101 this.utils = configuration.utils;
102 this.docEnv = rd;
103 this.outputdir = outputdir;
104 }
105
106 /**
107 * Translate the TypeElements in the given DocletEnvironment to HTML representation.
108 *
109 * @param configuration the configuration.
110 * @param docEnv the DocletEnvironment to convert.
111 * @param outputdir the name of the directory to output to.
112 * @throws DocFileIOException if there is a problem generating an output file
113 * @throws SimpleDocletException if there is a problem reading a source file
114 */
115 public static void convertRoot(HtmlConfiguration configuration, DocletEnvironment docEnv,
116 DocPath outputdir) throws DocFileIOException, SimpleDocletException {
117 new SourceToHTMLConverter(configuration, docEnv, outputdir).generate();
118 }
119
120 void generate() throws DocFileIOException, SimpleDocletException {
121 if (docEnv == null || outputdir == null) {
122 return;
123 }
124 for (ModuleElement mdl : configuration.getSpecifiedModuleElements()) {
125 // If -nodeprecated option is set and the module is marked as deprecated,
126 // do not convert the module files to HTML.
127 if (!(options.noDeprecated && utils.isDeprecated(mdl)))
128 convertModule(mdl, outputdir);
129 }
130 for (PackageElement pkg : configuration.getSpecifiedPackageElements()) {
131 // If -nodeprecated option is set and the package is marked as deprecated,
132 // do not convert the package files to HTML.
133 if (!(options.noDeprecated && utils.isDeprecated(pkg)))
134 convertPackage(pkg, outputdir);
135 }
136 for (TypeElement te : configuration.getSpecifiedTypeElements()) {
137 // If -nodeprecated option is set and the class is marked as deprecated
138 // or the containing package is deprecated, do not convert the
139 // package files to HTML.
140 if (!(options.noDeprecated &&
141 (utils.isDeprecated(te) || utils.isDeprecated(utils.containingPackage(te)))))
142 convertClass(te, outputdir);
143 }
144 }
145
146 /**
147 * Convert the Classes in the given Package to an HTML file.
148 *
149 * @param pkg the Package to convert.
150 * @param outputdir the name of the directory to output to.
151 * @throws DocFileIOException if there is a problem generating an output file
152 * @throws SimpleDocletException if there is a problem reading a source file
153 */
154 public void convertPackage(PackageElement pkg, DocPath outputdir)
155 throws DocFileIOException, SimpleDocletException {
156 if (pkg == null) {
157 return;
158 }
159 for (Element te : utils.getAllClasses(pkg)) {
160 // If -nodeprecated option is set and the class is marked as deprecated,
161 // do not convert the package files to HTML. We do not check for
162 // containing package deprecation since it is already check in
163 // the calling method above.
164 if (!(options.noDeprecated && utils.isDeprecated(te)))
165 convertClass((TypeElement)te, outputdir);
166 }
167 }
168
169 /**
170 * Convert the documented packages contained in the given module to an HTML representation.
171 *
172 * @param mdl the module to convert.
173 * @param outputdir the name of the directory to output to.
174 * @throws DocFileIOException if there is a problem generating an output file
175 * @throws SimpleDocletException if there is a problem reading a source file
176 */
177 public void convertModule(ModuleElement mdl, DocPath outputdir)
178 throws DocFileIOException, SimpleDocletException {
179 if (mdl == null) {
180 return;
181 }
182 for (Element elem : mdl.getEnclosedElements()) {
183 if (elem instanceof PackageElement && configuration.docEnv.isIncluded(elem)
184 && !(options.noDeprecated && utils.isDeprecated(elem))) {
185 convertPackage((PackageElement) elem, outputdir);
186 }
187 }
188 }
189
190 /**
191 * Convert the given Class to an HTML.
192 *
193 * @param te the class to convert.
194 * @param outputdir the name of the directory to output to
195 * @throws DocFileIOException if there is a problem generating the output file
196 * @throws SimpleDocletException if there is a problem reading the source file
197 */
198 public void convertClass(TypeElement te, DocPath outputdir)
199 throws DocFileIOException, SimpleDocletException {
200 if (te == null) {
201 return;
202 }
203 FileObject fo = utils.getFileObject(te);
204 if (fo == null)
221 }
222 }
223 addBlankLines(pre);
224 Content div = HtmlTree.DIV(HtmlStyle.sourceContainer, pre);
225 body.add(HtmlTree.MAIN(div));
226 writeToFile(body, outputdir.resolve(configuration.docPaths.forClass(te)), te);
227 } catch (IOException e) {
228 String message = resources.getText("doclet.exception.read.file", fo.getName());
229 throw new SimpleDocletException(message, e);
230 }
231 }
232
233 /**
234 * Write the output to the file.
235 *
236 * @param body the documentation content to be written to the file.
237 * @param path the path for the file.
238 */
239 private void writeToFile(Content body, DocPath path, TypeElement te) throws DocFileIOException {
240 Head head = new Head(path, configuration.docletVersion, configuration.startTime)
241 // .setTimestamp(!options.notimestamp) // temporary: compatibility!
242 .setTitle(resources.getText("doclet.Window_Source_title"))
243 // .setCharset(options.charset) // temporary: compatibility!
244 .setDescription(HtmlDocletWriter.getDescription("source", te))
245 .setGenerator(HtmlDocletWriter.getGenerator(getClass()))
246 .addDefaultScript(false)
247 .setStylesheets(configuration.getMainStylesheet(), configuration.getAdditionalStylesheets());
248 Content htmlTree = HtmlTree.HTML(configuration.getLocale().getLanguage(),
249 head.toContent(), body);
250 HtmlDocument htmlDocument = new HtmlDocument(htmlTree);
251 messages.notice("doclet.Generating_0", path.getPath());
252 htmlDocument.write(DocFile.createFileForOutput(configuration, path));
253 }
254
255 /**
256 * Returns a link to the stylesheet file.
257 *
258 * @param head an HtmlTree to which the stylesheet links will be added
259 */
260 public void addStyleSheetProperties(Content head) {
261 String filename = options.stylesheetFile;
262 DocPath stylesheet;
263 if (filename.length() > 0) {
264 DocFile file = DocFile.createFileForInput(configuration, filename);
265 stylesheet = DocPath.create(file.getName());
266 } else {
267 stylesheet = DocPaths.STYLESHEET;
268 }
269 DocPath p = relativePath.resolve(stylesheet);
270 HtmlTree link = HtmlTree.LINK("stylesheet", "text/css", p.getPath(), "Style");
271 head.add(link);
272 addStylesheets(head);
273 }
274
275 protected void addStylesheets(Content tree) {
276 List<String> stylesheets = options.additionalStylesheets;
277 if (!stylesheets.isEmpty()) {
278 stylesheets.forEach((ssheet) -> {
279 DocFile file = DocFile.createFileForInput(configuration, ssheet);
280 DocPath ssheetPath = DocPath.create(file.getName());
281 HtmlTree slink = HtmlTree.LINK("stylesheet", "text/css", relativePath.resolve(ssheetPath).getPath(),
282 "Style");
283 tree.add(slink);
284 });
285 }
286 }
287
288 /**
289 * Get the header.
290 *
291 * @return the header content for the HTML file
292 */
293 private static Content getHeader() {
294 return new HtmlTree(HtmlTag.BODY).put(HtmlAttr.CLASS, "source");
295 }
296
|