001    /*
002     * Common usable utilities
003     *
004     * Copyright (c) 2006
005     *   Petr Hadraba <hadrabap@bluetone.cz>
006     *
007     * Author: Petr Hadraba
008     *
009     * --
010     *
011     * XML Utilities
012     */
013    
014    package global.sandbox.xmlutilities;
015    
016    import java.io.BufferedReader;
017    import java.io.File;
018    import java.io.FileNotFoundException;
019    import java.io.IOException;
020    import java.io.InputStream;
021    import java.io.StringReader;
022    import java.util.Map;
023    import javax.xml.namespace.NamespaceContext;
024    
025    import javax.xml.parsers.DocumentBuilder;
026    import javax.xml.parsers.DocumentBuilderFactory;
027    import javax.xml.parsers.ParserConfigurationException;
028    import javax.xml.transform.Source;
029    import javax.xml.transform.Templates;
030    import javax.xml.transform.Transformer;
031    import javax.xml.transform.TransformerConfigurationException;
032    import javax.xml.transform.TransformerException;
033    import javax.xml.transform.TransformerFactory;
034    import javax.xml.transform.dom.DOMSource;
035    import javax.xml.transform.stream.StreamSource;
036    import javax.xml.validation.SchemaFactory;
037    import javax.xml.xpath.XPath;
038    import javax.xml.xpath.XPathExpressionException;
039    import javax.xml.xpath.XPathFactory;
040    import javax.xml.xpath.XPathFactoryConfigurationException;
041    
042    import org.w3c.dom.Document;
043    import org.w3c.dom.Node;
044    import org.w3c.dom.NodeList;
045    import org.xml.sax.InputSource;
046    import org.xml.sax.SAXException;
047    
048    /**
049     * Static version of the XMLUtilities class.
050     * 
051     * @author Petr Hadraba
052     * 
053     * @version 1.1
054     */
055    public abstract class XMLTools {
056        
057        /**
058         * Use this constant, if you want to use internal XMLUtilities for the
059         * static methods
060         */
061        private static final XMLUtilities INTERNAL_XMLUTILITIES = null;
062        
063        /**
064         * stores XMLUtilities object for the static usage
065         */
066        private static XMLUtilities xmlUtilities = null;
067        
068        /**
069         * hidden constructor
070         */
071        protected XMLTools() {
072            super();
073        }
074        
075        /**
076         * converts Document to DOMSource object
077         * 
078         * @param source
079         *            Document XML representation
080         * 
081         * @return converted XML source
082         */
083        public static Source documentToDOMSource(final Document source) {
084            return new DOMSource(source);
085        }
086        
087        /**
088         * converts Document to DOMSource object
089         * 
090         * @param source
091         *            Document XML representation
092         * @param systemId
093         *            system ID
094         * 
095         * @return converted XML source
096         */
097        public static Source documentToDOMSource(final Document source,
098                String systemId) {
099            return new DOMSource(source, systemId);
100        }
101        
102        /**
103         * converst XML Document into String
104         * 
105         * @param source
106         *            Document to convert
107         * @param xmlUtilities
108         *            custom XMLUtilities; can be null
109         * 
110         * @return XML in the String
111         * 
112         * @throws TransformerException
113         * @throws IOException
114         * @throws XPathFactoryConfigurationException
115         * @throws ParserConfigurationException
116         */
117        public static String documentToString(final Document source,
118                final XMLUtilities xmlUtilities) throws TransformerException,
119                IOException, XPathFactoryConfigurationException,
120                ParserConfigurationException {
121            if (xmlUtilities != null) {
122                return xmlUtilities.documentToString(source);
123            }
124            
125            if (XMLTools.xmlUtilities == null) {
126                initializeXMLUtilities();
127            }
128            
129            return XMLTools.xmlUtilities.documentToString(source);
130        }
131        
132        /**
133         * converst XML Document into String
134         * 
135         * @param source
136         *            Document to convert
137         * 
138         * @return XML in the String
139         * 
140         * @throws TransformerException
141         * @throws IOException
142         * @throws XPathFactoryConfigurationException
143         * @throws ParserConfigurationException
144         */
145        public static String documentToString(final Document source)
146                throws TransformerException, IOException,
147                XPathFactoryConfigurationException, ParserConfigurationException {
148            return documentToString(source, INTERNAL_XMLUTILITIES);
149        }
150        
151        /**
152         * evaluates specified XPath expression on specified context node
153         * 
154         * @param query
155         *            XPath expression
156         * @param context
157         *            context node
158         * @param namespaces
159         *            namespace context
160         * @param xmlUtilities
161         *            custom XMLUtilities; can be null
162         * 
163         * @return NodeList or null if no matches
164         * 
165         * @throws XPathExpressionException
166         * @throws TransformerConfigurationException
167         * @throws XPathFactoryConfigurationException
168         * @throws ParserConfigurationException
169         */
170        public static NodeList evaluateXPath(final String query,
171                final Node context, final NamespaceContext namespaces,
172                final XMLUtilities xmlUtilities) throws XPathExpressionException,
173                TransformerConfigurationException,
174                XPathFactoryConfigurationException, ParserConfigurationException {
175            if (xmlUtilities != null) {
176                return xmlUtilities.evaluateXPath(query, context, namespaces);
177            }
178            
179            if (XMLTools.xmlUtilities == null) {
180                initializeXMLUtilities();
181            }
182            
183            return XMLTools.xmlUtilities.evaluateXPath(query, context, namespaces);
184        }
185        
186        /**
187         * evaluates specified XPath expression on specified context node
188         * 
189         * @param query
190         *            XPath expression
191         * @param context
192         *            context node
193         * @param namespaces
194         *            namespace context
195         * 
196         * @return NodeList or null if no matches
197         * 
198         * @throws XPathExpressionException
199         * @throws TransformerConfigurationException
200         * @throws XPathFactoryConfigurationException
201         * @throws ParserConfigurationException
202         */
203        public static NodeList evaluateXPath(final String query, final Node context,
204                final NamespaceContext namespaces) throws XPathExpressionException,
205                TransformerConfigurationException,
206                XPathFactoryConfigurationException, ParserConfigurationException {
207            return evaluateXPath(query, context, namespaces, INTERNAL_XMLUTILITIES);
208        }
209        
210        /**
211         * evaluates specified XPath expression on specified context node
212         * 
213         * @param query
214         *            XPath expression
215         * @param context
216         *            context node
217         * @param xmlUtilities
218         *            custom XMLUtilities; can be null
219         * 
220         * @return NodeList or null if no matches
221         * 
222         * @throws XPathExpressionException
223         * @throws TransformerConfigurationException
224         * @throws XPathFactoryConfigurationException
225         * @throws ParserConfigurationException
226         */
227        public static NodeList evaluateXPath(final String query,
228                final Node context, final XMLUtilities xmlUtilities)
229                throws XPathExpressionException, TransformerConfigurationException,
230                XPathFactoryConfigurationException, ParserConfigurationException {
231            if (xmlUtilities != null) {
232                return xmlUtilities.evaluateXPath(query, context);
233            }
234            
235            if (XMLTools.xmlUtilities == null) {
236                initializeXMLUtilities();
237            }
238            
239            return XMLTools.xmlUtilities.evaluateXPath(query, context);
240        }
241        
242        /**
243         * evaluates specified XPath expression on specified context node
244         * 
245         * @param query
246         *            XPath expression
247         * @param context
248         *            context node
249         * 
250         * @return NodeList or null if no matches
251         * 
252         * @throws XPathExpressionException
253         * @throws TransformerConfigurationException
254         * @throws XPathFactoryConfigurationException
255         * @throws ParserConfigurationException
256         */
257        public static NodeList evaluateXPath(final String query, final Node context)
258                throws XPathExpressionException, TransformerConfigurationException,
259                XPathFactoryConfigurationException, ParserConfigurationException {
260            return evaluateXPath(query, context, INTERNAL_XMLUTILITIES);
261        }
262        
263        /**
264         * evaluates specified XPath expression and returnes first Node if XPath has
265         * matches
266         * 
267         * @param query
268         *            XPath expression
269         * @param context
270         *            context node
271         * @param xmlUtilities
272         *            xustom XMLUtilities; can be null
273         * 
274         * @return first node or null
275         * 
276         * @throws XPathExpressionException
277         * @throws TransformerConfigurationException
278         * @throws XPathFactoryConfigurationException
279         * @throws ParserConfigurationException
280         */
281        public static Node getFirstNodeForXPath(final String query,
282                final Node context, final XMLUtilities xmlUtilities)
283                throws XPathExpressionException, TransformerConfigurationException,
284                XPathFactoryConfigurationException, ParserConfigurationException {
285            if (xmlUtilities != null) {
286                return xmlUtilities.getFirstNodeForXPath(query, context);
287            }
288            
289            if (XMLTools.xmlUtilities == null) {
290                initializeXMLUtilities();
291            }
292            
293            return XMLTools.xmlUtilities.getFirstNodeForXPath(query, context);
294        }
295        
296        /**
297         * evaluates specified XPath expression and returnes first Node if XPath has
298         * matches
299         * 
300         * @param query
301         *            XPath expression
302         * @param context
303         *            context node
304         * 
305         * @return first node or null
306         * 
307         * @throws XPathExpressionException
308         * @throws TransformerConfigurationException
309         * @throws XPathFactoryConfigurationException
310         * @throws ParserConfigurationException
311         */
312        public static Node getFirstNodeForXPath(final String query,
313                final Node context) throws XPathExpressionException,
314                TransformerConfigurationException,
315                XPathFactoryConfigurationException, ParserConfigurationException {
316            return getFirstNodeForXPath(query, context, INTERNAL_XMLUTILITIES);
317        }
318        
319        /**
320         * evaluates specified XPath expression and returnes first Node if XPath has
321         * matches
322         * 
323         * @param query
324         *            XPath expression
325         * @param context
326         *            context node
327         * @param namespaces
328         *            namespace context
329         * @param xmlUtilities
330         *            xustom XMLUtilities; can be null
331         * 
332         * @return first node or null
333         * 
334         * @throws XPathExpressionException
335         * @throws TransformerConfigurationException
336         * @throws XPathFactoryConfigurationException
337         * @throws ParserConfigurationException
338         */
339        public static Node getFirstNodeForXPath(final String query,
340                final Node context, final NamespaceContext namespaces,
341                final XMLUtilities xmlUtilities) throws XPathExpressionException,
342                TransformerConfigurationException,
343                XPathFactoryConfigurationException, ParserConfigurationException {
344            if (xmlUtilities != null) {
345                return xmlUtilities.getFirstNodeForXPath(
346                        query, context, namespaces);
347            }
348            
349            if (XMLTools.xmlUtilities == null) {
350                initializeXMLUtilities();
351            }
352            
353            return XMLTools.xmlUtilities.getFirstNodeForXPath(
354                    query, context, namespaces);
355        }
356        
357        /**
358         * evaluates specified XPath expression and returnes first Node if XPath has
359         * matches
360         * 
361         * @param query
362         *            XPath expression
363         * @param context
364         *            context node
365         * @param namespaces
366         *            namespace context
367         * @return first node or null
368         * 
369         * @throws XPathExpressionException
370         * @throws TransformerConfigurationException
371         * @throws XPathFactoryConfigurationException
372         * @throws ParserConfigurationException
373         */
374        public static Node getFirstNodeForXPath(final String query,
375                final Node context, final NamespaceContext namespaces)
376                throws XPathExpressionException,
377                TransformerConfigurationException,
378                XPathFactoryConfigurationException, ParserConfigurationException {
379            return getFirstNodeForXPath(
380                    query, context, namespaces, INTERNAL_XMLUTILITIES);
381        }
382        
383        /**
384         * initializes XMLUtilities static member for the static usage
385         * 
386         * @throws ParserConfigurationException
387         * @throws XPathFactoryConfigurationException
388         * @throws TransformerConfigurationException
389         */
390        private static void initializeXMLUtilities()
391                throws TransformerConfigurationException,
392                XPathFactoryConfigurationException, ParserConfigurationException {
393            XMLTools.xmlUtilities = new XMLUtilities();
394        }
395        
396        /**
397         * initializes XMLUtilities static member for the static usage using
398         * specified XMLUtilities
399         * 
400         * @param xmlUtilities
401         *            XMLUtilities to use
402         */
403        public static void initializeXMLUtilities(final XMLUtilities xmlUtilities) {
404            if (xmlUtilities == null) {
405                throw new NullPointerException();
406            }
407            
408            XMLTools.xmlUtilities = xmlUtilities;
409        }
410        
411        /**
412         * obtains SchemaFactory object internaly used by the XMLUtilities static
413         * methods
414         * 
415         * @return SchemaFactory object
416         */
417        public static SchemaFactory getInternalSchemaFactory() {
418            if (xmlUtilities == null) {
419                return null;
420            }
421            
422            return xmlUtilities.getSchemaFactory();
423        }
424        
425        /**
426         * obtains DocumentBuilder object internaly used by the XMLUtilities static
427         * methods
428         * 
429         * @return DocumentBuilder object
430         */
431        public static DocumentBuilder getInternalDocumentBuilder() {
432            if (xmlUtilities == null) {
433                return null;
434            }
435            
436            return xmlUtilities.getDocumentBuilder();
437        }
438        
439        /**
440         * obtains TransformerFactory object internaly used by the XMLUtilities
441         * static methods
442         * 
443         * @return TransformerFactory object
444         */
445        public static TransformerFactory getInternalTransformerFactory() {
446            if (xmlUtilities == null) {
447                return null;
448            }
449            
450            return xmlUtilities.getTransformerFactory();
451        }
452        
453        /**
454         * obtains Transformer object internaly used by the XMLUtilities static
455         * methods
456         * 
457         * @return Transformer object
458         */
459        public static Transformer getInternalTransformer() {
460            if (xmlUtilities == null) {
461                return null;
462            }
463            
464            return xmlUtilities.getTransformer();
465        }
466        
467        /**
468         * obtains XPathFactory object internaly used by the XMLUtilities static
469         * methods
470         * 
471         * @return XPathFactory object
472         */
473        public static XPathFactory getInternalXPathFactory() {
474            if (xmlUtilities == null) {
475                return null;
476            }
477            
478            return xmlUtilities.getXPathFactory();
479        }
480        
481        /**
482         * obtains NamespaceContext object internaly used by the XMLUtilities static
483         * methods
484         *
485         * @return NamespaceContext object
486         */
487        public static NamespaceContext getInternalNamespaceContext() {
488            if (xmlUtilities == null) {
489                return null;
490            }
491            
492            return xmlUtilities.getDefaultNamespaceContext();
493        }
494        
495        /**
496         * validates specified XML with the specified XMLScheme
497         * 
498         * @param xmlDocument
499         *            XML document to validate
500         * @param xmlSchema
501         *            XMLSchema
502         * @param xmlUtilities
503         *            specified XMLUtilities. if null, internal will be used
504         * 
505         * @return null if successfull, string with error otherwise
506         * 
507         * @throws TransformerConfigurationException
508         * @throws XPathFactoryConfigurationException
509         * @throws ParserConfigurationException
510         * @throws IOException
511         */
512        public static String validateXmlUsingSchema(final Source xmlDocument,
513                final Source xmlSchema, final XMLUtilities xmlUtilities)
514                throws TransformerConfigurationException,
515                XPathFactoryConfigurationException, ParserConfigurationException,
516                IOException {
517            if (xmlUtilities != null) {
518                return xmlUtilities.validateXmlUsingSchema(xmlDocument, xmlSchema);
519            }
520            
521            if (XMLTools.xmlUtilities == null) {
522                initializeXMLUtilities();
523            }
524            
525            return XMLTools.xmlUtilities.validateXmlUsingSchema(xmlDocument,
526                    xmlSchema);
527        }
528        
529        /**
530         * validates specified XML with the specified XMLScheme
531         * 
532         * @param xmlDocument
533         *            XML document to validate
534         * @param xmlSchema
535         *            XMLSchema
536         * 
537         * @return null if successfull, string with error otherwise
538         * 
539         * @throws TransformerConfigurationException
540         * @throws XPathFactoryConfigurationException
541         * @throws ParserConfigurationException
542         * @throws IOException
543         */
544        public static String validateXmlUsingSchema(final Source xmlDocument,
545                final Source xmlSchema) throws TransformerConfigurationException,
546                XPathFactoryConfigurationException, ParserConfigurationException,
547                IOException {
548            return validateXmlUsingSchema(xmlDocument, xmlSchema,
549                    INTERNAL_XMLUTILITIES);
550        }
551        
552        /**
553         * loads XML from file specified with file name
554         * 
555         * @param fileName
556         *            file to load
557         * @param xmlUtilities
558         *            custom XMLUtilities object; can be null
559         * 
560         * @return Document object
561         * 
562         * @throws FileNotFoundException
563         * @throws IOException
564         * @throws SAXException
565         * @throws TransformerConfigurationException
566         * @throws XPathFactoryConfigurationException
567         * @throws ParserConfigurationException
568         */
569        public static Document loadDocumentFromFile(final String fileName,
570                final XMLUtilities xmlUtilities) throws FileNotFoundException,
571                IOException, SAXException, TransformerConfigurationException,
572                XPathFactoryConfigurationException, ParserConfigurationException {
573            if (xmlUtilities != null) {
574                return xmlUtilities.loadDocumentFromFile(fileName);
575            }
576            
577            if (XMLTools.xmlUtilities == null) {
578                initializeXMLUtilities();
579            }
580            
581            return XMLTools.xmlUtilities.loadDocumentFromFile(fileName);
582        }
583        
584        /**
585         * loads XML from file specified with file name
586         * 
587         * @param fileName
588         *            file to load
589         * 
590         * @return Document object
591         * 
592         * @throws FileNotFoundException
593         * @throws IOException
594         * @throws SAXException
595         * @throws TransformerConfigurationException
596         * @throws XPathFactoryConfigurationException
597         * @throws ParserConfigurationException
598         */
599        public static Document loadDocumentFromFile(final String fileName)
600                throws FileNotFoundException, IOException, SAXException,
601                TransformerConfigurationException,
602                XPathFactoryConfigurationException, ParserConfigurationException {
603            return loadDocumentFromFile(fileName, INTERNAL_XMLUTILITIES);
604        }
605        
606        /**
607         * loads XML from file specified with file name
608         * 
609         * @param fileName
610         *            file to load
611         * @param documentBuilder
612         *            custom DocumentBuilder
613         * @param xmlUtilities
614         *            custom XMLUtilities; can be null
615         * 
616         * @return Document object
617         * 
618         * @throws FileNotFoundException
619         * @throws IOException
620         * @throws SAXException
621         * @throws TransformerConfigurationException
622         * @throws XPathFactoryConfigurationException
623         * @throws ParserConfigurationException
624         */
625        public static Document loadDocumentFromFile(final String fileName,
626                final DocumentBuilder documentBuilder,
627                final XMLUtilities xmlUtilities) throws FileNotFoundException,
628                IOException, SAXException, TransformerConfigurationException,
629                XPathFactoryConfigurationException, ParserConfigurationException {
630            if (xmlUtilities != null) {
631                return xmlUtilities.loadDocumentFromFile(fileName, documentBuilder);
632            }
633            
634            if (XMLTools.xmlUtilities == null) {
635                initializeXMLUtilities();
636            }
637            
638            return XMLTools.xmlUtilities.loadDocumentFromFile(fileName,
639                    documentBuilder);
640        }
641        
642        /**
643         * loads XML from file specified with file name
644         * 
645         * @param fileName
646         *            file to load
647         * @param documentBuilder
648         *            custom DocumentBuilder
649         * 
650         * @return Document object
651         * 
652         * @throws FileNotFoundException
653         * @throws IOException
654         * @throws SAXException
655         * @throws TransformerConfigurationException
656         * @throws XPathFactoryConfigurationException
657         * @throws ParserConfigurationException
658         */
659        public static Document loadDocumentFromFile(final String fileName,
660                final DocumentBuilder documentBuilder)
661                throws FileNotFoundException, IOException, SAXException,
662                TransformerConfigurationException,
663                XPathFactoryConfigurationException, ParserConfigurationException {
664            return loadDocumentFromFile(fileName, documentBuilder,
665                    INTERNAL_XMLUTILITIES);
666        }
667        
668        /**
669         * loads XML from file specified with the File object
670         * 
671         * @param file
672         *            file to load
673         * @param xmlUtilities
674         *            custom XMLUtilities; can be null
675         * 
676         * @return Document object
677         * 
678         * @throws FileNotFoundException
679         * @throws IOException
680         * @throws SAXException
681         * @throws TransformerConfigurationException
682         * @throws XPathFactoryConfigurationException
683         * @throws ParserConfigurationException
684         */
685        public static Document loadDocumentFromFile(final File file,
686                final XMLUtilities xmlUtilities) throws FileNotFoundException,
687                IOException, SAXException, TransformerConfigurationException,
688                XPathFactoryConfigurationException, ParserConfigurationException {
689            if (xmlUtilities != null) {
690                return xmlUtilities.loadDocumentFromFile(file);
691            }
692            
693            if (XMLTools.xmlUtilities == null) {
694                initializeXMLUtilities();
695            }
696            
697            return XMLTools.xmlUtilities.loadDocumentFromFile(file);
698        }
699        
700        /**
701         * loads XML from file specified with the File object
702         * 
703         * @param file
704         *            file to load
705         * 
706         * @return Document object
707         * 
708         * @throws FileNotFoundException
709         * @throws IOException
710         * @throws SAXException
711         * @throws TransformerConfigurationException
712         * @throws XPathFactoryConfigurationException
713         * @throws ParserConfigurationException
714         */
715        public static Document loadDocumentFromFile(final File file)
716                throws FileNotFoundException, IOException, SAXException,
717                TransformerConfigurationException,
718                XPathFactoryConfigurationException, ParserConfigurationException {
719            return loadDocumentFromFile(file, INTERNAL_XMLUTILITIES);
720        }
721        
722        /**
723         * loads XML from file specified with the file object
724         * 
725         * @param file
726         *            fileto load
727         * @param documentBuilder
728         *            custom document builder
729         * @param xmlUtilities
730         *            custom XMLUtilities; can be null
731         * 
732         * @return Document object
733         * 
734         * @throws FileNotFoundException
735         * @throws IOException
736         * @throws SAXException
737         * @throws TransformerConfigurationException
738         * @throws XPathFactoryConfigurationException
739         * @throws ParserConfigurationException
740         */
741        public static Document loadDocumentFromFile(final File file,
742                final DocumentBuilder documentBuilder,
743                final XMLUtilities xmlUtilities) throws FileNotFoundException,
744                IOException, SAXException, TransformerConfigurationException,
745                XPathFactoryConfigurationException, ParserConfigurationException {
746            if (xmlUtilities != null) {
747                return xmlUtilities.loadDocumentFromFile(file, documentBuilder);
748            }
749            
750            if (XMLTools.xmlUtilities == null) {
751                initializeXMLUtilities();
752            }
753            
754            return XMLTools.xmlUtilities
755                    .loadDocumentFromFile(file, documentBuilder);
756        }
757        
758        /**
759         * loads XML from file specified with the file object
760         * 
761         * @param file
762         *            fileto load
763         * @param documentBuilder
764         *            custom document builder
765         * 
766         * @return Document object
767         * 
768         * @throws FileNotFoundException
769         * @throws IOException
770         * @throws SAXException
771         * @throws TransformerConfigurationException
772         * @throws XPathFactoryConfigurationException
773         * @throws ParserConfigurationException
774         */
775        public static Document loadDocumentFromFile(final File file,
776                final DocumentBuilder documentBuilder)
777                throws FileNotFoundException, IOException, SAXException,
778                TransformerConfigurationException,
779                XPathFactoryConfigurationException, ParserConfigurationException {
780            return loadDocumentFromFile(file, documentBuilder,
781                    INTERNAL_XMLUTILITIES);
782        }
783        
784        /**
785         * loads XML from specified stream
786         * 
787         * @param is
788         *            input stream
789         * @param xmlUtilities
790         *            custom XMLUtilities (can be null)
791         * 
792         * @return Document object
793         * 
794         * @throws TransformerConfigurationException
795         * @throws XPathFactoryConfigurationException
796         * @throws ParserConfigurationException
797         * @throws IOException
798         * @throws SAXException
799         */
800        public static Document loadDocumentFromStream(final InputStream is,
801                final XMLUtilities xmlUtilities)
802                throws TransformerConfigurationException,
803                XPathFactoryConfigurationException, ParserConfigurationException,
804                IOException, SAXException {
805            if (xmlUtilities != null) {
806                return xmlUtilities.loadDocumentFromStream(is);
807            }
808            
809            if (XMLTools.xmlUtilities == null) {
810                initializeXMLUtilities();
811            }
812            
813            return XMLTools.xmlUtilities.loadDocumentFromStream(is);
814        }
815        
816        /**
817         * loads XML from specified stream
818         * 
819         * @param is
820         *            input stream
821         * 
822         * @return Document object
823         * 
824         * @throws TransformerConfigurationException
825         * @throws XPathFactoryConfigurationException
826         * @throws ParserConfigurationException
827         * @throws IOException
828         * @throws SAXException
829         */
830        public static Document loadDocumentFromStream(final InputStream is)
831                throws TransformerConfigurationException,
832                XPathFactoryConfigurationException, ParserConfigurationException,
833                IOException, SAXException {
834            return loadDocumentFromStream(is, INTERNAL_XMLUTILITIES);
835        }
836        
837        /**
838         * loads XML from specified input stream
839         * 
840         * @param is
841         *            input stream
842         * @param documentBuilder
843         *            custom Document Builder
844         * @param xmlUtilities
845         *            custom XMLUtilities (can be null)
846         * 
847         * @return Document object
848         * 
849         * @throws TransformerConfigurationException
850         * @throws XPathFactoryConfigurationException
851         * @throws ParserConfigurationException
852         * @throws IOException
853         * @throws SAXException
854         */
855        public static Document loadDocumentFromStream(final InputStream is,
856                final DocumentBuilder documentBuilder,
857                final XMLUtilities xmlUtilities)
858                throws TransformerConfigurationException,
859                XPathFactoryConfigurationException, ParserConfigurationException,
860                IOException, SAXException {
861            if (xmlUtilities != null) {
862                return xmlUtilities.loadDocumentFromStream(is, documentBuilder);
863            }
864            
865            if (XMLTools.xmlUtilities == null) {
866                initializeXMLUtilities();
867            }
868            
869            return XMLTools.xmlUtilities
870                    .loadDocumentFromStream(is, documentBuilder);
871        }
872        
873        /**
874         * loads XML from specified input stream
875         * 
876         * @param is
877         *            input stream
878         * @param documentBuilder
879         *            custom Document Builder
880         * 
881         * @return Document object
882         * 
883         * @throws TransformerConfigurationException
884         * @throws XPathFactoryConfigurationException
885         * @throws ParserConfigurationException
886         * @throws IOException
887         * @throws SAXException
888         */
889        public static Document loadDocumentFromStream(final InputStream is,
890                final DocumentBuilder documentBuilder)
891                throws TransformerConfigurationException,
892                XPathFactoryConfigurationException, ParserConfigurationException,
893                IOException, SAXException {
894            return loadDocumentFromStream(is, documentBuilder,
895                    INTERNAL_XMLUTILITIES);
896        }
897        
898        /**
899         * obtains DocumentBuilderFactory object internaly used by the XMLUtilities
900         * static methods
901         * 
902         * @return DocumentBuilderFactory object
903         */
904        public static DocumentBuilderFactory getInternalDocumentBuilderFactory() {
905            if (xmlUtilities == null) {
906                return null;
907            }
908            
909            return xmlUtilities.getDocumentBuilderFactory();
910        }
911        
912        /**
913         * obtains XPath object internaly used by the XMLUtilities static methods
914         * 
915         * @return XPath object
916         */
917        public static XPath getInternalXPath() {
918            if (xmlUtilities == null) {
919                return null;
920            }
921            
922            return xmlUtilities.getXPath();
923        }
924        
925        /**
926         * transformes specified XML document using specified XSLT template
927         * 
928         * @param xsltTemplate
929         *            template to use
930         * @param document
931         *            source XML document
932         * 
933         * @return resulting document in the <code>String</code>
934         * 
935         * @throws XPathFactoryConfigurationException
936         * @throws ParserConfigurationException
937         * @throws TransformerException
938         */
939        public static String transformToString(final Source xsltTemplate,
940                final Source document) throws XPathFactoryConfigurationException,
941                ParserConfigurationException, TransformerException {
942            return transformToString(xsltTemplate, document,
943                    XMLTools.INTERNAL_XMLUTILITIES);
944        }
945        
946        /**
947         * transformes specified XML document using specified XSLT template
948         * 
949         * @param xsltTemplate
950         *            XSLT template
951         * @param document
952         *            source XML document
953         * @param xmlUtilities
954         *            custom <code>XMLUtilities</code>
955         * 
956         * @return resulting XML document in the <code>String</code>
957         * 
958         * @throws XPathFactoryConfigurationException
959         * @throws ParserConfigurationException
960         * @throws TransformerException
961         */
962        public static String transformToString(final Source xsltTemplate,
963                final Source document, final XMLUtilities xmlUtilities)
964                throws XPathFactoryConfigurationException,
965                ParserConfigurationException, TransformerException {
966            return transformToString(xsltTemplate, document, null, xmlUtilities);
967        }
968        
969        /**
970         * transformes specified XML document using specified XSLT template
971         * 
972         * @param xsltTemplate
973         *            XSLT template to use
974         * @param document
975         *            source XML document
976         * @param parameters
977         *            parameters for the XSLT processor
978         * 
979         * @return resulting XML file in the <code>String</code>
980         * 
981         * @throws XPathFactoryConfigurationException
982         * @throws ParserConfigurationException
983         * @throws TransformerException
984         */
985        public static String transformToString(final Source xsltTemplate,
986                final Source document, final Map<String, Object> parameters)
987                throws XPathFactoryConfigurationException,
988                ParserConfigurationException, TransformerException {
989            return transformToString(xsltTemplate, document, parameters,
990                    XMLTools.INTERNAL_XMLUTILITIES);
991        }
992        
993        /**
994         * transformes specified XML document using specified XSLT template
995         * 
996         * @param xsltTemplate
997         *            XSLT template to use
998         * @param document
999         *            source XML document
1000         * @param parameters
1001         *            parameters for the XSLT processor
1002         * @param xmlUtilities
1003         *            custom <code>XMLUtilities</code> to use
1004         * 
1005         * @return resulting XML document in the <code>String</code>
1006         * 
1007         * @throws XPathFactoryConfigurationException
1008         * @throws ParserConfigurationException
1009         * @throws TransformerException
1010         */
1011        public static String transformToString(final Source xsltTemplate,
1012                final Source document, final Map<String, Object> parameters,
1013                final XMLUtilities xmlUtilities)
1014                throws XPathFactoryConfigurationException,
1015                ParserConfigurationException, TransformerException {
1016            if (xmlUtilities != null) {
1017                return xmlUtilities.transformToString(xsltTemplate, document,
1018                        parameters);
1019            }
1020            
1021            if (XMLTools.xmlUtilities == null) {
1022                initializeXMLUtilities();
1023            }
1024            
1025            return XMLTools.xmlUtilities.transformToString(xsltTemplate, document,
1026                    parameters);
1027        }
1028        
1029        /**
1030         * transforms specified XML document using XSLT (compiled) template
1031         * 
1032         * @param xsltTemplate
1033         *            template to use
1034         * @param document
1035         *            XML document to transform
1036         * @param parameters
1037         *            parameters for the transformation
1038         * @param xmlUtilities
1039         *            custom <code>XMLUtilities</code> to use
1040         * 
1041         * @return resulting XML document in the <code>String</code>
1042         * 
1043         * @throws XPathFactoryConfigurationException
1044         * @throws ParserConfigurationException
1045         * @throws TransformerException
1046         */
1047        public static String transformToString(final Templates xsltTemplate,
1048                final Source document, final Map<String, Object> parameters,
1049                final XMLUtilities xmlUtilities)
1050                throws XPathFactoryConfigurationException,
1051                ParserConfigurationException, TransformerException {
1052            if (xmlUtilities != null) {
1053                return xmlUtilities.transformToString(xsltTemplate, document,
1054                        parameters);
1055            }
1056            
1057            if (XMLTools.xmlUtilities == null) {
1058                initializeXMLUtilities();
1059            }
1060            
1061            return XMLTools.xmlUtilities.transformToString(xsltTemplate, document,
1062                    parameters);
1063        }
1064        
1065        /**
1066         * transforms specified XML document using XSLT (compiled) template
1067         * 
1068         * @param xsltTemplate
1069         *            template to use
1070         * @param document
1071         *            XML document to transform
1072         * @param parameters
1073         *            parameters for the transformation
1074         * 
1075         * @return resulting XML document in the <code>String</code>
1076         * 
1077         * @throws XPathFactoryConfigurationException
1078         * @throws ParserConfigurationException
1079         * @throws TransformerException
1080         */
1081        public static String transformToString(final Templates xsltTemplate,
1082                final Source document, final Map<String, Object> parameters)
1083                throws XPathFactoryConfigurationException,
1084                ParserConfigurationException, TransformerException {
1085            return transformToString(xsltTemplate, document, parameters,
1086                    XMLTools.INTERNAL_XMLUTILITIES);
1087        }
1088        
1089        /**
1090         * transforms specified XML document using XSLT (compiled) template
1091         * 
1092         * @param xsltTemplate
1093         *            template to use
1094         * @param document
1095         *            XML document to transform
1096         * @param xmlUtilities
1097         *            custom <code>XMLUtilities</code> to use
1098         * 
1099         * @return resulting XML in the <code>String</code>
1100         * 
1101         * @throws XPathFactoryConfigurationException
1102         * @throws ParserConfigurationException
1103         * @throws TransformerException
1104         */
1105        public static String transformToString(final Templates xsltTemplate,
1106                final Source document, final XMLUtilities xmlUtilities)
1107                throws XPathFactoryConfigurationException,
1108                ParserConfigurationException, TransformerException {
1109            return transformToString(xsltTemplate, document, null, xmlUtilities);
1110        }
1111        
1112        /**
1113         * transforms specified XML document using XSLT (compiled) template
1114         * 
1115         * @param xsltTemplate
1116         *            template to use
1117         * @param document
1118         *            XML document to transform
1119         * 
1120         * @return resulting XML in the <code>String</code>
1121         * 
1122         * @throws XPathFactoryConfigurationException
1123         * @throws ParserConfigurationException
1124         * @throws TransformerException
1125         */
1126        public static String transformToString(final Templates xsltTemplate,
1127                final Source document) throws XPathFactoryConfigurationException,
1128                ParserConfigurationException, TransformerException {
1129            return transformToString(xsltTemplate, document, null,
1130                    XMLTools.INTERNAL_XMLUTILITIES);
1131        }
1132        
1133        /**
1134         * transforms specified XML document using XSLT (compiled) template
1135         * 
1136         * @param xsltTemplate
1137         *            template to use
1138         * @param document
1139         *            XML document to transform
1140         * @param parameters
1141         *            parameters for the transformation
1142         * @param xmlUtilities
1143         *            custom <code>XMLUtilities</code> to use
1144         * 
1145         * @return resulting XML in the <code>Document</code>
1146         * 
1147         * @throws XPathFactoryConfigurationException
1148         * @throws ParserConfigurationException
1149         * @throws SAXException
1150         * @throws IOException
1151         * @throws TransformerException
1152         */
1153        public static Document transformToDocument(final Templates xsltTemplate,
1154                final Source document, final Map<String, Object> parameters,
1155                final XMLUtilities xmlUtilities)
1156                throws XPathFactoryConfigurationException,
1157                ParserConfigurationException, SAXException, IOException,
1158                TransformerException {
1159            if (xmlUtilities != null) {
1160                return xmlUtilities.transformToDocument(xsltTemplate, document,
1161                        parameters);
1162            }
1163            
1164            if (XMLTools.xmlUtilities == null) {
1165                initializeXMLUtilities();
1166            }
1167            
1168            return XMLTools.xmlUtilities.transformToDocument(xsltTemplate,
1169                    document, parameters);
1170        }
1171        
1172        /**
1173         * transforms specified XML document using XSLT (compiled) template
1174         * 
1175         * @param xsltTemplate
1176         *            template to use
1177         * @param document
1178         *            XML document to transform
1179         * @param parameters
1180         *            parameters for the transformation
1181         * 
1182         * @return resulting XML in the <code>Document</code>
1183         * 
1184         * @throws XPathFactoryConfigurationException
1185         * @throws ParserConfigurationException
1186         * @throws SAXException
1187         * @throws IOException
1188         * @throws TransformerException
1189         */
1190        public static Document transformToDocument(final Templates xsltTemplate,
1191                final Source document, final Map<String, Object> parameters)
1192                throws XPathFactoryConfigurationException,
1193                ParserConfigurationException, SAXException, IOException,
1194                TransformerException {
1195            return transformToDocument(xsltTemplate, document, parameters,
1196                    XMLTools.INTERNAL_XMLUTILITIES);
1197        }
1198        
1199        /**
1200         * transforms specified XML document using XSLT (compiled) template
1201         * 
1202         * @param xsltTemplate
1203         *            template to use
1204         * @param document
1205         *            XML document to transform
1206         * @param xmlUtilities
1207         *            custom <code>XMLUtilities</code> to use
1208         * 
1209         * @return resulting XML in the <code>Document</code>
1210         * 
1211         * @throws XPathFactoryConfigurationException
1212         * @throws ParserConfigurationException
1213         * @throws SAXException
1214         * @throws IOException
1215         * @throws TransformerException
1216         */
1217        public static Document transformToDocument(final Templates xsltTemplate,
1218                final Source document, final XMLUtilities xmlUtilities)
1219                throws XPathFactoryConfigurationException,
1220                ParserConfigurationException, SAXException, IOException,
1221                TransformerException {
1222            return transformToDocument(xsltTemplate, document, null, xmlUtilities);
1223        }
1224        
1225        /**
1226         * transforms specified XML document using XSLT (compiled) template
1227         * 
1228         * @param xsltTemplate
1229         *            template to use
1230         * @param document
1231         *            XML document to transform
1232         * 
1233         * @return resulting XML in the <code>Document</code>
1234         * 
1235         * @throws XPathFactoryConfigurationException
1236         * @throws ParserConfigurationException
1237         * @throws SAXException
1238         * @throws IOException
1239         * @throws TransformerException
1240         */
1241        public static Document transformToDocument(final Templates xsltTemplate,
1242                final Source document) throws XPathFactoryConfigurationException,
1243                ParserConfigurationException, SAXException, IOException,
1244                TransformerException {
1245            return transformToDocument(xsltTemplate, document, null,
1246                    XMLTools.INTERNAL_XMLUTILITIES);
1247        }
1248        
1249        /**
1250         * loads document from <code>String</code> into the <code>Document</code>
1251         * 
1252         * @param source
1253         *            source XML
1254         * 
1255         * @return resulting XML
1256         * 
1257         * @throws TransformerConfigurationException
1258         * @throws XPathFactoryConfigurationException
1259         * @throws ParserConfigurationException
1260         * @throws SAXException
1261         * @throws IOException
1262         */
1263        public static Document loadDocumentFromString(final String source)
1264                throws TransformerConfigurationException,
1265                XPathFactoryConfigurationException, ParserConfigurationException,
1266                SAXException, IOException {
1267            return loadDocumentFromString(source, INTERNAL_XMLUTILITIES);
1268        }
1269        
1270        /**
1271         * loads document from <code>String</code> into the <code>Document</code>
1272         * 
1273         * @param source
1274         *            source XML
1275         * @param xmlUtilities
1276         *            custom <code>XMLUtilities</code> to use
1277         * 
1278         * @return resulting XML
1279         * 
1280         * @throws TransformerConfigurationException
1281         * @throws XPathFactoryConfigurationException
1282         * @throws ParserConfigurationException
1283         * @throws SAXException
1284         * @throws IOException
1285         */
1286        public static Document loadDocumentFromString(final String source,
1287                final XMLUtilities xmlUtilities)
1288                throws TransformerConfigurationException,
1289                XPathFactoryConfigurationException, ParserConfigurationException,
1290                SAXException, IOException {
1291            XMLUtilities xmlUtils;
1292            if (xmlUtilities != null) {
1293                xmlUtils = xmlUtilities;
1294            } else {
1295                if (XMLTools.xmlUtilities == null) {
1296                    initializeXMLUtilities();
1297                }
1298                
1299                xmlUtils = XMLTools.xmlUtilities;
1300            }
1301            
1302            return loadDocumentFromString(source, xmlUtils.getDocumentBuilder());
1303        }
1304        
1305        /**
1306         * loads document from <code>String</code> into the <code>Document</code>
1307         * 
1308         * @param source
1309         *            source XML
1310         * @param documentBuilder
1311         *            custom document builder
1312         * 
1313         * @return resulting XML
1314         * 
1315         * @throws SAXException
1316         * @throws IOException
1317         */
1318        public static Document loadDocumentFromString(final String source,
1319                final DocumentBuilder documentBuilder) throws SAXException,
1320                IOException {
1321            final StringReader sr = new StringReader(source);
1322            final BufferedReader br = new BufferedReader(sr);
1323            final InputSource is = new InputSource(br);
1324            
1325            final Document result = documentBuilder.parse(is);
1326            
1327            br.close();
1328            sr.close();
1329            
1330            return result;
1331        }
1332        
1333        /**
1334         * loads document from <code>String</code> into the <code>Document</code>
1335         * 
1336         * @param source
1337         *            source XML
1338         * @param documentBuilder
1339         *            cutom DocumentBuilder to use
1340         * @param xmlUtilities
1341         *            custom <code>XMLUtilities</code> to use
1342         * 
1343         * @return resulting XML
1344         * 
1345         * @throws TransformerConfigurationException
1346         * @throws XPathFactoryConfigurationException
1347         * @throws ParserConfigurationException
1348         * @throws SAXException
1349         * @throws IOException
1350         */
1351        public static Document loadDocumentFromString(final String source,
1352                final DocumentBuilder documentBuilder,
1353                final XMLUtilities xmlUtilities)
1354                throws TransformerConfigurationException,
1355                XPathFactoryConfigurationException, ParserConfigurationException,
1356                SAXException, IOException {
1357            return loadDocumentFromString(source, xmlUtilities);
1358        }
1359        
1360        /**
1361         * converts XML Source into String
1362         * 
1363         * @param source
1364         *            source Document
1365         * 
1366         * @return XML in the String
1367         * 
1368         * @throws TransformerConfigurationException
1369         * @throws XPathFactoryConfigurationException
1370         * @throws ParserConfigurationException
1371         * @throws IOException
1372         * @throws TransformerException
1373         */
1374        public static String sourceToString(final Source source)
1375                throws TransformerConfigurationException,
1376                XPathFactoryConfigurationException, ParserConfigurationException,
1377                IOException, TransformerException {
1378            return sourceToString(source, XMLTools.INTERNAL_XMLUTILITIES);
1379        }
1380        
1381        /**
1382         * converts XML Source into String
1383         * 
1384         * @param source
1385         *            source Document
1386         * @param xmlUtilities
1387         *            <code>XMLUtilities</code> to use
1388         * 
1389         * @return XML in the String
1390         * 
1391         * @throws TransformerConfigurationException
1392         * @throws XPathFactoryConfigurationException
1393         * @throws ParserConfigurationException
1394         * @throws IOException
1395         * @throws TransformerException
1396         */
1397        public static String sourceToString(final Source source,
1398                final XMLUtilities xmlUtilities)
1399                throws TransformerConfigurationException,
1400                XPathFactoryConfigurationException, ParserConfigurationException,
1401                IOException, TransformerException {
1402            if (xmlUtilities != null) {
1403                return xmlUtilities.sourceToString(source);
1404            }
1405            
1406            if (XMLTools.xmlUtilities == null) {
1407                initializeXMLUtilities();
1408            }
1409            
1410            return XMLTools.xmlUtilities.sourceToString(source);
1411        }
1412        
1413        /**
1414         * transforms specified XML using specified XSLT template
1415         * 
1416         * @param xsltTemplate
1417         *            XSLT template
1418         * @param document
1419         *            source XML document
1420         * @param parameters
1421         *            parameters for the template
1422         * @param xmlUtilities
1423         *            <code>XMLUtilities</code> to use
1424         * @return resulting XML in the <code>Document</code>
1425         * 
1426         * @throws XPathFactoryConfigurationException
1427         * @throws ParserConfigurationException
1428         * @throws SAXException
1429         * @throws IOException
1430         * @throws TransformerException
1431         */
1432        public static Document transformToDocument(final Source xsltTemplate,
1433                final Source document, final Map<String, Object> parameters,
1434                final XMLUtilities xmlUtilities)
1435                throws XPathFactoryConfigurationException,
1436                ParserConfigurationException, SAXException, IOException,
1437                TransformerException {
1438            if (xmlUtilities != null) {
1439                return xmlUtilities.transformToDocument(xsltTemplate, document,
1440                        parameters);
1441            }
1442            
1443            if (XMLTools.xmlUtilities == null) {
1444                initializeXMLUtilities();
1445            }
1446            
1447            return XMLTools.xmlUtilities.transformToDocument(xsltTemplate,
1448                    document, parameters);
1449        }
1450        
1451        /**
1452         * transforms specified XML using specified XSLT template
1453         * 
1454         * @param xsltTemplate
1455         *            XSLT template
1456         * @param document
1457         *            source XML document
1458         * @param parameters
1459         *            parameters for the template
1460         * @return resulting XML in the <code>Document</code>
1461         * 
1462         * @throws XPathFactoryConfigurationException
1463         * @throws ParserConfigurationException
1464         * @throws SAXException
1465         * @throws IOException
1466         * @throws TransformerException
1467         */
1468        public static Document transformToDocument(final Source xsltTemplate,
1469                final Source document, final Map<String, Object> parameters)
1470                throws XPathFactoryConfigurationException,
1471                ParserConfigurationException, SAXException, IOException,
1472                TransformerException {
1473            return transformToDocument(xsltTemplate, document, parameters,
1474                    INTERNAL_XMLUTILITIES);
1475        }
1476        
1477        /**
1478         * transforms specified XML using specified XSLT template
1479         * 
1480         * @param xsltTemplate
1481         *            XSLT template
1482         * @param document
1483         *            source XML document
1484         * @param xmlUtilities
1485         *            <code>XMLUtilities</code> to use
1486         * @return resulting XML in the <code>Document</code>
1487         * 
1488         * @throws XPathFactoryConfigurationException
1489         * @throws ParserConfigurationException
1490         * @throws SAXException
1491         * @throws IOException
1492         * @throws TransformerException
1493         */
1494        public static Document transformToDocument(final Source xsltTemplate,
1495                final Source document, final XMLUtilities xmlUtilities)
1496                throws XPathFactoryConfigurationException,
1497                ParserConfigurationException, SAXException, IOException,
1498                TransformerException {
1499            if (xmlUtilities != null) {
1500                return xmlUtilities.transformToDocument(xsltTemplate, document);
1501            }
1502            
1503            if (XMLTools.xmlUtilities == null) {
1504                initializeXMLUtilities();
1505            }
1506            
1507            return XMLTools.xmlUtilities
1508                    .transformToDocument(xsltTemplate, document);
1509        }
1510        
1511        /**
1512         * transforms specified XML using specified XSLT template
1513         * 
1514         * @param xsltTemplate
1515         *            XSLT template
1516         * @param document
1517         *            source XML document
1518         * @return resulting XML in the <code>Document</code>
1519         * 
1520         * @throws XPathFactoryConfigurationException
1521         * @throws ParserConfigurationException
1522         * @throws SAXException
1523         * @throws IOException
1524         * @throws TransformerException
1525         */
1526        public static Document transformToDocument(final Source xsltTemplate,
1527                final Source document) throws XPathFactoryConfigurationException,
1528                ParserConfigurationException, SAXException, IOException,
1529                TransformerException {
1530            return transformToDocument(xsltTemplate, document,
1531                    INTERNAL_XMLUTILITIES);
1532        }
1533        
1534        /**
1535         * loads XML from String
1536         * 
1537         * @param source
1538         *            source string
1539         * 
1540         * @return XML in the <code>Source</code>
1541         */
1542        public static Source loadSourceFromString(final String source) {
1543            return new StreamSource(new StringReader(source));
1544        }
1545        
1546        /**
1547         * loads XML from String
1548         * 
1549         * @param source
1550         *            source string
1551         * @param systemId
1552         *            system ID
1553         * 
1554         * @return XML in the <code>Source</code>
1555         */
1556        public static Source loadSourceFromString(final String source,
1557                final String systemId) {
1558            return new StreamSource(new StringReader(source), systemId);
1559        }
1560        
1561    }