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