001/*
002 * NodeBuilder.java July 2006
003 *
004 * Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
015 * implied. See the License for the specific language governing 
016 * permissions and limitations under the License.
017 */
018
019package org.simpleframework.xml.stream;
020
021import java.io.InputStream;
022import java.io.Reader;
023import java.io.Writer;
024
025/**
026 * The <code>NodeBuilder</code> object is used to create either an
027 * input node or an output node for a given source or destination. 
028 * If an <code>InputNode</code> is required for reading an XML
029 * document then a reader must be provided to read the content from.
030 * <p>
031 * If an <code>OutputNode</code> is required then a destination is
032 * required. The provided output node can be used to generate well
033 * formed XML to the specified writer. 
034 * 
035 * @author Niall Gallagher
036 */ 
037public final class NodeBuilder {
038 
039   /**
040    * This is the XML provider implementation that creates readers.
041    */         
042   private static Provider PROVIDER;
043
044   static {
045      PROVIDER = ProviderFactory.getInstance();                    
046   }
047
048   /**
049    * This is used to create an <code>InputNode</code> that can be 
050    * used to read XML from the specified stream. The stream will
051    * be positioned at the root element in the XML document.
052    *
053    * @param source this contains the contents of the XML source
054    *
055    * @throws Exception thrown if there is an I/O exception
056    */   
057   public static InputNode read(InputStream source) throws Exception {
058      return read(PROVIDER.provide(source));   
059   }
060        
061   /**
062    * This is used to create an <code>InputNode</code> that can be 
063    * used to read XML from the specified reader. The reader will
064    * be positioned at the root element in the XML document.
065    *
066    * @param source this contains the contents of the XML source
067    *
068    * @throws Exception thrown if there is an I/O exception
069    */   
070   public static InputNode read(Reader source) throws Exception {
071      return read(PROVIDER.provide(source));   
072   }
073
074   /**
075    * This is used to create an <code>InputNode</code> that can be 
076    * used to read XML from the specified reader. The reader will
077    * be positioned at the root element in the XML document.
078    *
079    * @param source this contains the contents of the XML source
080    *
081    * @throws Exception thrown if there is an I/O exception
082    */     
083   private static InputNode read(EventReader source) throws Exception {
084      return new NodeReader(source).readRoot();           
085   }
086   
087   /**
088    * This is used to create an <code>OutputNode</code> that can be
089    * used to write a well formed XML document. The writer specified
090    * will have XML elements, attributes, and text written to it as
091    * output nodes are created and populated.
092    * 
093    * @param result this contains the result of the generated XML
094    *
095    * @throws Exception this is thrown if there is an I/O error
096    */ 
097   public static OutputNode write(Writer result) throws Exception {
098      return write(result, new Format());
099   }
100
101   /**
102    * This is used to create an <code>OutputNode</code> that can be
103    * used to write a well formed XML document. The writer specified
104    * will have XML elements, attributes, and text written to it as
105    * output nodes are created and populated.
106    * 
107    * @param result this contains the result of the generated XML
108    * @param format this is the format to use for the document
109    *
110    * @throws Exception this is thrown if there is an I/O error
111    */ 
112   public static OutputNode write(Writer result, Format format) throws Exception {
113      return new NodeWriter(result, format).writeRoot();
114   }   
115}