1/*
2 * Copyright (c) 1997, 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package com.sun.tools.javadoc.main;
27
28import java.lang.reflect.Modifier;
29import java.text.CollationKey;
30
31import com.sun.javadoc.*;
32import com.sun.source.util.TreePath;
33import com.sun.tools.javac.code.Attribute;
34import com.sun.tools.javac.code.Symbol;
35import com.sun.tools.javac.code.Symbol.ClassSymbol;
36import com.sun.tools.javac.tree.JCTree;
37import com.sun.tools.javac.tree.JCTree.JCCompilationUnit;
38import com.sun.tools.javac.util.Position;
39
40/**
41 * Represents a java program element: class, interface, field,
42 * constructor, or method.
43 * This is an abstract class dealing with information common to
44 * these elements.
45 *
46 *  <p><b>This is NOT part of any supported API.
47 *  If you write code that depends on this, you do so at your own risk.
48 *  This code and its internal interfaces are subject to change or
49 *  deletion without notice.</b>
50 *
51 * @see MemberDocImpl
52 * @see ClassDocImpl
53 *
54 * @author Robert Field
55 * @author Neal Gafter (rewrite)
56 * @author Scott Seligman (generics, enums, annotations)
57 */
58@Deprecated
59public abstract class ProgramElementDocImpl
60        extends DocImpl implements ProgramElementDoc {
61
62    private final Symbol sym;
63
64    // For source position information.
65    JCTree tree = null;
66    Position.LineMap lineMap = null;
67
68
69    // Cache for getModifiers().
70    private int modifiers = -1;
71
72    protected ProgramElementDocImpl(DocEnv env, Symbol sym, TreePath treePath) {
73        super(env, treePath);
74        this.sym = sym;
75        if (treePath != null) {
76            tree = (JCTree) treePath.getLeaf();
77            lineMap = ((JCCompilationUnit) treePath.getCompilationUnit()).lineMap;
78        }
79    }
80
81    @Override
82    void setTreePath(TreePath treePath) {
83        super.setTreePath(treePath);
84        this.tree = (JCTree) treePath.getLeaf();
85        this.lineMap = ((JCCompilationUnit) treePath.getCompilationUnit()).lineMap;
86    }
87
88    /**
89     * Subclasses override to identify the containing class
90     */
91    protected abstract ClassSymbol getContainingClass();
92
93    /**
94     * Returns the flags in terms of javac's flags
95     */
96    abstract protected long getFlags();
97
98    /**
99     * Returns the modifier flags in terms of java.lang.reflect.Modifier.
100     */
101    protected int getModifiers() {
102        if (modifiers == -1) {
103            modifiers = DocEnv.translateModifiers(getFlags());
104        }
105        return modifiers;
106    }
107
108    /**
109     * Get the containing class of this program element.
110     *
111     * @return a ClassDocImpl for this element's containing class.
112     * If this is a class with no outer class, return null.
113     */
114    public ClassDoc containingClass() {
115        if (getContainingClass() == null) {
116            return null;
117        }
118        return env.getClassDoc(getContainingClass());
119    }
120
121    /**
122     * Return the package that this member is contained in.
123     * Return "" if in unnamed package.
124     */
125    public PackageDoc containingPackage() {
126        return env.getPackageDoc(getContainingClass().packge());
127    }
128
129    /**
130     * Get the modifier specifier integer.
131     *
132     * @see java.lang.reflect.Modifier
133     */
134    public int modifierSpecifier() {
135        int modifiers = getModifiers();
136        if (isMethod() && containingClass().isInterface())
137            // Remove the implicit abstract modifier.
138            return modifiers & ~Modifier.ABSTRACT;
139        return modifiers;
140    }
141
142    /**
143     * Get modifiers string.
144     * <pre>
145     * Example, for:
146     *   public abstract int foo() { ... }
147     * modifiers() would return:
148     *   'public abstract'
149     * </pre>
150     * Annotations are not included.
151     */
152    public String modifiers() {
153        int modifiers = getModifiers();
154        if (isAnnotationTypeElement() ||
155                (isMethod() && containingClass().isInterface())) {
156            // Remove the implicit abstract modifier.
157            return Modifier.toString(modifiers & ~Modifier.ABSTRACT);
158        } else {
159            return Modifier.toString(modifiers);
160        }
161    }
162
163    /**
164     * Get the annotations of this program element.
165     * Return an empty array if there are none.
166     */
167    public AnnotationDesc[] annotations() {
168        AnnotationDesc res[] = new AnnotationDesc[sym.getRawAttributes().length()];
169        int i = 0;
170        for (Attribute.Compound a : sym.getRawAttributes()) {
171            res[i++] = new AnnotationDescImpl(env, a);
172        }
173        return res;
174    }
175
176    /**
177     * Return true if this program element is public
178     */
179    public boolean isPublic() {
180        int modifiers = getModifiers();
181        return Modifier.isPublic(modifiers);
182    }
183
184    /**
185     * Return true if this program element is protected
186     */
187    public boolean isProtected() {
188        int modifiers = getModifiers();
189        return Modifier.isProtected(modifiers);
190    }
191
192    /**
193     * Return true if this program element is private
194     */
195    public boolean isPrivate() {
196        int modifiers = getModifiers();
197        return Modifier.isPrivate(modifiers);
198    }
199
200    /**
201     * Return true if this program element is package private
202     */
203    public boolean isPackagePrivate() {
204        return !(isPublic() || isPrivate() || isProtected());
205    }
206
207    /**
208     * Return true if this program element is static
209     */
210    public boolean isStatic() {
211        int modifiers = getModifiers();
212        return Modifier.isStatic(modifiers);
213    }
214
215    /**
216     * Return true if this program element is final
217     */
218    public boolean isFinal() {
219        int modifiers = getModifiers();
220        return Modifier.isFinal(modifiers);
221    }
222
223    /**
224     * Generate a key for sorting.
225     */
226    CollationKey generateKey() {
227        String k = name();
228        // System.out.println("COLLATION KEY FOR " + this + " is \"" + k + "\"");
229        return env.doclocale.collator.getCollationKey(k);
230    }
231
232}
233