PreparedXMLStatement


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  import java.io.InputStream  ;
26  import java.math.BigDecimal  ;
27  import java.util.Date  ;
28  import java.util.List  ;
29  
30  import javax.xml.namespace.QName  ;
31  
32  
33  /**
34   * This prepared statement interface is used for executing parameterized XQuery
35   * or XPath prepared statements, setting external variables and obtaining the
36   * results (update statements are not supported yet).<BR>
37   * Prepared statements allow queries precompilation by the driver.<BR>
38   * <p>In order to binds external variables, two kinds of methods are available:</p>
39   * <ul>
40   * <li>{@link #setExternalVariable(String, String, String)} assumes that the
41   * value be parsed and validated.</li>
42   * <li>setXXX() methods assumes that values passed match the variable primitive
43   * type. These methods are supposed to be more efficient since validation only
44   * consist in checking facets avoiding object allocation.</li>
45   * </ul>
46   */
47  public interface PreparedXMLStatement extends XMLStatement {
48  
49      
50      /*********************************************************************/
51      /*************************** Parameters management *******************/
52      /*********************************************************************/
53  
54      /**
55       * Binds the specified external variable to the current query of the
56       * statement. Variable value will be parsed and validated.
57       * @param ns The namespace of the external variable. Possibly an empty
58       * string if the variable has no namespace.
59       * @param varName local name of the external variable. Must not be null.
60       * @param value a string that is the value to set for the variable.
61       * @throws XMLDBCException if a data source access error occurs.
62       */
63      public void setExternalVariable(String   ns, String   varName, String   value)
64      throws XMLDBCException;
65  
66      /**
67       * Binds the specified external variable to the current query of the
68       * statement. Variable value will be parsed and validated.
69       * @param varName local name of the external variable. Must not be null.
70       * @param value a string that is the value to set for the variable.
71       * @throws XMLDBCException if a data source access error occurs.
72       */
73      public void setExternalVariable(String   varName, String   value)
74      throws XMLDBCException;
75  
76      /**
77       * To set the specified variable with a value inside an object. This method
78       * has to be used for instance when you own a java object instead of a
79       * corresponding primitive type (e.g. Boolean instead of boolean, Long
80       * instead of long, etc.).
81       * @param ns The namespace of the external variable. Possibly an empty
82       * string if the variable has no namespace.
83       * @param varName local name of the external variable. Must not be null.
84       * @param value an object that is the value to set for the parameter.
85       * @throws XMLDBCException if a data source access error occurs.
86       */
87      public void setObject(String   ns, String   varName, Object   value)
88      throws XMLDBCException;
89  
90      /**
91       * To set the specified variable with a value inside an object. This method
92       * has to be used for instance when you own a java object instead of a
93       * corresponding primitive type (e.g. Boolean instead of boolean, Long
94       * instead of long, etc.).
95       * @param varName local name of the external variable. Must not be null.
96       * @param value an object that is the value to set for the parameter.
97       * @throws XMLDBCException if a data source access error occurs.
98       */
99      public void setObject(String   varName, Object   value)
100     throws XMLDBCException;
101 
102     /**
103      * To set the specified variable with a @link java.math.BigDecimal value.
104      * To be used with XML types derived from <code>decimal</code>.
105      * @param ns The namespace of the external variable. Possibly an empty
106      * string if the variable has no namespace.
107      * @param varName local name of the external variable. Must not be null.
108      * @param value a @link java.math.BigDecimal that is the value to set for
109      * the variable.
110      * @throws XMLDBCException if a data source access error occurs.
111      */
112     public void setBigDecimal(String   ns, String   varName, BigDecimal   value)
113     throws XMLDBCException;
114 
115     /**
116      * To set the specified variable with a @link java.math.BigDecimal value.
117      * To be used with XML types derived from <code>decimal</code>.
118      * @param varName local name of the external variable. Must not be null.
119      * @param value a @link java.math.BigDecimal that is the value to set for
120      * the variable.
121      * @throws XMLDBCException if a data source access error occurs.
122      */
123     public void setBigDecimal(String   varName, BigDecimal   value)
124     throws XMLDBCException;
125 
126     /**
127      * To set the specified variable with a @link java.io.InputStream value.
128      * To be used with XML types derived from <code>Base64Binary</code> or 
129      * <code>HexBinary</code>.
130      * @param ns The namespace of the external variable. Possibly an empty
131      * string if the variable has no namespace.
132      * @param varName local name of the external variable. Must not be null.
133      * @param value an input stream.
134      * @param length the length of given input stream.
135      * @throws XMLDBCException if a data source access error occurs.
136      */
137     public void setInputStream(String   ns, String   varName, InputStream   value, int length)
138     throws XMLDBCException;
139 
140     /**
141      * To set the specified variable with a @link java.io.InputStream value.
142      * To be used with XML types derived from <code>Base64Binary</code> or 
143      * <code>HexBinary</code>.
144      * @param varName local name of the external variable. Must not be null.
145      * @param value an input stream.
146      * @param length the length of given input stream.
147      * @throws XMLDBCException if a data source access error occurs.
148      */
149     public void setInputStream(String   varName, InputStream   value, int length)
150     throws XMLDBCException;
151 
152     /**
153      * To set the specified variable with a byte array value. To be used with
154      * XML types derived from <code>Base64Binary</code> or <code>HexBinary</code>.
155      * @param ns The namespace of the external variable. Possibly an empty
156      * string if the variable has no namespace.
157      * @param varName local name of the external variable. Must not be null.
158      * @param value a byte array that is the value to set for the parameter.
159      * @throws XMLDBCException if a data source access error occurs.
160      */
161     public void setBytes(String   ns, String   varName, byte[] value)
162     throws XMLDBCException;
163 
164     /**
165      * To set the specified variable with a byte array value. To be used with
166      * XML types derived from <code>Base64Binary</code> or <code>HexBinary</code>.
167      * @param varName local name of the external variable. Must not be null.
168      * @param value a byte array that is the value to set for the parameter.
169      * @throws XMLDBCException if a data source access error occurs.
170      */
171     public void setBytes(String   varName, byte[] value)
172     throws XMLDBCException;
173 
174     /**
175      * To set the specified variable with a boolean value. To be used with XML
176      * types derived from <code>boolean</code>.
177      * @param ns The namespace of the external variable. Possibly an empty
178      * string if the variable has no namespace.
179      * @param varName local name of the external variable. Must not be null.
180      * @param value a boolean that is the value to set for the parameter.
181      * @throws XMLDBCException if a data source access error occurs.
182      */
183     public void setBoolean(String   ns, String   varName, boolean value)
184     throws XMLDBCException;
185 
186     /**
187      * To set the specified variable with a boolean value. To be used with XML
188      * types derived from <code>boolean</code>.
189      * @param varName local name of the external variable. Must not be null.
190      * @param value a boolean that is the value to set for the parameter.
191      * @throws XMLDBCException if a data source access error occurs.
192      */
193     public void setBoolean(String   varName, boolean value)
194     throws XMLDBCException;
195 
196     /**
197      * To set the specified variable with a @link java.util.Date value. To be
198      * used with XML types derived from all built-in time types.
199      * @param ns The namespace of the external variable. Possibly an empty
200      * string if the variable has no namespace.
201      * @param varName local name of the external variable. Must not be null.
202      * @param value a java.sql.Date that is the value to set for the parameter.
203      * @throws XMLDBCException if a data source access error occurs.
204      */
205     public void setDate(String   ns, String   varName, Date   value)
206     throws XMLDBCException;
207 
208     /**
209      * To set the specified variable with a @link java.util.Date value. To be
210      * used with XML types derived from all built-in time types.
211      * @param varName local name of the external variable. Must not be null.
212      * @param value a java.sql.Date that is the value to set for the parameter.
213      * @throws XMLDBCException if a data source access error occurs.
214      */
215     public void setDate(String   varName, Date   value)
216     throws XMLDBCException;
217 
218     /**
219      * To set the specified variable with a double value. To be used with XML
220      * types derived from <code>double</code>.
221      * @param ns The namespace of the external variable. Possibly an empty
222      * string if the variable has no namespace.
223      * @param varName local name of the external variable. Must not be null.
224      * @param value a double that is the value to set for the parameter.
225      * @throws XMLDBCException if a data source access error occurs.
226      */
227     public void setDouble(String   ns, String   varName, double value)
228     throws XMLDBCException;
229 
230     /**
231      * To set the specified variable with a double value. To be used with XML
232      * types derived from <code>double</code>.
233      * @param varName local name of the external variable. Must not be null.
234      * @param value a double that is the value to set for the parameter.
235      * @throws XMLDBCException if a data source access error occurs.
236      */
237     public void setDouble(String   varName, double value)
238     throws XMLDBCException;
239 
240     /**
241      * To set the specified variable with a float value. To be used with XML
242      * types derived from <code>float</code>.
243      * @param ns The namespace of the external variable. Possibly an empty
244      * string if the variable has no namespace.
245      * @param varName local name of the external variable. Must not be null.
246      * @param value a float that is the value to set for the parameter.
247      * @throws XMLDBCException if a data source access error occurs.
248      */
249     public void setFloat(String   ns, String   varName, float value)
250     throws XMLDBCException;
251 
252     /**
253      * To set the specified variable with a float value. To be used with XML
254      * types derived from <code>float</code>.
255      * @param varName local name of the external variable. Must not be null.
256      * @param value a float that is the value to set for the parameter.
257      * @throws XMLDBCException if a data source access error occurs.
258      */
259     public void setFloat(String   varName, float value)
260     throws XMLDBCException;
261 
262     /**
263      * To set the specified variable with a long value. To be used with XML
264      * types derived from <code>integer</code>.
265      * @param ns The namespace of the external variable. Possibly an empty
266      * string if the variable has no namespace.
267      * @param varName local name of the external variable. Must not be null.
268      * @param value a long that is the value to set for the parameter.
269      * @throws XMLDBCException if a data source access error occurs.
270      */
271     public void setLong(String   ns, String   varName, long value)
272     throws XMLDBCException;
273 
274     /**
275      * To set the specified variable with a long value. To be used with XML
276      * types derived from <code>integer</code>.
277      * @param varName local name of the external variable. Must not be null.
278      * @param value a long that is the value to set for the parameter.
279      * @throws XMLDBCException if a data source access error occurs.
280      */
281     public void setLong(String   varName, long value)
282     throws XMLDBCException;
283 
284     /**
285      * To set the specified variable with a String value. To be used with XML
286      * types derived from <code>string</code>.
287      * @param ns The namespace of the external variable. Possibly an empty
288      * string if the variable has no namespace.
289      * @param varName local name of the external variable. Must not be null.
290      * @param value a string that is the value to set for the parameter.
291      * @throws XMLDBCException if a data source access error occurs.
292      */
293     public void setString(String   ns, String   varName, String   value)
294     throws XMLDBCException;
295 
296     /**
297      * To set the specified variable with a String value. To be used with XML
298      * types derived from <code>string</code>.
299      * @param varName local name of the external variable. Must not be null.
300      * @param value a string that is the value to set for the parameter.
301      * @throws XMLDBCException if a data source access error occurs.
302      */
303     public void setString(String   varName, String   value)
304     throws XMLDBCException;
305 
306     /**
307      * To set the specified variable with a Sequence value. 
308      * @param ns The namespace of the external variable. Possibly an empty
309      * string if the variable has no namespace.
310      * @param varName local name of the external variable. Must not be null.
311      * @param value a Sequence that is the value to set for the parameter.
312      * @throws XMLDBCException if a data source access error occurs.
313      */
314     public void setSequence(String   ns, String   varName, List   value)
315     throws XMLDBCException;
316 
317     /**
318      * To set the specified variable with a Sequence value.
319      * @param varName local name of the external variable. Must not be null.
320      * @param value a Sequence that is the value to set for the parameter.
321      * @throws XMLDBCException if a data source access error occurs.
322      */
323     public void setSequence(String   varName, List   value)
324     throws XMLDBCException;
325 
326      /**
327      * Clears the current parameters values immediately.
328      * @throws XMLDBCException if a data source access error occurs.
329      */
330     public void clearVariables() throws XMLDBCException;
331     
332     /**
333      * Executes the query statement specified when this object was built with
334      * the prepareStatement method (see XMLConnection interface) that may
335      * return results.
336      * If the query generates results, use the <I>getResultSet()</I> or
337      * <I>getDocumentSet()</I> methods to get the set of results.
338      * @return true if there are available resuts, else false.
339      * @throws XMLDBCException if a data source access error occurs.
340      */
341     public boolean execute() throws XMLDBCException;
342     
343     /**
344      * Executes the query statement specified when this object was built with
345      * the prepareStatement method (see XMLConnection interface) that returns
346      * results.
347      * @return an XMLResultSet object that contains the data produced by the
348      * given query.
349      * @throws XMLDBCException if a data source access error occurs.
350      */
351     public XMLResultSet executeQuery() throws XMLDBCException;
352     
353     /**
354      * Gets the array of parameter names of the statement
355      */
356     public QName  [] getParameterNames();
357     /**
358      * Gets the schema type of a particular parameter given it's name
359      */
360     public QName   getParameterType(QName   varName);
361 
362 }
363
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags