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