KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xquark > xml > xdbc > XMLDocumentFiler


1 /*
2  * This file belongs to the XQuark distribution.
3  * Copyright (C) 2003 Universite de Versailles Saint-Quentin.
4  *
5  * This program is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this program; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307.
18  * You can also get it at http://www.gnu.org/licenses/lgpl.html
19  *
20  * For more information on this software, see http://www.xquark.org.
21  */

22
23 package org.xquark.xml.xdbc;
24
25 /**
26  * This interface is used to insert XML documents in XML collections.
27  * A single filer can store several documents sequentially, however it is an
28  * error to try to use a filer before the current storage is finished.
29  * Objects implementing this interface can be plugged into a SAX2 XMLReader
30  * to process XML data as SAX2 events. Both org.xml.sax.ContentHandler,
31  * org.xml.sax.ext.LexicalHandler and org.xml.sax.ErrorHandler are supported,
32  * so that comments and processing instructions are not lost during storage.
33  * <p><B>Notes:</B></p>
34  * <ol>
35  * <li>The error handler must absolutely be plugged so that the
36  * application could have a consistent behavior in case of parsing error due to
37  * to a malformed XML document.</li>
38  * <li>This object is likely to use resources that can be released using the
39  * {@link #close()} method.</li>
40  * </ol>
41  */

