View Javadoc

1   /*
2    * File:    DOMUtils.java
3    * Created: 16.04.2006 2:12:49 
4    *
5    * Copyright 2006 Michal Burda.
6    *
7    * This program is free software; you can redistribute it and/or modify
8    * it under the terms of the GNU General Public License as published by
9    * the Free Software Foundation; either version 2 of the License, or
10   * (at your option) any later version.
11   *
12   * This program is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15   * GNU General Public License for more details.
16   *
17   * You should have received a copy of the GNU General Public License
18   * along with this program; if not, write to the Free Software
19   * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
20   */
21  package net.sf.webmancer.util.xml.dom;
22  
23  import java.util.Map;
24  import java.util.Map.Entry;
25  
26  import javax.xml.XMLConstants;
27  import javax.xml.namespace.QName;
28  
29  import net.sf.webmancer.util.ContractChecker;
30  
31  import org.w3c.dom.Attr;
32  import org.w3c.dom.Element;
33  import org.w3c.dom.Node;
34  import org.w3c.dom.NodeList;
35  
36  /**
37   * @author michal
38   */
39  public class DOMUtils {
40  
41      /**
42       * 
43       */
44      private DOMUtils() {
45          super();
46      }
47  
48      /**
49       * @param what
50       * @param message
51       * @throws DOMSemanticException
52       */
53      public static void expect(boolean what, final String message) throws DOMSemanticException {
54          if (!what) {
55              throw new DOMSemanticException(message);
56          }
57      }
58  
59      /**
60       * @param element
61       * @return
62       */
63      public static QName getQName(final Element element) {
64          if (element == null) {
65              return null;
66          }
67          return new QName(element.getNamespaceURI(), element.getNodeName());
68      }
69  
70      /**
71       * @param element
72       * @param qName
73       * @return
74       */
75      public static boolean tryQName(final Element element, final QName qName) {
76          ContractChecker.mustNotBeNull(qName, "qName");
77          if (element == null) {
78              return false;
79          }
80          QName realQName = getQName(element);
81          if (!qName.equals(realQName)) {
82              return false;
83          }
84          return true;
85      }
86  
87      /**
88       * @param element
89       * @param qName
90       * @throws DOMSemanticException
91       */
92      public static void expectQName(final Element element, final QName qName) throws DOMSemanticException {
93          if (!tryQName(element, qName)) {
94              QName realQName = getQName(element);
95              throw new DOMSemanticException("Expected '" + qName.toString() + "', but '" + realQName + "' was found");
96          }
97      }
98  
99      /**
100      * @param element
101      * @param childQName
102      * @return
103      */
104     public static NodeList tryChildElements(final Element element, final QName childQName) {
105         ContractChecker.mustNotBeNull(element, "element");
106         ContractChecker.mustNotBeNull(childQName, "childQName");
107         return element.getElementsByTagNameNS(childQName.getNamespaceURI(), childQName.getLocalPart());
108     }
109 
110     /**
111      * @param element
112      * @param childQName
113      * @return
114      * @throws DOMSemanticException
115      */
116     public static NodeList expectChildElements(final Element element, final QName childQName) throws DOMSemanticException {
117         NodeList nl = tryChildElements(element, childQName);
118         expect(nl.getLength() > 0, "At least one '" + childQName.toString() + "' element expected, but none was found");
119         return nl;
120     }
121 
122     /**
123      * @param element
124      * @param childQName
125      * @return
126      * @throws DOMSemanticException
127      */
128     public static Element tryUniqueChildElement(final Element element, final QName childQName) throws DOMSemanticException {
129         NodeList children = tryChildElements(element, childQName);
130         if (children.getLength() > 0) {
131             expect(children.getLength() == 1, "Unexpected many instances of the '" + childQName.toString()
132                     + "' element");
133             Node node = children.item(0);
134             assert node instanceof Element : "tryChildElements() should always return a NodeList full of Element nodes only";
135             return (Element) node;
136         }
137         return null;
138     }
139 
140     /**
141      * @param element
142      * @param childQName
143      * @return
144      * @throws DOMSemanticException
145      */
146     public static Element expectUniqueChildElement(final Element element, final QName childQName) throws DOMSemanticException {
147         Element child = tryUniqueChildElement(element, childQName);
148         expect(child != null, "Unique '" + childQName.toString() + "' expected, but none was found");
149         return child;
150     }
151 
152     /**
153      * @param element
154      * @param childQName
155      * @return
156      * @throws DOMSemanticException
157      */
158     public static String tryUniqueChildElementTextContent(final Element element, final QName childQName)
159             throws DOMSemanticException {
160         Element child = tryUniqueChildElement(element, childQName);
161         if (child == null) {
162             return null;
163         }
164         return child.getTextContent();
165     }
166 
167     /**
168      * @param element
169      * @param childQName
170      * @return
171      * @throws DOMSemanticException
172      */
173     public static String expectUniqueChildElementTextContent(final Element element, final QName childQName)
174             throws DOMSemanticException {
175         String text = tryUniqueChildElementTextContent(element, childQName);
176         expect(text != null, "Non-null text content expected of '" + childQName.toString() + "' element");
177         return text;
178     }
179 
180     /**
181      * @param element
182      * @param childQName
183      * @return
184      * @throws DOMSemanticException
185      */
186     public static String tryUniqueChildElementNonEmptyTextContent(final Element element, final QName childQName)
187             throws DOMSemanticException {
188         String text = tryUniqueChildElementTextContent(element, childQName);
189         if (text == null) {
190             return null;
191         }
192         text = text.trim();
193         if (text.length() <= 0) {
194             return null;
195         }
196         return text;
197     }
198 
199     /**
200      * @param element
201      * @param childQName
202      * @return
203      * @throws DOMSemanticException
204      */
205     public static String expectUniqueChildElementNonEmptyTextContent(final Element element, final QName childQName)
206             throws DOMSemanticException {
207         String str = expectUniqueChildElementTextContent(element, childQName).trim();
208         expect(str.length() > 0, "Expected non-empty string in '" + childQName.toString() + "'");
209         return str;
210     }
211 
212     /**
213      * @param element
214      * @param attributeQName
215      * @return
216      */
217     public static Attr tryAttribute(final Element element, final QName attributeQName) {
218         ContractChecker.mustNotBeNull(element, "element");
219         ContractChecker.mustNotBeNull(attributeQName, "attributeQName");
220         String ns = attributeQName.getNamespaceURI();
221         if (ns == XMLConstants.NULL_NS_URI) {
222             ns = null;
223         }
224         return element.getAttributeNodeNS(ns, attributeQName.getLocalPart());
225     }
226 
227     /**
228      * @param element
229      * @param attributeQName
230      * @return
231      * @throws DOMSemanticException
232      */
233     public static Attr expectAttribute(final Element element, final QName attributeQName) throws DOMSemanticException {
234         Attr a = tryAttribute(element, attributeQName);
235         expect(a != null, "Attribute '" + attributeQName.toString() + "' expected");
236         return a;
237     }
238 
239     /**
240      * @param element
241      * @param attributeQName
242      * @return
243      * @throws DOMSemanticException
244      */
245     public static int expectIntAttributeValue(final Element element, final QName attributeQName) throws DOMSemanticException {
246         Attr attr = expectAttribute(element, attributeQName);
247         try {
248             return Integer.parseInt(attr.getTextContent());
249         } catch (NumberFormatException e) {
250             throw new DOMSemanticException("Integer value expected in '" + attributeQName.toString()
251                     + "' attribute value");
252         }
253 
254     }
255 
256     /**
257      * @param element
258      * @param attributeQName
259      * @return
260      * @throws DOMSemanticException
261      */
262     public static long expectLongAttributeValue(final Element element, final QName attributeQName) throws DOMSemanticException {
263         Attr attr = expectAttribute(element, attributeQName);
264         try {
265             return Long.parseLong(attr.getTextContent());
266         } catch (NumberFormatException e) {
267             throw new DOMSemanticException("Long value expected in '" + attributeQName.toString() + "' attribute value");
268         }
269 
270     }
271 
272     /**
273      * @param element
274      * @param attributeQName
275      * @return
276      * @throws DOMSemanticException
277      */
278     public static float expectFloatAttributeValue(final Element element, final QName attributeQName) throws DOMSemanticException {
279         Attr attr = tryAttribute(element, attributeQName);
280         try {
281             return Float.parseFloat(attr.getTextContent());
282         } catch (NumberFormatException e) {
283             throw new DOMSemanticException("Float value expected in '" + attributeQName.toString()
284                     + "' attribute value");
285         }
286 
287     }
288 
289     /**
290      * @param element
291      * @param attributeQName
292      * @return
293      * @throws DOMSemanticException
294      */
295     public static double expectDoubleAttributeValue(final Element element, final QName attributeQName) throws DOMSemanticException {
296         Attr attr = tryAttribute(element, attributeQName);
297         try {
298             return Double.parseDouble(attr.getTextContent());
299         } catch (NumberFormatException e) {
300             throw new DOMSemanticException("Double value expected in '" + attributeQName.toString()
301                     + "' attribute value");
302         }
303 
304     }
305 
306     /**
307      * @param element
308      * @return
309      * @throws DOMSemanticException
310      */
311     public static int expectIntElementValue(final Element element) throws DOMSemanticException {
312         try {
313             return Integer.parseInt(element.getTextContent());
314         } catch (NumberFormatException e) {
315             throw new DOMSemanticException("Integer value expected in '" + element.toString() + "' element value");
316         }
317 
318     }
319 
320     /**
321      * @param element
322      * @return
323      * @throws DOMSemanticException
324      */
325     public static long expectLongElementValue(final Element element) throws DOMSemanticException {
326         try {
327             return Long.parseLong(element.getTextContent());
328         } catch (NumberFormatException e) {
329             throw new DOMSemanticException("Long value expected in '" + element.toString() + "' element value");
330         }
331 
332     }
333 
334     /**
335      * @param element
336      * @return
337      * @throws DOMSemanticException
338      */
339     public static float expectFloatElementValue(final Element element) throws DOMSemanticException {
340         try {
341             return Float.parseFloat(element.getTextContent());
342         } catch (NumberFormatException e) {
343             throw new DOMSemanticException("Float value expected in '" + element.toString() + "' element value");
344         }
345 
346     }
347 
348     /**
349      * @param element
350      * @return
351      * @throws DOMSemanticException
352      */
353     public static double expectDoubleElementValue(final Element element) throws DOMSemanticException {
354         try {
355             return Double.parseDouble(element.getTextContent());
356         } catch (NumberFormatException e) {
357             throw new DOMSemanticException("Double value expected in '" + element.toString() + "' element value");
358         }
359     }
360 
361     /**
362      * @param parent
363      * @param attributes
364      */
365     public static void addAttributes(Element parent, Map<String, String> attributes) {
366         ContractChecker.mustNotBeNull(parent, "parent");
367         ContractChecker.mustNotBeNull(attributes, "attributes");
368         for (Entry<String, String> e : attributes.entrySet()) {
369             parent.setAttribute(e.getKey(), e.getValue());
370         }
371     }
372 }