1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package dev.metaschema.core.model.validation;
7   
8   import java.net.URI;
9   
10  import dev.metaschema.core.model.IResourceLocation;
11  import dev.metaschema.core.model.constraint.IConstraint;
12  import edu.umd.cs.findbugs.annotations.NonNull;
13  import edu.umd.cs.findbugs.annotations.Nullable;
14  
15  /**
16   * Provides information about an individual finding that is the result of a
17   * completed content validation.
18   */
19  public interface IValidationFinding {
20    /**
21     * The finding type.
22     */
23    enum Kind {
24      /**
25       * The finding does not apply to the intended purpose of the validation.
26       */
27      NOT_APPLICABLE,
28      /**
29       * The finding represents a successful result.
30       */
31      PASS,
32      /**
33       * The finding represents an unsuccessful result.
34       */
35      FAIL,
36      /**
37       * The finding is providing information that does not indicate success or
38       * failure.
39       */
40      INFORMATIONAL;
41    }
42  
43    /**
44     * Get the unique identifier for the finding.
45     *
46     * @return the identifier
47     */
48    @Nullable
49    String getIdentifier();
50  
51    /**
52     * Get the finding's severity.
53     *
54     * @return the severity
55     */
56    @NonNull
57    IConstraint.Level getSeverity();
58  
59    /**
60     * Get the finding type.
61     *
62     * @return the finding type
63     */
64    @NonNull
65    Kind getKind();
66  
67    /**
68     * Get the document's URI.
69     *
70     * @return the document's URI or {@code null} if it is not known
71     */
72    @Nullable
73    URI getDocumentUri();
74  
75    /**
76     * Get the location in the associated resource associated with the finding.
77     *
78     * @return the location or {@code null} if no location is known
79     */
80    @Nullable
81    IResourceLocation getLocation();
82  
83    /**
84     * Get the path expression type provided by the {@link #getPath()} method.
85     *
86     * @return the path type identifier or {@code null} if unknown
87     */
88    @Nullable
89    String getPathKind();
90  
91    /**
92     * A format specific path to the finding in the source document.
93     *
94     * @return the path or {@code null} if unknown
95     */
96    @Nullable
97    String getPath();
98  
99    /**
100    * Get the finding message.
101    *
102    * @return the message or {@code null} if there is no message
103    */
104   @Nullable
105   String getMessage();
106 
107   /**
108    * Get the exception associated with the finding.
109    *
110    * @return the {@link Throwable} or {@code null} if no thowable is associated
111    *         with the finding
112    */
113   Throwable getCause();
114 }