001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 * http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.atteo.xmlcombiner;
015
016/**
017 * Controls the behavior when merging two XML nodes.
018 */
019public enum CombineSelf {
020    /**
021     * Merge elements.
022     * <p>
023     * Attributes from dominant element override those from recessive element.
024     * Child elements are by default paired using their keys (tag name and selected attributes) and combined
025     * recursively. The exact behavior depends on {@link CombineChildren 'combine.children'} attribute value.
026     * </p>
027     * <p>
028     *
029     * Example:<br/>
030     * First:
031     * <pre>
032     * {@code
033     *  <config>
034     *     <service id="1">
035     *         <parameter>parameter</parameter>
036     *     </service>
037     *  </config>
038     * }
039     * </pre>
040     * Second:
041     * <pre>
042     * {@code
043     *  <config>
044     *     <service id="1">
045     *         <parameter2>parameter</parameter2>
046     *     </service>
047     *  </config>
048     * }
049     * </pre>
050     * Result:
051     * <pre>
052     * {@code
053     *  <config>
054     *     <service id="1">
055     *         <parameter>parameter</parameter>
056     *         <parameter2>parameter</parameter2>
057     *     </service>
058     *  </config>
059     * }
060     * </pre>
061     * </p>
062     */
063    MERGE,
064
065    /**
066     * Remove entire element with attributes and children.
067     *
068     * <p>
069     * Example:<br/>
070     * First:
071     * <pre>
072     * {@code
073     *  <config>
074     *     <service id="1">
075     *         <parameter>parameter</parameter>
076     *     </service>
077     *  </config>
078     * }
079     * </pre>
080     * Second:
081     * <pre>
082     * {@code
083     *  <config>
084     *     <service id="1" combine.self="REMOVE"/>
085     *  </config>
086     * }
087     * </pre>
088     * Result:
089     * <pre>
090     * {@code
091     *  <config>
092     *  </config>
093     * }
094     * </pre>
095     * </p>
096     */
097    REMOVE,
098
099    /**
100     * Behaves exactly like {@link #MERGE} if paired element exists in any subsequent dominant document.
101     * If paired element is not found in any dominant document behaves the same as {@link #REMOVE}
102     * <p>
103     * This behavior is specifically designed to allow specifying default values which are used only
104     * when given element exists in any subsequent document.
105     * </p>
106     * <p>
107     * Example:<br/>
108     * First:
109     * <pre>
110     * {@code
111     *  <config>
112     *     <service id="1" combine.self="DEFAULTS">
113     *         <parameter>parameter</parameter>
114     *     </service>
115     *     <service id="2" combine.self="DEFAULTS"/>
116     *  </config>
117     * }
118     * </pre>
119     * Second:
120     * <pre>
121     * {@code
122     * <config>
123     *     <service id="1">
124     *     </service>
125     *  </config>
126     * }
127     * </pre>
128     * Result:
129     * <pre>
130     * {@code
131     * <config>
132     *     <service id="1">
133     *         <parameter>parameter</parameter>
134     *     </service>
135     *  </config>
136     * }
137     * </pre>
138     * </p>
139     */
140    DEFAULTS,
141
142    /**
143     * Override element.
144     * <p>
145     * Completely ignores content from recessive document by overwriting it
146     * with element from dominant document.
147     * </p>
148     *
149     * <p>
150     * Example:<br/>
151     * First:
152     * <pre>
153     * {@code
154     * <config>
155     *     <service id="1">
156     *         <parameter>parameter</parameter>
157     *     </service>
158     *  </config>
159     * }
160     * </pre>
161     * Second:
162     * <pre>
163     * {@code
164     * <config>
165     *     <service id="1" combine.self="override">
166     *         <parameter2>parameter2</parameter2>
167     *     </service>
168     *  </config>
169     * }
170     * </pre>
171     * Result:
172     * <pre>
173     * {@code
174     * <config>
175     *     <service id="1">
176     *         <parameter2>parameter2</parameter2>
177     *     </service>
178     *  </config>
179     * }
180     * </pre>
181     * </p>
182     */
183    OVERRIDE,
184
185    /**
186     * Override element.
187     * <p>
188     * Completely ignores content from recessive document by overwriting it
189     * with element from dominant document.
190     * </p>
191     * <p>
192     * The difference with {@link #OVERRIDE} is that OVERRIDABLE is specified on the tag in recessive document.
193     * </p>
194     * <p>
195     * Example:<br/>
196     * First:
197     * <pre>
198     * {@code
199     *  <config>
200     *     <service id="id1" combine.self="OVERRIDABLE">
201     *         <test/>
202     *     </service>
203     *  </config>
204     * }
205     * </pre>
206     * Second:
207     * <pre>
208     * {@code
209     *  <config>
210     *  </config>
211     * }
212     * </pre>
213     * Result:
214     * <pre>
215     * {@code
216     * <config>
217     *     <service id="id1" combine.self="OVERRIDABLE">
218     *         <test/>
219     *     </service>
220     *  </config>
221     * }
222     * </pre>
223     * </p>
224     * <p>
225     * Example2:<br/>
226     * First:
227     * <pre>
228     * {@code
229     *  <config>
230     *     <service id="id1" combine.self="OVERRIDABLE">
231     *         <test/>
232     *     </service>
233     *  </config>
234     * }
235     * </pre>
236     * Second:
237     * <pre>
238     * {@code
239     *  <config>
240     *      <service id="id1"/>
241     *  </config>
242     * }
243     * </pre>
244     * Result:
245     * <pre>
246     * {@code
247     *  <config>
248     *      <service id="id1"/>
249     *  </config>
250     * }
251     * </pre>
252     * </p>
253     */
254    OVERRIDABLE,
255
256    /**
257     * Override element.
258     * <p>
259     * Completely ignores content from recessive document by overwriting it
260     * with element from dominant document.
261     * </p>
262     * <p>
263     * The difference with {@link #OVERRIDABLE} is that with OVERRIDABLE_BY_TAG recessive element is ignored
264 even when the id is different.
265 </p>
266     * <p>
267     * Example:<br/>
268     * First:
269     * <pre>
270     * {@code
271     *  <config>
272     *     <service id="id1" combine.self="OVERRIDABLE_BY_TAG">
273     *         <test/>
274     *     </service>
275     *  </config>
276     * }
277     * </pre>
278     * Second:
279     * <pre>
280     * {@code
281     *  <config>
282     *      <service id="id2"/>
283     *  </config>
284     * }
285     * </pre>
286     * Result:
287     * <pre>
288     * {@code
289     *  <config>
290     *      <service id="id2"/>
291     *  </config>
292     * }
293     * </pre>
294     * </p>
295     */
296    OVERRIDABLE_BY_TAG;
297
298    public static final String ATTRIBUTE_NAME = "combine.self";
299}
300