1 package org.apache.maven.api.xml;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.util.List;
23 import java.util.Map;
24
25 import org.apache.maven.api.annotations.Experimental;
26 import org.apache.maven.api.annotations.Immutable;
27 import org.apache.maven.api.annotations.Nonnull;
28 import org.apache.maven.api.annotations.Nullable;
29 import org.apache.maven.api.annotations.ThreadSafe;
30
31 /**
32 * An immutable xml node.
33 *
34 * @since 4.0
35 */
36 @Experimental
37 @ThreadSafe @Immutable
38 public interface Dom
39 {
40
41 String CHILDREN_COMBINATION_MODE_ATTRIBUTE = "combine.children";
42
43 String CHILDREN_COMBINATION_MERGE = "merge";
44
45 String CHILDREN_COMBINATION_APPEND = "append";
46
47 /**
48 * This default mode for combining children DOMs during merge means that where element names match, the process will
49 * try to merge the element data, rather than putting the dominant and recessive elements (which share the same
50 * element name) as siblings in the resulting DOM.
51 */
52 String DEFAULT_CHILDREN_COMBINATION_MODE = CHILDREN_COMBINATION_MERGE;
53
54 String SELF_COMBINATION_MODE_ATTRIBUTE = "combine.self";
55
56 String SELF_COMBINATION_OVERRIDE = "override";
57
58 String SELF_COMBINATION_MERGE = "merge";
59
60 String SELF_COMBINATION_REMOVE = "remove";
61
62 /**
63 * This default mode for combining a DOM node during merge means that where element names match, the process will
64 * try to merge the element attributes and values, rather than overriding the recessive element completely with the
65 * dominant one. This means that wherever the dominant element doesn't provide the value or a particular attribute,
66 * that value or attribute will be set from the recessive DOM node.
67 */
68 String DEFAULT_SELF_COMBINATION_MODE = SELF_COMBINATION_MERGE;
69
70 @Nonnull
71 String getName();
72
73 @Nullable
74 String getValue();
75
76 @Nonnull
77 Map<String, String> getAttributes();
78
79 @Nullable
80 String getAttribute( @Nonnull String name );
81
82 @Nonnull
83 List<Dom> getChildren();
84
85 @Nullable
86 Dom getChild( String name );
87
88 @Nullable
89 Object getInputLocation();
90
91 default Dom merge( @Nullable Dom source )
92 {
93 return merge( source, (Boolean) null );
94 }
95
96 Dom merge( @Nullable Dom source, @Nullable Boolean childMergeOverride );
97
98 Dom clone();
99
100 /**
101 * Merge recessive into dominant and return either {@code dominant}
102 * with merged information or a clone of {@code recessive} if
103 * {@code dominant} is {@code null}.
104 *
105 * @param dominant the node
106 * @param recessive if {@code null}, nothing will happen
107 * @return the merged node
108 */
109 @Nullable
110 static Dom merge( @Nullable Dom dominant, @Nullable Dom recessive )
111 {
112 return merge( dominant, recessive, null );
113 }
114
115 @Nullable
116 static Dom merge( @Nullable Dom dominant, @Nullable Dom recessive, @Nullable Boolean childMergeOverride )
117 {
118 if ( recessive == null )
119 {
120 return dominant;
121 }
122 if ( dominant == null )
123 {
124 return recessive;
125 }
126 return dominant.merge( recessive, childMergeOverride );
127 }
128
129 }