001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.core.model;
007
008import javax.xml.XMLConstants;
009
010import dev.metaschema.core.qname.IEnhancedQName;
011import edu.umd.cs.findbugs.annotations.NonNull;
012import edu.umd.cs.findbugs.annotations.Nullable;
013
014/**
015 * Represents a model element that has a name and associated naming properties.
016 * <p>
017 * This interface provides methods for accessing the name, use name, qualified
018 * name, and index values used for XML and binary representations of model
019 * elements.
020 */
021public interface INamed {
022
023  /**
024   * Retrieve the name of the model element.
025   *
026   * @return the name
027   */
028  @NonNull
029  String getName();
030
031  /**
032   * Retrieve the name to use for the model element, instead of the name.
033   *
034   * @return the use name or {@code null} if no use name is defined
035   */
036  // from INamedModelElement
037  @Nullable
038  default String getUseName() {
039    // no use-name by default
040    return null;
041  }
042
043  /**
044   * Get the name to use based on the provided names. This method will return the
045   * use name provided by {@link #getUseName()} if the call is not {@code null},
046   * and fall back to the name provided by {@link #getName()} otherwise. This is
047   * the model name to use for the for an instance where the instance is
048   * referenced.
049   *
050   * @return the use name if available, or the name if not
051   *
052   * @see #getUseName()
053   * @see #getName()
054   */
055  // from INamedModelElement
056  @NonNull
057  default String getEffectiveName() {
058    @Nullable
059    String useName = getUseName();
060    return useName == null ? getName() : useName;
061  }
062
063  /**
064   * Get the unique XML qualified name for this model element.
065   * <p>
066   * The qualified name is considered to be unique relative to all sibling
067   * elements. For a flag, this name will be unique among all flag instances on
068   * the same field or assembly definition. For a field or assembly, this name
069   * will be unique among all sibling field or assembly instances on the same
070   * assembly definition.
071   * <p>
072   * Multiple calls to this method are expected to produce the same, deterministic
073   * return value.
074   * <p>
075   * If the namespace is not specified, then the resulting QName will have the
076   * namespace {@link XMLConstants#NULL_NS_URI}.
077   * <p>
078   * This implementation may be overridden by implementation that cache the QName
079   * or provide for a more efficient method for QName creation.
080   *
081   * @return the XML qualified name, or {@code null} if there isn't one
082   */
083  @NonNull
084  IEnhancedQName getQName();
085
086  /**
087   * Retrieve the index value to use for binary naming.
088   *
089   * @return the name index or {@code null} if no name index is defined
090   */
091  // from INamedModelElement
092  @Nullable
093  default Integer getIndex() {
094    // no index by default
095    return null;
096  }
097
098  /**
099   * Retrieve the index value to use for binary naming, instead of the name.
100   *
101   * @return the use name index or {@code null} if no use name index is defined
102   */
103  // from INamedModelElement
104  @Nullable
105  default Integer getUseIndex() {
106    // no use-name index by default
107    return null;
108  }
109
110  /**
111   * Get the index value to use for binary naming based on the provided index
112   * values.
113   * <p>
114   * This method will return the use index value provided by
115   * {@link #getUseIndex()} if the call result is not {@code null}, and fall back
116   * to the index value provided by {@link #getIndex()} otherwise.
117   *
118   * @return the index value if available, or {@code null} otherwise
119   */
120  // from INamedModelElement
121  @Nullable
122  default Integer getEffectiveIndex() {
123    @Nullable
124    Integer useIndex = getUseIndex();
125    return useIndex == null ? getIndex() : useIndex;
126  }
127}