001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 2023–2025 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.bean;
015
016import java.lang.constant.ClassDesc;
017import java.lang.constant.Constable;
018import java.lang.constant.DynamicConstantDesc;
019import java.lang.constant.MethodHandleDesc;
020
021import java.util.ArrayList;
022import java.util.Arrays;
023import java.util.Collections;
024import java.util.List;
025import java.util.Objects;
026import java.util.Optional;
027
028import javax.lang.model.type.TypeMirror;
029
030import org.microbean.attributes.Attributed;
031import org.microbean.attributes.Attributes;
032
033import org.microbean.constant.Constables;
034
035import static java.lang.constant.ConstantDescs.BSM_INVOKE;
036import static java.lang.constant.ConstantDescs.CD_boolean;
037import static java.lang.constant.ConstantDescs.CD_int;
038import static java.lang.constant.ConstantDescs.CD_List;
039import static java.lang.constant.ConstantDescs.FALSE;
040import static java.lang.constant.ConstantDescs.TRUE;
041
042import static org.microbean.bean.BeanTypes.legalBeanType;
043
044/**
045 * An identifier for a {@link Bean}.
046 *
047 * <p>Note that because an {@link Id} houses a {@link BeanTypeList}, and because a {@link BeanTypeList} houses {@link
048 * TypeMirror} instances, and because many {@link TypeMirror} instances may model the same type, two {@link Id}s that
049 * might appear as equal at first glance may not be.</p>
050 *
051 * @param types a {@link BeanTypeList}
052 *
053 * @param attributes a {@link List} of {@link Attributes}s
054 *
055 * @param alternate whether this {@link Id} is to be considered an <dfn>alternate</dfn>
056 *
057 * @param rank the {@linkplain Ranked#rank() rank} of this {@link Id}; often {@link Ranked#DEFAULT_RANK} to indicate no
058 * particular rank; <strong>always {@link Ranked#DEFAULT_RANK} if {@code alternate} is {@code false}</strong>
059 *
060 * @author <a href="https://about.me/lairdnelson" target="_top">Laird Nelson</a>
061 *
062 * @see Ranked
063 *
064 * @see TypeMirror#equals(Object)
065 */
066public final record Id(BeanTypeList types,
067                       List<Attributes> attributes,
068                       boolean alternate,
069                       int rank)
070  implements Attributed, Constable, Ranked {
071
072
073  /*
074   * Constructors.
075   */
076
077
078  /**
079   * Creates a new {@link Id} that is not an alternate and that therefore has a {@linkplain Ranked#DEFAULT_RANK default
080   * rank}.
081   *
082   * @param types a {@link BeanTypeList}; must not be {@code null}; must not be {@linkplain List#isEmpty() empty}
083   *
084   * @param attributes a {@link List} of {@link Attributes}s; must not be {@code null}
085   *
086   * @exception NullPointerException if {@code types} or {@code attributes} is {@code null}
087   */
088  public Id(final BeanTypeList types,
089            final List<Attributes> attributes) {
090    this(types, attributes, false, DEFAULT_RANK);
091  }
092
093  /**
094   * Creates a new {@link Id}.
095   *
096   * @param types a {@link BeanTypeList}; must not be {@code null}; must not be {@linkplain List#isEmpty() empty}
097   *
098   * @param attributes a {@link List} of {@link Attributes}s; must not be {@code null}
099   *
100   * @param alternate whether this {@link Id} is to be considered an <dfn>alternate</dfn>
101   *
102   * @param rank the {@linkplain Ranked#rank() rank} of this {@link Id}; often {@link Ranked#DEFAULT_RANK} to indicate
103   * no particular rank; <strong>always {@link Ranked#DEFAULT_RANK} if {@code alternate} is {@code false}</strong>
104   *
105   * @exception NullPointerException if {@code types} or {@code attributes} is {@code null}
106   */
107  public Id {
108    Objects.requireNonNull(types, "types");
109    attributes = List.copyOf(attributes);
110    if (!alternate) {
111      rank = DEFAULT_RANK;
112    }
113  }
114
115
116  /*
117   * Instance methods.
118   */
119
120
121  @Override // Constable
122  public final Optional<DynamicConstantDesc<Id>> describeConstable() {
123    return Constables.describeConstable(this.attributes())
124      .flatMap(attributesDesc -> this.types().describeConstable()
125               .map(typesDesc -> DynamicConstantDesc.of(BSM_INVOKE,
126                                                        MethodHandleDesc.ofConstructor(this.getClass().describeConstable().orElseThrow(),
127                                                                                       BeanTypeList.class.describeConstable().orElseThrow(),
128                                                                                       CD_List,
129                                                                                       CD_boolean,
130                                                                                       CD_int),
131                                                        typesDesc,
132                                                        attributesDesc,
133                                                        this.alternate() ? TRUE : FALSE,
134                                                        this.rank())));
135  }
136
137  
138
139}