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  , org.xml.sax.ErrorHandler  ,
45          org.xml.sax.ext.LexicalHandler  , 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   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   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   input) throws XMLDBCException, org.xml.sax.SAXException  ;
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   input, String   id) throws XMLDBCException, org.xml.sax.SAXException  ;
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   parser, org.xml.sax.InputSource   input) throws XMLDBCException, org.xml.sax.SAXException  ;
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   parser, org.xml.sax.InputSource   input, String   id) throws XMLDBCException, org.xml.sax.SAXException  ;
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   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   doc, String   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   doc) throws XMLDBCException, org.xml.sax.SAXException  ;
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   doc, String   id) throws XMLDBCException, org.xml.sax.SAXException  ;
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags