001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.oscal.lib.profile.resolver.policy;
007
008import java.util.List;
009
010import dev.metaschema.oscal.lib.profile.resolver.support.IEntityItem;
011import edu.umd.cs.findbugs.annotations.NonNull;
012
013public interface ICustomReferencePolicyHandler<TYPE> {
014  @NonNull
015  ICustomReferencePolicyHandler<?> IGNORE_INDEX_MISS_POLICY = new AbstractIndexMissPolicyHandler<>() {
016    @Override
017    public boolean handleIndexMiss(
018        @NonNull ICustomReferencePolicy<Object> policy,
019        @NonNull Object type,
020        @NonNull List<IEntityItem.ItemType> itemTypes,
021        @NonNull String identifier,
022        @NonNull IReferenceVisitor<?> visitor) {
023      // do nothing
024      return true;
025    }
026  };
027
028  /**
029   * A callback used to handle the case where an identifier could not be parsed
030   * from the reference text.
031   *
032   * @param policy
033   *          the reference policy for this reference
034   * @param reference
035   *          the reference object
036   * @param visitor
037   *          the reference visitor used to resolve referenced objects
038   * @return {@code true} if the reference is considered handled, or {@code false}
039   *         otherwise
040   */
041  default boolean handleIdentifierNonMatch(
042      @NonNull ICustomReferencePolicy<TYPE> policy,
043      @NonNull TYPE reference,
044      @NonNull IReferenceVisitor<?> visitor) {
045    return false;
046  }
047
048  /**
049   * A callback used to handle the case where an identifier could be parsed from
050   * the reference text, but the index didn't contain a matching entity.
051   *
052   * @param policy
053   *          the reference policy for this reference
054   * @param reference
055   *          the reference object
056   * @param itemTypes
057   *          the item types that were checked
058   * @param identifier
059   *          the parsed identifier
060   * @param visitor
061   *          the reference visitor used to resolve referenced objects
062   * @return {@code true} if the reference is considered handled, or {@code false}
063   *         otherwise
064   */
065  default boolean handleIndexMiss(
066      @NonNull ICustomReferencePolicy<TYPE> policy,
067      @NonNull TYPE reference,
068      @NonNull List<IEntityItem.ItemType> itemTypes,
069      @NonNull String identifier,
070      @NonNull IReferenceVisitor<?> visitor) {
071    return false;
072  }
073
074  /**
075   * A callback used to handle the case where an identifier could be parsed and
076   * the index contains a matching entity.
077   *
078   * @param policy
079   *          the reference policy for this reference
080   * @param reference
081   *          the reference object
082   * @param item
083   *          the entity that is referenced
084   * @param visitor
085   *          the reference visitor used to resolve referenced objects
086   * @return {@code true} if the reference is considered handled, or {@code false}
087   *         otherwise
088   */
089  default boolean handleIndexHit(
090      @NonNull ICustomReferencePolicy<TYPE> policy,
091      @NonNull TYPE reference,
092      @NonNull IEntityItem item,
093      @NonNull IReferenceVisitor<?> visitor) {
094    return false;
095  }
096}