1/*
2 * Copyright (c) 1997, 2013, 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 com.sun.source.util.TreePath;
29import java.lang.reflect.Modifier;
30
31import com.sun.javadoc.*;
32
33import com.sun.tools.javac.code.Flags;
34import com.sun.tools.javac.code.Symbol.ClassSymbol;
35import com.sun.tools.javac.code.Symbol.VarSymbol;
36
37import static com.sun.tools.javac.code.TypeTag.BOOLEAN;
38
39/**
40 * Represents a field in a java class.
41 *
42 *  <p><b>This is NOT part of any supported API.
43 *  If you write code that depends on this, you do so at your own risk.
44 *  This code and its internal interfaces are subject to change or
45 *  deletion without notice.</b>
46 *
47 * @see MemberDocImpl
48 *
49 * @since 1.2
50 * @author Robert Field
51 * @author Neal Gafter (rewrite)
52 * @author Scott Seligman (generics, enums, annotations)
53 */
54@Deprecated
55public class FieldDocImpl extends MemberDocImpl implements FieldDoc {
56
57    protected final VarSymbol sym;
58
59    /**
60     * Constructor.
61     */
62    public FieldDocImpl(DocEnv env, VarSymbol sym, TreePath treePath) {
63        super(env, sym, treePath);
64        this.sym = sym;
65    }
66
67    /**
68     * Constructor.
69     */
70    public FieldDocImpl(DocEnv env, VarSymbol sym) {
71        this(env, sym, null);
72    }
73
74    /**
75     * Returns the flags in terms of javac's flags
76     */
77    protected long getFlags() {
78        return sym.flags();
79    }
80
81    /**
82     * Identify the containing class
83     */
84    protected ClassSymbol getContainingClass() {
85        return sym.enclClass();
86    }
87
88    /**
89     * Get type of this field.
90     */
91    public com.sun.javadoc.Type type() {
92        return TypeMaker.getType(env, sym.type, false);
93    }
94
95    /**
96     * Get the value of a constant field.
97     *
98     * @return the value of a constant field. The value is
99     * automatically wrapped in an object if it has a primitive type.
100     * If the field is not constant, returns null.
101     */
102    public Object constantValue() {
103        Object result = sym.getConstValue();
104        if (result != null && sym.type.hasTag(BOOLEAN))
105            // javac represents false and true as Integers 0 and 1
106            result = Boolean.valueOf(((Integer)result).intValue() != 0);
107        return result;
108    }
109
110    /**
111     * Get the value of a constant field.
112     *
113     * @return the text of a Java language expression whose value
114     * is the value of the constant. The expression uses no identifiers
115     * other than primitive literals. If the field is
116     * not constant, returns null.
117     */
118    public String constantValueExpression() {
119        return constantValueExpression(constantValue());
120    }
121
122    /**
123     * A static version of the above.
124     */
125    static String constantValueExpression(Object cb) {
126        if (cb == null) return null;
127        if (cb instanceof Character) return sourceForm(((Character)cb).charValue());
128        if (cb instanceof Byte) return sourceForm(((Byte)cb).byteValue());
129        if (cb instanceof String) return sourceForm((String)cb);
130        if (cb instanceof Double) return sourceForm(((Double)cb).doubleValue(), 'd');
131        if (cb instanceof Float) return sourceForm(((Float)cb).doubleValue(), 'f');
132        if (cb instanceof Long) return cb + "L";
133        return cb.toString(); // covers int, short
134    }
135        // where
136        private static String sourceForm(double v, char suffix) {
137            if (Double.isNaN(v))
138                return "0" + suffix + "/0" + suffix;
139            if (v == Double.POSITIVE_INFINITY)
140                return "1" + suffix + "/0" + suffix;
141            if (v == Double.NEGATIVE_INFINITY)
142                return "-1" + suffix + "/0" + suffix;
143            return v + (suffix == 'f' || suffix == 'F' ? "" + suffix : "");
144        }
145        private static String sourceForm(char c) {
146            StringBuilder buf = new StringBuilder(8);
147            buf.append('\'');
148            sourceChar(c, buf);
149            buf.append('\'');
150            return buf.toString();
151        }
152        private static String sourceForm(byte c) {
153            return "0x" + Integer.toString(c & 0xff, 16);
154        }
155        private static String sourceForm(String s) {
156            StringBuilder buf = new StringBuilder(s.length() + 5);
157            buf.append('\"');
158            for (int i=0; i<s.length(); i++) {
159                char c = s.charAt(i);
160                sourceChar(c, buf);
161            }
162            buf.append('\"');
163            return buf.toString();
164        }
165        private static void sourceChar(char c, StringBuilder buf) {
166            switch (c) {
167            case '\b': buf.append("\\b"); return;
168            case '\t': buf.append("\\t"); return;
169            case '\n': buf.append("\\n"); return;
170            case '\f': buf.append("\\f"); return;
171            case '\r': buf.append("\\r"); return;
172            case '\"': buf.append("\\\""); return;
173            case '\'': buf.append("\\\'"); return;
174            case '\\': buf.append("\\\\"); return;
175            default:
176                if (isPrintableAscii(c)) {
177                    buf.append(c); return;
178                }
179                unicodeEscape(c, buf);
180                return;
181            }
182        }
183        private static void unicodeEscape(char c, StringBuilder buf) {
184            final String chars = "0123456789abcdef";
185            buf.append("\\u");
186            buf.append(chars.charAt(15 & (c>>12)));
187            buf.append(chars.charAt(15 & (c>>8)));
188            buf.append(chars.charAt(15 & (c>>4)));
189            buf.append(chars.charAt(15 & (c>>0)));
190        }
191        private static boolean isPrintableAscii(char c) {
192            return c >= ' ' && c <= '~';
193        }
194
195    /**
196     * Return true if this field is included in the active set.
197     */
198    public boolean isIncluded() {
199        return containingClass().isIncluded() && env.shouldDocument(sym);
200    }
201
202    /**
203     * Is this Doc item a field (but not an enum constant?
204     */
205    @Override
206    public boolean isField() {
207        return !isEnumConstant();
208    }
209
210    /**
211     * Is this Doc item an enum constant?
212     * (For legacy doclets, return false.)
213     */
214    @Override
215    public boolean isEnumConstant() {
216        return (getFlags() & Flags.ENUM) != 0 &&
217               !env.legacyDoclet;
218    }
219
220    /**
221     * Return true if this field is transient
222     */
223    public boolean isTransient() {
224        return Modifier.isTransient(getModifiers());
225    }
226
227    /**
228     * Return true if this field is volatile
229     */
230    public boolean isVolatile() {
231        return Modifier.isVolatile(getModifiers());
232    }
233
234    /**
235     * Returns true if this field was synthesized by the compiler.
236     */
237    public boolean isSynthetic() {
238        return (getFlags() & Flags.SYNTHETIC) != 0;
239    }
240
241    /**
242     * Return the serialField tags in this FieldDocImpl item.
243     *
244     * @return an array of <tt>SerialFieldTagImpl</tt> containing all
245     *         <code>&#64;serialField</code> tags.
246     */
247    public SerialFieldTag[] serialFieldTags() {
248        return comment().serialFieldTags();
249    }
250
251    public String name() {
252        if (name == null) {
253            name = sym.name.toString();
254        }
255        return name;
256    }
257
258    private String name;
259
260    public String qualifiedName() {
261        if (qualifiedName == null) {
262            qualifiedName = sym.enclClass().getQualifiedName() + "." + name();
263        }
264        return qualifiedName;
265    }
266
267    private String qualifiedName;
268
269    /**
270     * Return the source position of the entity, or null if
271     * no position is available.
272     */
273    @Override
274    public SourcePosition position() {
275        if (sym.enclClass().sourcefile == null) return null;
276        return SourcePositionImpl.make(sym.enclClass().sourcefile,
277                                       (tree==null) ? 0 : tree.pos,
278                                       lineMap);
279    }
280}
281