001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2025–2026 microBean™.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
006 * the License. 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 distributed under the License is distributed on
011 * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
012 * specific language governing permissions and limitations under the License.
013 */
014package org.microbean.attributes;
015
016import java.util.List;
017
018/**
019 * Something with affiliated {@link Attributes} instances that further describe it.
020 *
021 * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
022 *
023 * @see Attributes
024 */
025public interface Attributed {
026
027  /**
028   * Returns a non-{@code null}, immutable, determinate {@link List} of {@link Attributes}.
029   *
030   * @return a non-{@code null}, immutable, determinate {@link List} of {@link Attributes}
031   */
032  public List<Attributes> attributes();
033
034  /**
035   * Returns {@code true} if and only if this {@link Attributed} implementation is equal to the supplied {@link Object},
036   * following the general contract of {@link Object#equals(Object)} <strong>with additional requirements</strong>.
037   *
038   * <p>The return value of any invocation of the {@link #attributes()} method must not be factored into equality
039   * computations or undefined behavior may result.</p>
040   *
041   * @param other the {@link Object} to test; may be {@code null} in which case {@code false} will be returned
042   *
043   * @return {@code true} if and only if this {@link Attributed} implementation is equal to the supplied {@link Object}
044   *
045   * @see #attributes()
046   *
047   * @see #hashCode()
048   */
049  @Override
050  public boolean equals(Object other);
051
052  /**
053   * Returns a hashcode for this {@link Attributed} implementation <strong>that is not based on the return value of an
054   * invocation of the {@link #attributes()} method</strong>.
055   *
056   * @return a hashcode for this {@link Attributed}
057   *
058   * @see #attributes()
059   *
060   * @see #equals(Object)
061   */
062  public int hashCode();
063
064}