1 /*
2 * #%L
3 * wcm.io
4 * %%
5 * Copyright (C) 2018 wcm.io
6 * %%
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 * #L%
19 */
20 package io.wcm.caravan.hal.comparison;
21
22 import org.osgi.annotation.versioning.ProviderType;
23
24 import com.fasterxml.jackson.databind.JsonNode;
25
26 import io.wcm.caravan.hal.resource.HalResource;
27
28 /**
29 * Represents a single difference detected by the {@link HalComparison} when comparing two trees of
30 * {@link HalResource}s.
31 * <p>
32 * Some examples of changes that are represented by a {@link HalDifference} instance:
33 * </p>
34 * <ul>
35 * <li>a JSON property in the resource state was added, removed or modified</li>
36 * <li>a link was added or removed</li>
37 * <li>an embedded resource was added or removed</li>
38 * <li>the order of links or embedded resource has changed</li>
39 * </ul>
40 */
41 @ProviderType
42 public interface HalDifference {
43
44 /**
45 * Describes the "relational" location of the resource (or property) that was reported to be different.
46 * @return a {@link HalComparisonContext} that can be used to group or filter the results based on their relations and
47 * context
48 */
49 HalComparisonContext getHalContext();
50
51 /**
52 * @return what kind of modification was detected
53 */
54 ChangeType getChangeType();
55
56 /**
57 * @return what kind of HAL/JSON element was found to be different
58 */
59 EntityType getEntityType();
60
61 /**
62 * @return a text that describes why the difference was reported
63 */
64 String getDescription();
65
66 /**
67 * @return a formatted JSON string of the resource, link, property or state object that was expected (or an empty
68 * string if the value only exists in the actual resource)
69 */
70 JsonNode getExpectedJson();
71
72 /**
73 * @return a formatted JSON string of the resource, link, property or state object that was actually found (or an
74 * empty string if the value only exists in the expected resource)
75 */
76 JsonNode getActualJson();
77
78 /**
79 * defines the different kind of HAL/JSON elements that are compared
80 */
81 enum EntityType {
82 LINK, EMBEDDED, PROPERTY
83 }
84
85 /**
86 * defines the different types of modifications that can be detected
87 */
88 enum ChangeType {
89 ADDITIONAL, MISSING, MODIFIED, REORDERED
90 }
91 }