KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > ui > JavadocContentAccess


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.jdt.ui;
12  
13 import java.io.IOException JavaDoc;
14 import java.io.Reader JavaDoc;
15 import java.io.StringReader JavaDoc;
16
17 import org.eclipse.jdt.core.IBuffer;
18 import org.eclipse.jdt.core.IJavaElement;
19 import org.eclipse.jdt.core.IMember;
20 import org.eclipse.jdt.core.IMethod;
21 import org.eclipse.jdt.core.ISourceRange;
22 import org.eclipse.jdt.core.IType;
23 import org.eclipse.jdt.core.ITypeHierarchy;
24 import org.eclipse.jdt.core.JavaModelException;
25
26 import org.eclipse.jdt.internal.corext.javadoc.JavaDocCommentReader;
27 import org.eclipse.jdt.internal.corext.util.MethodOverrideTester;
28
29 import org.eclipse.jdt.internal.ui.text.javadoc.JavaDoc2HTMLTextReader;
30
31 /**
32  * Helper needed to get the content of a Javadoc comment.
33  *
34  * <p>
35  * This class is not intended to be subclassed or instantiated by clients.
36  * </p>
37  *
38  * @since 3.1
39  */
40 public class JavadocContentAccess {
41     
42     private JavadocContentAccess() {
43         // do not instantiate
44 }
45     
46     /**
47      * Gets a reader for an IMember's Javadoc comment content from the source attachment.
48      * The content does contain only the text from the comment without the Javadoc leading star characters.
49      * Returns <code>null</code> if the member does not contain a Javadoc comment or if no source is available.
50      * @param member The member to get the Javadoc of.
51      * @param allowInherited For methods with no (Javadoc) comment, the comment of the overridden class
52      * is returned if <code>allowInherited</code> is <code>true</code>.
53      * @return Returns a reader for the Javadoc comment content or <code>null</code> if the member
54      * does not contain a Javadoc comment or if no source is available
55      * @throws JavaModelException is thrown when the elements javadoc can not be accessed
56      */
57     public static Reader JavaDoc getContentReader(IMember member, boolean allowInherited) throws JavaModelException {
58         IBuffer buf= member.getOpenable().getBuffer();
59         if (buf == null) {
60             return null; // no source attachment found
61 }
62         
63         ISourceRange javadocRange= member.getJavadocRange();
64         if (javadocRange != null) {
65             JavaDocCommentReader reader= new JavaDocCommentReader(buf, javadocRange.getOffset(), javadocRange.getOffset() + javadocRange.getLength() - 1);
66             if (!containsOnlyInheritDoc(reader, javadocRange.getLength())) {
67                 reader.reset();
68                 return reader;
69             }
70         }
71
72         if (allowInherited && (member.getElementType() == IJavaElement.METHOD)) {
73             return findDocInHierarchy((IMethod) member);
74         }
75         
76         return null;
77     }
78
79     /**
80      * Checks whether the given reader only returns
81      * the inheritDoc tag.
82      *
83      * @param reader the reader
84      * @param length the length of the underlying content
85      * @return <code>true</code> if the reader only returns the inheritDoc tag
86      * @since 3.2
87      */
88     private static boolean containsOnlyInheritDoc(Reader JavaDoc reader, int length) {
89         char[] content= new char[length];
90         try {
91             reader.read(content, 0, length);
92         } catch (IOException JavaDoc e) {
93             return false;
94         }
95         return new String JavaDoc(content).trim().equals("{@inheritDoc}"); //$NON-NLS-1$
96
97     }
98
99     /**
100      * Gets a reader for an IMember's Javadoc comment content from the source attachment.
101      * and renders the tags in HTML.
102      * Returns <code>null</code> if the member does not contain a Javadoc comment or if no source is available.
103      *
104      * @param member the member to get the Javadoc of.
105      * @param allowInherited for methods with no (Javadoc) comment, the comment of the overridden
106      * class is returned if <code>allowInherited</code> is <code>true</code>
107      * @param useAttachedJavadoc if <code>true</code> Javadoc will be extracted from attached Javadoc
108      * if there's no source
109      * @return a reader for the Javadoc comment content in HTML or <code>null</code> if the member
110      * does not contain a Javadoc comment or if no source is available
111      * @throws JavaModelException is thrown when the elements Javadoc can not be accessed
112      * @since 3.2
113      */
114     public static Reader JavaDoc getHTMLContentReader(IMember member, boolean allowInherited, boolean useAttachedJavadoc) throws JavaModelException {
115         Reader JavaDoc contentReader= getContentReader(member, allowInherited);
116         if (contentReader != null)
117             return new JavaDoc2HTMLTextReader(contentReader);
118         
119         if (useAttachedJavadoc && member.getOpenable().getBuffer() == null) { // only if no source available
120 String JavaDoc s= member.getAttachedJavadoc(null);
121             if (s != null)
122                 return new StringReader JavaDoc(s);
123         }
124         return null;
125     }
126     
127     
128
129     /**
130      * Gets a reader for an IMember's Javadoc comment content from the source attachment.
131      * and renders the tags in HTML.
132      * Returns <code>null</code> if the member does not contain a Javadoc comment or if no source is available.
133      *
134      * @param member The member to get the Javadoc of.
135      * @param allowInherited For methods with no (Javadoc) comment, the comment of the overridden class
136      * is returned if <code>allowInherited</code> is <code>true</code>.
137      * @return Returns a reader for the Javadoc comment content in HTML or <code>null</code> if the member
138      * does not contain a Javadoc comment or if no source is available
139      * @throws JavaModelException is thrown when the elements javadoc can not be accessed
140      * @deprecated As of 3.2, replaced by {@link #getHTMLContentReader(IMember, boolean, boolean)}
141      */
142     public static Reader JavaDoc getHTMLContentReader(IMember member, boolean allowInherited) throws JavaModelException {
143         return getHTMLContentReader(member, allowInherited, false);
144     }
145
146     private static Reader JavaDoc findDocInHierarchy(IMethod method) throws JavaModelException {
147         IType type= method.getDeclaringType();
148         ITypeHierarchy hierarchy= type.newSupertypeHierarchy(null);
149         
150         MethodOverrideTester tester= new MethodOverrideTester(type, hierarchy);
151         
152         IType[] superTypes= hierarchy.getAllSupertypes(type);
153         for (int i= 0; i < superTypes.length; i++) {
154             IType curr= superTypes[i];
155             IMethod overridden= tester.findOverriddenMethodInType(curr, method);
156             if (overridden != null) {
157                 Reader JavaDoc reader= getContentReader(overridden, false);
158                 if (reader != null) {
159                     return reader;
160                 }
161             }
162         }
163         return null;
164     }
165
166 }
167
Popular Tags