Entry.java example

Explorer
geotoolkit-master
/*
 *    Geotoolkit.org - An Open Source Java GIS Toolkit
 *    http://www.geotoolkit.org
 *
 *    (C) 2005-2012, Open Source Geospatial Foundation (OSGeo)
 *    (C) 2007-2012, Geomatys
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */
package org.geotoolkit.internal.sql.table;


/**
 * Interface for entries created from a record in a table. They are the elements returned by
 * {@link SingletonTable}. Each entry must have an identifier which is unique among all entries
 * in a given table. However the identifier may not be unique among entries in different tables.
 *
 * @author Martin Desruisseaux (IRD, Geomatys)
 * @author Guilhem Legal (Geomatys)
 * @version 3.11
 *
 * @since 3.09 (derived from Seagis)
 * @module
 */
public interface Entry {
    /**
     * Returns the textual or numeric identifier for this entry. It is often (but not always) the
     * primary key value in a database table. If the identifier is a {@link String}, then that name
     * should be meaningful enough for inclusion in a graphical user interface.
     *
     * @return The identifier, which is not allowed to be null.
     */
    Comparable<?> getIdentifier();

    /**
     * Returns a string representation of this entry. The returned string may be used in graphical
     * user interface, for example a <cite>Swing</cite> {@link javax.swing.JTree}. The current
     * implementation returns the entry {@linkplain #identifier}.
     *
     * @return A string representation of this entry suitable for use in GUI.
     */
    @Override
    String toString();

    /**
     * Returns a hash code value for this entry. The implementation shall compute the hash
     * code from the {@linkplain #getIdentifier() identifier} only. Because entry identifiers
     * should be unique, this is usually sufficient.
     *
     * @return A hash code value computed from the identifier.
     */
    @Override
    int hashCode();

    /**
     * Compares this entry with the specified object for equality. The implementation shall
     * compares at least the {@linkplain #getClass class} and {@linkplain #getIdentifier()
     * identifier}. If should be sufficient when every entries have a unique name, for example
     * when the name is the primary key in a database table. Implementation may compare other
     * attributes as a safety when affordable, but should avoid any comparison that may force
     * the loading of a large amount of data.
     *
     * @param  object The object to compare with this entry.
     * @return {@code true} if the given object is equals to this entry.
     */
    @Override
    boolean equals(Object object);
}