Source code

001// Copyright 2011-2013 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007// http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5.javadoc;
016
017import com.sun.source.doctree.DocTree;
018import jdk.javadoc.doclet.Doclet;
019import jdk.javadoc.doclet.DocletEnvironment;
020import jdk.javadoc.doclet.Taglet;
021import org.apache.commons.lang.StringUtils;
022import org.apache.tapestry5.commons.util.CollectionFactory;
023import org.apache.tapestry5.ioc.internal.util.InternalUtils;
024
025import javax.lang.model.element.Element;
026import javax.lang.model.element.TypeElement;
027import javax.tools.JavaFileObject;
028import javax.tools.StandardLocation;
029import java.io.File;
030import java.io.IOException;
031import java.io.StringWriter;
032import java.io.Writer;
033import java.util.List;
034import java.util.Map;
035import java.util.Set;
036
037/**
038 * An inline tag allowed inside a type; it produces Tapestry component reference and other information.
039 */
040public class TapestryDocTaglet implements Taglet, ClassDescriptionSource
041{
042    private DocletEnvironment env;
043    private Doclet doclet;
044
045    /**
046     * Map from class name to class description.
047     */
048    private final Map<String, ClassDescription> classDescriptions = CollectionFactory.newMap();
049
050    private final Set<Location> allowedLocations = CollectionFactory.newSet(Location.TYPE);
051
052    private Element firstSeen;
053
054    private static final String NAME = "tapestrydoc";
055
056    @SuppressWarnings({"unused", "unchecked"})
057    public static void register(Map paramMap)
058    {
059        paramMap.put(NAME, new TapestryDocTaglet());
060    }
061
062    @Override
063    public void init(DocletEnvironment env, Doclet doclet)
064    {
065        this.env = env;
066        this.doclet = doclet;
067    }
068
069    @Override
070    public Set<Location> getAllowedLocations()
071    {
072        return allowedLocations;
073    }
074
075    @Override
076    public boolean isInlineTag()
077    {
078        return false;
079    }
080
081    @Override
082    public String getName()
083    {
084        return NAME;
085    }
086
087    @Override
088    public String toString(List<? extends DocTree> tags, Element element)
089    {
090        if (tags.size() == 0)
091            return null;
092
093        // This should only be invoked with 0 or 1 tags. I suppose someone could put @tapestrydoc in the comment block
094        // more than once.
095
096        DocTree tag = tags.get(0);
097
098        try
099        {
100            StringWriter writer = new StringWriter(5000);
101
102            TypeElement classDoc = (TypeElement) element;
103
104            if (firstSeen == null)
105                firstSeen = classDoc;
106
107            ClassDescription cd = getDescription(classDoc.getQualifiedName().toString());
108
109            writeClassDescription(cd, writer);
110
111            streamXdoc(classDoc, writer);
112
113            return writer.toString();
114        } catch (Exception ex)
115        {
116            ex.printStackTrace(System.err);
117            System.exit(-1);
118
119            return null; // unreachable
120        }
121    }
122
123    @Override
124    public ClassDescription getDescription(String className)
125    {
126        ClassDescription result = classDescriptions.get(className);
127
128        if (result == null)
129        {
130            // System.err.printf("*** Search for CD %s ...\n", className);
131
132            TypeElement cd = env.getElementUtils().getTypeElement(className);
133
134            // System.err.printf("CD %s ... %s\n", className, cd == null ? "NOT found" : "found");
135
136            result = cd == null ? new ClassDescription(env) : new ClassDescription(cd, this, env);
137
138            classDescriptions.put(className, result);
139        }
140
141        return result;
142    }
143
144    private void writeElement(Writer writer, String elementSpec, String text) throws IOException
145    {
146        String elementName = elementSpec;
147        int idxOfSpace = elementSpec.indexOf(' ');
148        if (idxOfSpace != -1)
149        {
150            elementName = elementSpec.substring(0, idxOfSpace);
151        }
152        writer.write(String.format("<%s>%s</%s>", elementSpec,
153                InternalUtils.isBlank(text) ? "&nbsp;" : text, elementName));
154    }
155
156    private void writeClassDescription(ClassDescription cd, Writer writer) throws IOException
157    {
158        writeParameters(cd, writer);
159
160        writeEvents(cd, writer);
161    }
162
163    private void writeParameters(ClassDescription cd, Writer writer) throws IOException
164    {
165        if (cd.parameters.isEmpty())
166            return;
167
168        writer.write("</dl>"
169                + "<table class='parameters'>"
170                + "<caption><span>Component Parameters</span><span class='tabEnd'>&nbsp;</span></caption>"
171                + "<tr class='columnHeaders'>"
172                + "<th class='colFirst'>Name</th><th>Type</th><th>Flags</th><th>Default</th>"
173                + "<th class='colLast'>Default Prefix</th>"
174                + "</tr><tbody>");
175
176        int toggle = 0;
177        for (String name : InternalUtils.sortedKeys(cd.parameters))
178        {
179            ParameterDescription pd = cd.parameters.get(name);
180
181            writerParameter(pd, alternateCssClass(toggle++), writer);
182        }
183
184        writer.write("</tbody></table></dd>");
185    }
186
187    private void writerParameter(ParameterDescription pd, String rowClass, Writer writer) throws IOException
188    {
189        String description = pd.extractDescription();
190
191        writer.write("<tr class='values " + rowClass + "'>");
192        writer.write("<td" + (StringUtils.isEmpty(description) ? "" : " rowspan='2'") + " class='colFirst'>");
193        writer.write(pd.name);
194        writer.write("</td>");
195
196        writeElement(writer, "td", addWordBreaks(shortenClassName(pd.type)));
197
198        List<String> flags = CollectionFactory.newList();
199
200        if (pd.required)
201        {
202            flags.add("Required");
203        }
204
205        if (!pd.cache)
206        {
207            flags.add("Not Cached");
208        }
209
210        if (!pd.allowNull)
211        {
212            flags.add("Not Null");
213        }
214
215        if (InternalUtils.isNonBlank(pd.since)) {
216            flags.add("Since " + pd.since);
217        }
218
219        writeElement(writer, "td", InternalUtils.join(flags));
220        writeElement(writer, "td", addWordBreaks(pd.defaultValue));
221        writeElement(writer, "td class='colLast'", pd.defaultPrefix);
222
223        writer.write("</tr>");
224
225        if (StringUtils.isNotEmpty(description))
226        {
227            writer.write("<tr class='" + rowClass + "'>");
228            writer.write("<td colspan='4' class='description colLast'>");
229            writer.write(description);
230            writer.write("</td>");
231            writer.write("</tr>");
232        }
233    }
234
235    /**
236     * Return alternating CSS class names based on the input, which the caller
237     * should increment with each call.
238     */
239    private String alternateCssClass(int num) {
240        return num % 2 == 0 ? "altColor" : "rowColor";
241    }
242
243    private void writeEvents(ClassDescription cd, Writer writer) throws IOException
244    {
245        if (cd.events.isEmpty())
246            return;
247
248        writer.write("<p><table class='parameters'>"
249                + "<caption><span>Component Events</span><span class='tabEnd'>&nbsp;</span></caption>"
250                + "<tr class='columnHeaders'>"
251                + "<th class='colFirst'>Name</th><th class='colLast'>Description</th>"
252                + "</tr><tbody>");
253
254        int toggle = 0;
255        for (String name : InternalUtils.sortedKeys(cd.events))
256        {
257            writer.write("<tr class='" + alternateCssClass(toggle++) + "'>");
258            writeElement(writer, "td class='colFirst'", name);
259
260            String value = cd.events.get(name);
261
262            writeElement(writer, "td class='colLast'", value);
263
264            writer.write("</tr>");
265        }
266
267        writer.write("</table></p>");
268    }
269
270    /**
271     * Insert a <wbr/> tag after each period and colon in the given string, to
272     * allow browsers to break words at those points. (Otherwise the Parameters
273     * tables are too wide.)
274     *
275     * @param words
276     *         any string, possibly containing periods or colons
277     * @return the new string, possibly containing <wbr/> tags
278     */
279    private String addWordBreaks(String words)
280    {
281        return words.replace(".", ".<wbr/>").replace(":", ":<wbr/>");
282    }
283
284    /**
285     * Shorten the given class name by removing built-in Java packages
286     * (currently just java.lang)
287     *
288     * @param name
289     *         name of class, with package
290     * @return potentially shorter class name
291     */
292    private String shortenClassName(String name)
293    {
294        return name.replace("java.lang.", "");
295    }
296
297    private void streamXdoc(TypeElement classDoc, Writer writer) throws Exception
298    {
299        JavaFileObject sourceFileObject = env.getJavaFileManager()
300                .getJavaFileForInput(StandardLocation.SOURCE_PATH,
301                        classDoc.getQualifiedName().toString(),
302                        JavaFileObject.Kind.SOURCE);
303
304        File sourceFile;
305        if (sourceFileObject == null) {
306            final String path = "./tapestry-core/src/main/java/" + 
307                    classDoc.getQualifiedName().toString().replace('.', '/') +
308                    ".java";
309            System.err.println("[WARNING] Source file object not found for " 
310                    + classDoc.getQualifiedName().toString()
311                    + ", so we'll guess it's in " + path);
312            sourceFile = new File(path);
313        }
314        else {
315            sourceFile = new File(sourceFileObject.toUri());
316        }
317
318        // The .xdoc file will be adjacent to the sourceFile
319
320        String sourceName = sourceFile.getName();
321
322        String xdocName = sourceName.replaceAll("\\.java$", ".xdoc");
323
324        File xdocFile = new File(sourceFile.getParentFile(), xdocName);
325
326        if (xdocFile.exists())
327        {
328            try
329            {
330                // Close the definition list, to avoid unwanted indents. Very, very ugly.
331
332                new XDocStreamer(xdocFile, writer).writeContent();
333                // Open a new (empty) definition list, that HtmlDoclet will close.
334            } catch (Exception ex)
335            {
336                System.err.println("Error streaming XDOC content for " + classDoc);
337                throw ex;
338            }
339        }
340    }
341}