1 /*
   2  * Copyright (c) 2006, 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 
  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&eacute;
  50  * @see javax.lang.model.util.Elements#getName
  51  * @since 1.6
  52  */
  53 public interface Name extends CharSequence {
  54     /**
  55      * Returns {@code true} if the argument represents the same
  56      * name as {@code this}, and {@code false} otherwise.
  57      *
  58      * <p>Note that the identity of a {@code Name} is a function both
  59      * of its content in terms of a sequence of characters as well as
  60      * the implementation which created it.
  61      *
  62      * @param obj  the object to be compared with this element
  63      * @return {@code true} if the specified object represents the same
  64      *          name as this
  65      * @see Element#equals
  66      */
  67     boolean equals(Object obj);
  68 
  69     /**
  70      * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
  71      *
  72      * @see #equals
  73      */
  74     int hashCode();
  75 
  76     /**
  77      * Compares this name to the specified {@code CharSequence}. The result
  78      * is {@code true} if and only if this name represents the same sequence
  79      * of {@code char} values as the specified sequence.
  80      *
  81      * @return {@code true} if this name represents the same sequence
  82      * of {@code char} values as the specified sequence, {@code false}
  83      * otherwise
  84      *
  85      * @param cs The sequence to compare this name against
  86      * @see String#contentEquals(CharSequence)
  87      */
  88     boolean contentEquals(CharSequence cs);
  89 }