001/* -*- mode: Java; c-basic-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
002 *
003 * Copyright © 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.event;
015
016import java.util.Collection;
017
018import org.microbean.assign.Matcher;
019
020import org.microbean.qualifier.NamedAttributeMap;
021
022import static org.microbean.assign.Qualifiers.anyQualifier;
023import static org.microbean.assign.Qualifiers.defaultQualifier;
024import static org.microbean.assign.Qualifiers.defaultQualifiers;
025import static org.microbean.assign.Qualifiers.qualifiers;
026
027/**
028 * A {@link Matcher} encapsulating <a
029 * href="https://jakarta.ee/specifications/cdi/4.0/jakarta-cdi-spec-4.0#observer_resolution">CDI-compatible event
030 * qualifier matching rules</a>.
031 *
032 * @author <a href="https://about.me/lairdnelson/" target="_top">Laird Nelson</a>
033 *
034 * @see #test(Collection, Collection)
035 */
036public final class EventQualifiersMatcher
037  implements Matcher<Collection<? extends NamedAttributeMap<?>>, Collection<? extends NamedAttributeMap<?>>> {
038
039
040  /*
041   * Constructors.
042   */
043
044
045  /**
046   * Creates a new {@link EventQualifiersMatcher}.
047   */
048  public EventQualifiersMatcher() {
049    super();
050  }
051
052
053  /*
054   * Instance methods.
055   */
056
057
058  /**
059   * Returns {@code true} if and only if either the {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection)
060   * qualifiers present} in {@code receiverAttributes} are {@linkplain Collection#isEmpty() empty}, or if the collection
061   * of {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code
062   * payloadAttributes} {@linkplain Collection#containsAll(Collection) contains all} of the {@linkplain
063   * org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code receiverAttributes}.
064   *
065   * @param receiverAttributes a {@link Collection} of {@link NamedAttributeMap}s; must not be {@code null}
066   *
067   * @param payloadAttributes a {@link Collection} of {@link NamedAttributeMap}s; must not be {@code null}
068   *
069   * @return {@code true} if and only if either the {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection)
070   * qualifiers present} in {@code receiverAttributes} are {@linkplain Collection#isEmpty() empty}, or if the collection
071   * of {@linkplain org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code
072   * payloadAttributes} {@linkplain Collection#containsAll(Collection) contains all} of the {@linkplain
073   * org.microbean.assign.Qualifiers#qualifiers(Collection) qualifiers present} in {@code receiverAttributes}
074   *
075   * @exception NullPointerException if either argument is {@code null}
076   */
077  @Override // Matcher<Collection<? extends NamedAttributeMap<?>>, Collection<? extends NamedAttributeMap<?>>>
078  public final boolean test(final Collection<? extends NamedAttributeMap<?>> receiverAttributes,
079                            final Collection<? extends NamedAttributeMap<?>> payloadAttributes) {
080    // "An event is delivered to an observer method if...the observer method has no event qualifiers or has a subset of
081    // the event qualifiers."
082    final Collection<? extends NamedAttributeMap<?>> receiverQualifiers = qualifiers(receiverAttributes);
083    return receiverQualifiers.isEmpty() || qualifiers(payloadAttributes).containsAll(receiverQualifiers);
084  }
085
086}