    001    /*
    002     * Copyright (C) 2007 The Guava Authors
    003     *
    004     * Licensed under the Apache License, Version 2.0 (the "License");
    005     * you may not use this file except in compliance with the License.
    006     * You may obtain a copy of the License at
    007     *
    008     * http://www.apache.org/licenses/LICENSE-2.0
    009     *
    010     * Unless required by applicable law or agreed to in writing, software
    011     * distributed under the License is distributed on an "AS IS" BASIS,
    012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    013     * See the License for the specific language governing permissions and
    014     * limitations under the License.
    015     */
    016
    017    package com.google.common.collect;
    018
    019    import com.google.common.annotations.Beta;
    020
    021    /**
    022     * Provides equivalent behavior to {@link String#intern} for other immutable
    023     * types.
    024     *
    025     * @author Kevin Bourrillion
    026     * @since 3.0
    027     */
    028    @Beta
    029    public interface Interner<E> {
    030      /**
    031       * Chooses and returns the representative instance for any of a collection of
    032       * instances that are equal to each other. If two {@linkplain Object#equals
    033       * equal} inputs are given to this method, both calls will return the same
    034       * instance.  That is, {@code intern(a).equals(a)} always holds, and {@code
    035       * intern(a) == intern(b)} if and only if {@code a.equals(b)}. Note that
    036       * {@code intern(a)} is permitted to return one instance now and a different
    037       * instance later if the original interned instance was garbage-collected.
    038       *
    039       * <p><b>Warning:</b> do not use with mutable objects.
    040       *
    041       * @throws NullPointerException if {@code sample} is null
    042       */
    043      E intern(E sample);
    044    }