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.config.xmlmerge;
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 tag name and 'id' attribute and combined recursively.
025     * 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 similar to {@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    public static final String ATTRIBUTE_NAME = "combine.self";
186}
187