01 /*
02 * Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
03 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
04 *
05 * This code is free software; you can redistribute it and/or modify it
06 * under the terms of the GNU General Public License version 2 only, as
07 * published by the Free Software Foundation. Sun designates this
08 * particular file as subject to the "Classpath" exception as provided
09 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.lang.model.element;
27
28 /**
29 * An immutable sequence of characters. When created by the same
30 * implementation, objects implementing this interface must obey the
31 * general {@linkplain Object#equals equals contract} when compared
32 * with each other. Therefore, {@code Name} objects from the same
33 * implementation are usable in collections while {@code Name}s from
34 * different implementations may not work properly in collections.
35 *
36 * <p>An empty {@code Name} has a length of zero.
37 *
38 * <p>In the context of {@linkplain
39 * javax.annotation.processing.ProcessingEnvironment annotation
40 * processing}, the guarantees for "the same" implementation must
41 * include contexts where the {@linkplain javax.annotation.processing
42 * API mediated} side effects of {@linkplain
43 * javax.annotation.processing.Processor processors} could be visible
44 * to each other, including successive annotation processing
45 * {@linkplain javax.annotation.processing.RoundEnvironment rounds}.
46 *
47 * @author Joseph D. Darcy
48 * @author Scott Seligman
49 * @author Peter von der Ahé
50 * @version 1.8 07/05/05
51 * @see javax.lang.model.util.Elements#getName
52 * @since 1.6
53 */
54 public interface Name extends CharSequence {
55 /**
56 * Returns {@code true} if the argument represents the same
57 * name as {@code this}, and {@code false} otherwise.
58 *
59 * <p>Note that the identity of a {@code Name} is a function both
60 * of its content in terms of a sequence of characters as well as
61 * the implementation which created it.
62 *
63 * @param obj the object to be compared with this element
64 * @return {@code true} if the specified object represents the same
65 * name as this
66 * @see Element#equals
67 */
68 boolean equals(Object obj);
69
70 /**
71 * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
72 *
73 * @see #equals
74 */
75 int hashCode();
76
77 /**
78 * Compares this name to the specified {@code CharSequence}. The result
79 * is {@code true} if and only if this name represents the same sequence
80 * of {@code char} values as the specified sequence.
81 *
82 * @return {@code true} if this name represents the same sequence
83 * of {@code char} values as the specified sequence, {@code false}
84 * otherwise
85 *
86 * @param cs The sequence to compare this name against
87 * @see String#contentEquals(CharSequence)
88 */
89 boolean contentEquals(CharSequence cs);
90 }
|