42
43 public interface XMLDocumentFiler
44 extends org.xml.sax.ContentHandler JavaDoc, org.xml.sax.ErrorHandler JavaDoc,
45         org.xml.sax.ext.LexicalHandler JavaDoc, Configurable
46    {
47  
48
49
50   /**
51    * Closes the object and frees its associated resources.
52    * @throws XMLDBCException if a data source access error occurs.
53    */

54   public void close() throws XMLDBCException;
55   
56   /**
57    * Returns the XML collection that produced this object.
58    * @return the XML collection that produced this object.
59    */

60   public XMLCollection getCollection();
61   
62   /**
63    * Sets the identifier of the next document to be stored through this object.
64    * The identifier is reset to null after each storage.
65    * @param id the identifier of the next document to be stored.
66    * @throws XMLDBCException if a data source access error occurs.
67    */

68   public void setDocumentId(String JavaDoc id) throws XMLDBCException;
69
70   /**
71    * Gets the identifier to be used by the next document to be stored through this object.
72    * If this is null, an internal identifier will be used.
73    * @return the identifier to be used by the next document to be stored.
74    */

75   public String JavaDoc getDocumentId();
76   
77   /**
78    * Inserts an XML document in the filer's collection using the SAX method.
79    * The SAX parser is automatically allocated using JAXP. This method uses the
80    * identifier stored through the setDocumentId() method if available, or an
81    * internal identifier otherwise.
82    * @param input the SAX InputSource.
83    * @return the stored XML document.
84    * @throws XMLDBCException if a data source access error occurs.
85    * @throws org.xml.sax.SAXException if a parse exception occurs.
86    */

87   public XMLDocument insertDocument(org.xml.sax.InputSource JavaDoc input) throws XMLDBCException, org.xml.sax.SAXException JavaDoc;
88   
89   /**
90    * Inserts an XML document in the filer's collection using the SAX method.
91    * The SAX parser is automatically allocated using JAXP.
92    * @param input the SAX InputSource.
93    * @param id the document identifier in the collection.
94    * @return the stored XML document.
95    * @throws XMLDBCException if a data source access error occurs.
96    * @throws org.xml.sax.SAXException if a parse exception occurs.
97    */

98   public XMLDocument insertDocument(org.xml.sax.InputSource JavaDoc input, String JavaDoc id) throws XMLDBCException, org.xml.sax.SAXException JavaDoc;
99   
100   /**
101    * Inserts an XML document in the filer's collection using the SAX method.
102    * This method uses the identifier stored through the setDocumentId() method
103    * if available, or an internal identifier otherwise.
104    * @param parser the SAX 2 XMLReader implementation.
105    * @param input the SAX InputSource.
106    * @return the stored XML document.
107    * @throws XMLDBCException if a data source access error occurs.
108    * @throws org.xml.sax.SAXException if a parse exception occurs.
109    */

110   public XMLDocument insertDocument(org.xml.sax.XMLReader JavaDoc parser, org.xml.sax.InputSource JavaDoc input) throws XMLDBCException, org.xml.sax.SAXException JavaDoc;
111   
112   /**
113    * Inserts an XML document in the filer's collection using the SAX method.
114    * @param parser the SAX 2 XMLReader implementation.
115    * @param input the SAX InputSource.
116    * @param id the document identifier in the collection.
117    * @return the stored XML document.
118    * @throws XMLDBCException if a data source access error occurs.
119    * @throws org.xml.sax.SAXException if a parse exception occurs.
120    */

121   public XMLDocument insertDocument(org.xml.sax.XMLReader JavaDoc parser, org.xml.sax.InputSource JavaDoc input, String JavaDoc id) throws XMLDBCException, org.xml.sax.SAXException JavaDoc;
122    
123     /**
124    * Inserts the XML document in the filer's collection. This method uses the identifier
125    * stored through the setDocumentId() method if available, or an internal identifier
126    * otherwise.
127    * @param doc the XML document as a DOM2 org.w3c.dom.Document.
128    * @return the stored XML document.
129    * @throws XMLDBCException if a data source access error occurs.
130    */

131   public XMLDocument insertDocument(org.w3c.dom.Document JavaDoc doc) throws XMLDBCException;
132   
133   /**
134    * Inserts the XML document in the filer's collection with the specified identifier.
135    * @param doc the XML document as a DOM2 org.w3c.dom.Document.
136    * @param id the document identifier in the collection.
137    * @return the stored XML document.
138    * @throws XMLDBCException if a data source access error occurs.
139    */

140   public XMLDocument insertDocument(org.w3c.dom.Document JavaDoc doc, String JavaDoc id) throws XMLDBCException;
141
142   /**
143    * Inserts the XML document contained in the string in the filer's collection.
144    * This method uses the identifier stored through the setDocumentId() method
145    * if available, or an internal identifier otherwise.
146    * @param doc a string containing the XML document.
147    * @return the stored XML document.
148    * @throws XMLDBCException if a data source access error occurs.
149    * @throws org.xml.sax.SAXException if a parse exception occurs.
150    */

151   public XMLDocument insertDocument(String JavaDoc doc) throws XMLDBCException, org.xml.sax.SAXException JavaDoc;
152   
153   /**
154    * Inserts the XML document contained in the string in the filer's collection
155    * with the specified identifier.
156    * @param doc a string containing the XML document.
157    * @param id the document identifier in the collection.
158    * @return the stored XML document.
159    * @throws XMLDBCException if a data source access error occurs.
160    * @throws org.xml.sax.SAXException if a parse exception occurs.
161    */

162   public XMLDocument insertDocument(String JavaDoc doc, String JavaDoc id) throws XMLDBCException, org.xml.sax.SAXException JavaDoc;
163   
164   /**
165    * Turns on or off the automatic buffering mode. If this mode is off
166    * XML documents are buffered by the filer until the flushBuffer() method is
167    * called providing a kind of 'manual' mode for controlling data flush.
168    * If the batch mode is on (the default) data is automatically flushed when
169    * a certain amount of data is reached or when a commit is performed on the
170    * connection.
171    * @param activated 'true' is the default and means that autoflush is on.
172    * @throws XMLDBCException if a data source access error occurs.
173    */

174   public void setAutoFlush(boolean activated) throws XMLDBCException;
175   
176   /**
177    * Retrieves the current buffering mode.
178    * @see #setAutoFlush(boolean)
179    * @return true if the 'automatic' buffering mode is activated.
180    */

181   public boolean getAutoFlush();
182   
183   /**
184    * Sends buffered XML data to the data source. This method is to be called
185    * only when the automatic buffering mode is off.
186    * @see #setAutoFlush(boolean)
187    * @throws XMLDBCException if a data source access error occurs.
188    */

189   public void flushBuffer() throws XMLDBCException;
190
191   /**
192    * Discards the XML data buffered by the filer since the last call to
193    * flushBuffer() method. This method is to be called only when the automatic
194    * buffering mode is off.
195    * @see #setAutoFlush(boolean)
196    * @throws XMLDBCException if a data source access error occurs.
197    */

198     public void clearBuffer() throws XMLDBCException;
199
200     /**
201      * Allow an application to register an error event handler for non-fatal
202      * errors.
203      *
204      * <p>If the application does not register an error handler, all warning
205      * and non-fatal error events reported by the filer will be silently
206      * ignored and storage will continue.</p>
207      *
208      * <p>Applications may register a new or different handler in the
209      * middle of a storage operation, and the filer must begin using the new
210      * handler immediately.</p>
211      *
212      * @param handler The error handler.
213      * @exception java.lang.NullPointerException If the handler
214      * argument is null.
215      * @see #getErrorHandler
216      */

217     public void setErrorHandler (XMLErrorHandler handler);
218
219
220     /**
221      * Return the current error handler.
222      *
223      * @return The current error handler, or null if none
224      * has been registered.
225      * @see #setErrorHandler
226      */

227     public XMLErrorHandler getErrorHandler ();
228 }
229
Popular Tags