View Javadoc

1   /*
2    * Copyright (C) 2004 Christian Siefkes <christian@siefkes.net>.
3    * Development of this software is supported by the German Research Society,
4    * Berlin-Brandenburg Graduate School in Distributed Information Systems
5    * (DFG grant no. GRK 316).
6    *
7    * This library is free software; you can redistribute it and/or
8    * modify it under the terms of the GNU Lesser General Public
9    * License as published by the Free Software Foundation; either
10   * version 2.1 of the License, or (at your option) any later version.
11   *
12   * This library 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 GNU
15   * Lesser General Public License for more details.
16   *
17   * You should have received a copy of the GNU Lesser General Public
18   * License along with this library; if not, visit
19   * http://www.gnu.org/licenses/lgpl.html or write to the Free Software
20   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
21   */
22  package de.fu_berlin.ties.xml.io;
23  
24  import java.io.IOException;
25  import java.io.InputStream;
26  import java.io.OutputStream;
27  import java.io.Reader;
28  import java.io.Writer;
29  
30  import org.dom4j.Document;
31  import org.dom4j.DocumentException;
32  
33  /***
34   * Interface for classes that support reading and writing XML documents.
35   *
36   * @author Christian Siefkes
37   * @version $Revision: 1.1 $, $Date: 2004/12/09 18:10:52 $, $Author: siefkes $
38   */
39  public interface DocumentSerializer {
40  
41      /***
42       * Reads an XML document from a given reader. <strong>Typically a stream
43       * should be used instead ({@link #readDocument(InputStream)}) to ensure
44       * that encoding issues are handled correctly.</strong>
45       *
46       * @param reader reader containing the text to parse; not closed by this
47       * method
48       * @return the newly created document
49       * @throws DocumentException if an error occurs during parsing
50       * @throws IOException if an I/O error occurrs
51       */
52      Document readDocument(final Reader reader)
53      throws DocumentException, IOException;
54  
55      /***
56       * Reads an XML document from a given stream.
57       *
58       * @param in stream containing the text to parse; not closed by this method
59       * @return the newly created document
60       * @throws DocumentException if an error occurs during parsing
61       * @throws IOException if an I/O error occurrs
62       */
63      Document readDocument(final InputStream in)
64      throws DocumentException, IOException;
65  
66      /***
67       * Writes an XML document to a given writer. <strong>Typically a stream
68       * should be used instead ({@link #writeDocument(Document, OutputStream)})
69       * to ensure that encoding issues are handled correctly.</strong>
70       *
71       * @param document the document to write
72       * @param writer the writer to write the document text to; flushed
73       * but not closed by this method
74       * @throws IOException if an I/O error occurrs
75       */
76      void writeDocument(final Document document, final Writer writer)
77      throws IOException;
78  
79      /***
80       * Writes an XML document to a given stream .
81       *
82       * @param document the document to write
83       * @param out the stream to write the document text to; flushed
84       * but not closed by this method
85       * @throws IOException if an I/O error occurs during writing
86       */
87      Document writeDocument(final Document document, final OutputStream out)
88      throws IOException;
89  
90  }