Mapper


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.bridge;
24  
25  import java.sql.Connection  ;
26  
27  import org.xml.sax.ContentHandler  ;
28  import org.xml.sax.ErrorHandler  ;
29  import org.xquark.xml.xdbc.XMLDBCException;
30  import org.xquark.xml.xdbc.XMLErrorHandler;
31  
32  /**
33   * Objects implementing this class are used to store XML data
34   * into a database according to the parent mapping.<BR>
35   * An object of this class cannot be used in multiple threads concurrently.
36   * Different Mappers can be used concurrently by different threads.<BR>
37   * A Mapper may be used multiple times, to store several documents based
38   * on the same mapping.<BR>
39   * A Mapper provides three different interfaces to store XML data: the most
40   * efficient is based on SAX2, as the Mapper can be plugged directly as a
41   * org.xml.sax.ContentHandler into any XML parser implementing the org.xml.sax.XMLReader
42   * interface. <B>Note that with this method the error handler must also be
43   * plugged so that the mapper can have a consistent behavior in case of parsing
44   * error due to a malformed XML document (perform a rollback).</B>
45   * For convenience, a DOM2-based and a string-based interfaces are also
46   * provided.<BR>
47   * A Mapper object must be explicitly closed after use, in order to free its associated database
48   * resources.
49   * @see org.xml.sax.XMLReader
50   */
51  public interface Mapper extends ContentHandler  , ErrorHandler  
52  {
53      public static final String    RCSRevision     = "$Revision: 1.4 $";
54      public static final String    RCSName         = "$Name:  $";
55      
56      /**
57       * Returns the mapping used by this object
58       * @return the parent mapping
59       */
60      public Mapping getMapping();
61      
62      /**
63       * Closes the object and frees its associated resources.
64       * @throws XMLDBCException if a data source access error occurs.
65       */
66      public void close() throws XMLDBCException;
67      
68      /**
69       * Inserts an XML document in the database using the SAX method.
70       * The SAX parser is automatically allocated using JAXP.
71       * @param input the SAX InputSource.
72       * @throws XMLDBCException if a data source access error occurs.
73       * @throws SAXException if a parsing error occurs.
74       */
75      public void insertDocument(org.xml.sax.InputSource   input)
76      throws XMLDBCException, org.xml.sax.SAXException  ;
77      
78      /**
79       * Inserts an XML document in database using the SAX method.
80       * @param parser the SAX 2 XMLReader implementation.
81       * @param input the SAX InputSource.
82       * @throws XMLDBCException if a data source access error occurs.
83       * @throws SAXException if a parsing error occurs.
84       */
85      public void insertDocument(org.xml.sax.XMLReader   parser, org.xml.sax.InputSource   input)
86      throws XMLDBCException, org.xml.sax.SAXException  ;
87      
88      /**
89       * Inserts the XML data contained in the DOM2 document in the database.
90       * @param doc the XML document as a DOM2 org.w3c.dom.Document.
91       * @throws XMLDBCException if a data source access error occurs.
92       */
93      public void insertDocument(org.w3c.dom.Document   doc) throws XMLDBCException;
94      
95      /**
96       * Inserts the XML data contained in the string in the database.
97       * @param doc a string containing the XML document.
98       * @throws XMLDBCException if a data source access error occurs.
99       * @throws org.xml.sax.SAXException if a parse exception occurs.
100      */
101     public void insertDocument(String   doc) throws XMLDBCException, org.xml.sax.SAXException  ;
102     
103     /**
104      * Return the JDBC connection used by this object. It can be used to perform
105      * custom queries in the relational database.
106      *
107      * @return A JDBC connection.
108      */
109     public Connection   getConnection();
110     
111     /**
112      * Return the current error handler.
113      *
114      * @return The current error handler, or null if none
115      *         has been registered.
116      * @see #setErrorHandler
117      */
118     public XMLErrorHandler getErrorHandler();
119     
120   /**
121    * Allows an application to register an error event handler for non-fatal
122    * errors.
123    *
124    * <p>If the application does not register an error handler, all warning
125    * and non-fatal error events reported by the filer will be silently
126    * ignored and storage will continue.</p>
127    *
128    * <p>Applications may register a new or different handler in the
129    * middle of a storage operation, and the filer must begin using the new
130    * handler immediately.</p>
131    *
132    * @param handler The error handler.
133    * @exception java.lang.NullPointerException If the handler 
134    *            argument is null.
135    * @see #getErrorHandler
136    */
137     public void setErrorHandler(XMLErrorHandler handler);
138   
139   /**
140    * This method is to be used when the document stored contains an 'xsi:schemaLocation'
141    * attribute (or any element or attribute with the XML Schema type 'anyURI')
142    * that uses relatives URIs and when the API used to store documents does not
143    * use an InputSource with the SystemID set (e.g. DOM or String ones). The document
144    * base provided is then used to resolve the relative URI into an absolute one.
145    *
146    * @param URI The URI to be used as base during document storage.
147    * @see #getDocumentBase
148    */
149     public void setDocumentBase(String   URI);
150   
151   /**
152    * Retrieves the current document base used by this object.
153    *
154    * @return an URI.
155    * @see #setDocumentBase(String)
156    */
157     public String   getDocumentBase();
158   
159   /**
160    * Turns on or off the automatic buffering mode. If this mode is off
161    * XML documents are buffered until the flushBuffer() method is
162    * called, providing a kind of 'manual' mode for controlling data flush.
163    * If the automatic mode is on (the default) data is automatically flushed after
164    * each document insertion.
165    * <p><b>Important note: </b>The manual mode is only useful if the JDBC connection
166    * autoCommit mode is false (otherwise, a flushBuffer() and commit() are automatically
167    * called at the end of each document insertion, regardless of the autoFlush mode). When
168    * both autoCommit and autoFlush are turned off, the user MUST call flushBuffer() before
169    * committing the changes. 
170    * @param activated 'true' is the default and means that autoflush is on.
171    * @throws XMLDBCException if a data source access error occurs.
172    */
173   public void setAutoFlush(boolean activated) throws XMLDBCException;
174   
175   /**
176    * Retrieves the current buffering mode.
177    * @see #setAutoFlush(boolean)
178    * @return true if the 'automatic' buffering mode is activated.
179    */
180   public boolean getAutoFlush();
181   
182   /**
183    * Sends buffered XML data to the data source. This method is to be called
184    * only when the automatic buffering mode is off.
185    * @see #setAutoFlush(boolean)
186    * @throws XMLDBCException if a data source access error occurs.
187    */
188   public void flushBuffer() throws XMLDBCException;
189 
190   /**
191    * Discards the XML data buffered by the filer since the last call to
192    * flushBuffer() method. This method is to be called only when the automatic
193    * buffering mode is off.
194    * @see #setAutoFlush(boolean)
195    * @throws XMLDBCException if a data source access error occurs.
196    */
197   public void clearBuffer() throws XMLDBCException;
198 
199 }
200 
201 
202
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags