1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package gov.nist.secauto.metaschema.core.model.constraint;
7   
8   import gov.nist.secauto.metaschema.core.datatype.markup.MarkupMultiline;
9   import gov.nist.secauto.metaschema.core.metapath.IMetapathExpression;
10  import gov.nist.secauto.metaschema.core.model.constraint.impl.DefaultKeyField;
11  
12  import java.util.regex.Pattern;
13  
14  import edu.umd.cs.findbugs.annotations.NonNull;
15  import edu.umd.cs.findbugs.annotations.Nullable;
16  
17  /**
18   * Represents a component of a key used in a key-based index.
19   * <p>
20   * A key field is targeted at a Metaschema field or flag data object's value. An
21   * optional pattern can be used to extract a portion of the value for use in
22   * generating an index key.
23   */
24  public interface IKeyField {
25    /**
26     * Construct a new key field based on the provided target. An optional pattern
27     * can be used to extract a portion of the resulting key value.
28     *
29     * @param target
30     *          a Metapath expression identifying the target of the key field
31     * @param pattern
32     *          an optional used to extract a portion of the resulting key value
33     * @param remarks
34     *          optional remarks describing the intent of the constraint
35     * @return the new key field
36     */
37    @NonNull
38    static IKeyField of(
39        @NonNull IMetapathExpression target,
40        @Nullable Pattern pattern,
41        @Nullable MarkupMultiline remarks) {
42      return new DefaultKeyField(target, pattern, remarks);
43    }
44  
45    /**
46     * Get the Metapath expression that identifies the node item whose value will be
47     * used as the key value.
48     *
49     * @return the Metapath expression identifying the key value target
50     */
51    @NonNull
52    IMetapathExpression getTarget();
53  
54    /**
55     * A pattern to use to retrieve the value. If non-{@code null}, the first
56     * capturing group is used to retrieve the value.
57     *
58     * @return a pattern to use to get the value or {@code null} if the full value
59     *         is to be used
60     */
61    @Nullable
62    Pattern getPattern();
63  
64    /**
65     * Any remarks about the key field as markup text.
66     *
67     * @return markup text or {@code null} if no text is provided
68     */
69    @Nullable
70    MarkupMultiline getRemarks();
71  }