1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package gov.nist.secauto.oscal.lib.profile.resolver.policy;
7   
8   import gov.nist.secauto.oscal.lib.profile.resolver.support.IEntityItem;
9   
10  import java.util.List;
11  
12  import edu.umd.cs.findbugs.annotations.NonNull;
13  
14  public interface ICustomReferencePolicyHandler<TYPE> {
15    @NonNull
16    ICustomReferencePolicyHandler<?> IGNORE_INDEX_MISS_POLICY = new AbstractIndexMissPolicyHandler<>() {
17      @Override
18      public boolean handleIndexMiss(
19          @NonNull ICustomReferencePolicy<Object> policy,
20          @NonNull Object type,
21          @NonNull List<IEntityItem.ItemType> itemTypes,
22          @NonNull String identifier,
23          @NonNull IReferenceVisitor<?> visitor) {
24        // do nothing
25        return true;
26      }
27    };
28  
29    /**
30     * A callback used to handle the case where an identifier could not be parsed
31     * from the reference text.
32     *
33     * @param policy
34     *          the reference policy for this reference
35     * @param reference
36     *          the reference object
37     * @param visitor
38     *          the reference visitor used to resolve referenced objects
39     * @return {@code true} if the reference is considered handled, or {@code false}
40     *         otherwise
41     */
42    default boolean handleIdentifierNonMatch(
43        @NonNull ICustomReferencePolicy<TYPE> policy,
44        @NonNull TYPE reference,
45        @NonNull IReferenceVisitor<?> visitor) {
46      return false;
47    }
48  
49    /**
50     * A callback used to handle the case where an identifier could be parsed from
51     * the reference text, but the index didn't contain a matching entity.
52     *
53     * @param policy
54     *          the reference policy for this reference
55     * @param reference
56     *          the reference object
57     * @param itemTypes
58     *          the item types that were checked
59     * @param identifier
60     *          the parsed identifier
61     * @param visitor
62     *          the reference visitor used to resolve referenced objects
63     * @return {@code true} if the reference is considered handled, or {@code false}
64     *         otherwise
65     */
66    default boolean handleIndexMiss(
67        @NonNull ICustomReferencePolicy<TYPE> policy,
68        @NonNull TYPE reference,
69        @NonNull List<IEntityItem.ItemType> itemTypes,
70        @NonNull String identifier,
71        @NonNull IReferenceVisitor<?> visitor) {
72      return false;
73    }
74  
75    /**
76     * A callback used to handle the case where an identifier could be parsed and
77     * the index contains a matching entity.
78     *
79     * @param policy
80     *          the reference policy for this reference
81     * @param reference
82     *          the reference object
83     * @param item
84     *          the entity that is referenced
85     * @param visitor
86     *          the reference visitor used to resolve referenced objects
87     * @return {@code true} if the reference is considered handled, or {@code false}
88     *         otherwise
89     */
90    default boolean handleIndexHit(
91        @NonNull ICustomReferencePolicy<TYPE> policy,
92        @NonNull TYPE reference,
93        @NonNull IEntityItem item,
94        @NonNull IReferenceVisitor<?> visitor) {
95      return false;
96    }
97  }