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