ZorbaXQExpression.java
Go to the documentation of this file.
1 /*
2  * Copyright 2006-2012 The FLWOR Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.zorbaxquery.api.xqj;
17 
18 import java.io.InputStream;
19 import java.io.Reader;
20 import java.io.StringWriter;
21 import java.io.Writer;
22 import java.nio.CharBuffer;
23 import java.util.*;
24 import javax.xml.namespace.QName;
25 import javax.xml.stream.XMLStreamReader;
26 import javax.xml.transform.Source;
27 import javax.xml.xquery.*;
28 import org.w3c.dom.Node;
29 import org.zorbaxquery.api.DynamicContext;
30 import org.zorbaxquery.api.Item;
31 import org.zorbaxquery.api.XQuery;
32 
33 /**
34  * This interface describes the execute immediate functionality for expressions. This object can be created from the ZorbaXQConnection and the execution can be done using the executeQuery() or executeCommand() method, passing in the XQuery expression.
35  *
36  * All external variables defined in the prolog of the expression to be executed must be set in the dynamic context of this expression using the bind methods. Also, variables bound in this expression but not defined as external in the prolog of the expression to be executed, are simply ignored. For example, if variables $var1 and $var2 are bound, but the query only defines $var1 as external, no error will be reported for the binding of $var2. It will simply be ignored. When the expression is executed using the executeQuery method, if the execution is successful, then an ZorbaXQResultSequence object is returned. The ZorbaXQResultSequence object is tied to the ZorbaXQExpression from which it was prepared and is closed implicitly if that ZorbaXQExpression is either closed or re-executed.
37  *
38  * The ZorbaXQExpression object is dependent on the ZorbaXQConnection object from which it was created and is only valid for the duration of that object. Thus, if the ZorbaXQConnection object is closed then this ZorbaXQExpression object will be implicitly closed and it can no longer be used.
39  *
40  * An XQJ driver is not required to provide finalizer methods for the connection and other objects. Hence it is strongly recommended that users call close method explicitly to free any resources. It is also recommended that they do so under a final block to ensure that the object is closed even when there are exceptions. Not closing this object implicitly or explicitly might result in serious memory leaks.
41  *
42  * When the ZorbaXQExpression is closed any ZorbaXQResultSequence object obtained from it is also implicitly closed.
43  *
44  * Example -
45  * \code{.java}
46  * ZorbaXQConnection conn = XQDatasource.getConnection();
47  * ZorbaXQExpression expr = conn.createExpression();
48  *
49  * expr.bindInt(new QName("x"), 21, null);
50  *
51  * XQSequence result = expr.executeQuery(
52  * "declare variable $x as xs:integer external;
53  * for $i in $x return $i");
54  *
55  * while (result.next())
56  * {
57  * // process results ...
58  * }
59  *
60  * // Execute some other expression on the same object
61  * XQSequence result = expr.executeQuery("for $i in doc('foo.xml') return $i");
62  * ...
63  *
64  * result.close(); // close the result
65  * expr.close();
66  * conn.close();
67  * \endcode
68  */
69 public class ZorbaXQExpression implements javax.xml.xquery.XQExpression {
70 
71  //private XQuery query;
72  private XQConnection connection;
73  private boolean closed = false;
74  private boolean cancel = false;
75  private Collection<XQResultSequence> resultSequences = new ArrayList<XQResultSequence>();
76  private XQStaticContext staticContext;
77  private Map<String, Item> itemsToBind = new HashMap<String, Item>();
78  private TimeZone implicitTimeZone;
79 
80  public ZorbaXQExpression (XQConnection conn) throws XQException {
81  if (conn.isClosed()) {
82  throw new XQException ("Connection is closed");
83  }
84  connection = conn;
85  }
86 
87  public ZorbaXQExpression (XQConnection conn, XQStaticContext sc) throws XQException {
88  if (conn.isClosed()) {
89  throw new XQException ("Connection is closed");
90  }
91  connection = conn;
92  staticContext = sc;
93  }
94 
95  /** \brief Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an ZorbaXQExpression.
96  *
97  * This method can be used by one thread to cancel an ZorbaXQExpression, that is being executed in another thread. If cancellation is not supported or the attempt to cancel the execution was not successful, the method returns without any error. If the cancellation is successful, an XQException is thrown, to indicate that it has been aborted, by executeQuery, executeCommand or any method accessing the ZorbaXQResultSequence returned by executeQuery. If applicable, any open ZorbaXQResultSequence and XQResultItem objects will also be implicitly closed in this case.
98  *
99  * @throw XQException - if the expression is in a closed state
100  */
101  @Override
102  public void cancel() throws XQException {
103  isClosedXQException();
104  cancel = true;
105  }
106 
107  /** \brief Checks if the expression is in a closed state.
108  *
109  * @return true if the expression is in a closed state, false otherwise
110  */
111  @Override
112  public boolean isClosed() {
113  return closed;
114  }
115 
116 
117  /** \brief Closes the expression object and release associated resources.
118  *
119  * Once the expression is closed, all methods on this object other than the close or isClosed will raise exceptions. This also closes any result sequences obtained from this expression. Calling close on an ZorbaXQExpression object that is already closed has no effect.
120  *
121  * @throw XQException - if there are errors when closing the expression
122  */
123  @Override
124  public void close() throws XQException {
125  closed=true;
126  for (XQResultSequence rs: resultSequences) {
127  rs.close();
128  }
129  }
130 
131  /** \brief Executes an implementation-defined command.
132  *
133  * Calling this method implicitly closes any previous result sequence obtained from this expression.
134  *
135  * @param string - the input command as a string
136  * @throw XQException - if (1) there are errors when executing the command, or (2) the expression is in a closed state
137  */
138  @Override
139  public void executeCommand(String string) throws XQException {
140  throw new UnsupportedOperationException("Not supported yet.");
141  }
142 
143  /** \brief Executes an implementation-defined command.
144  *
145  * Calling this method implicitly closes any previous result sequence obtained from this expression.
146  *
147  * @param reader - the input command as a reader
148  * @throw XQException - if (1) there are errors when executing the command, or (2) the expression is in a closed state
149  */
150  @Override
151  public void executeCommand(Reader reader) throws XQException {
152  throw new UnsupportedOperationException("Not supported yet.");
153  }
154 
155  /** \brief Executes a query expression.
156  *
157  * This implicitly closes any previous result sequences obtained from this expression.
158  *
159  * @param value - the input query expression string. Cannot be null
160  * @return an ZorbaXQResultSequence object containing the result of the query execution
161  * @throw XQException - if (1) there are errors when executing the query, (2) the expression is in a closed state, (3) the execution is cancelled, (4) the query parameter is null
162  */
163  @Override
164  public XQResultSequence executeQuery(String value) throws XQException {
165  isClosedXQException();
166  isNullXQException(value);
167  org.zorbaxquery.api.xqj.ZorbaXQConnection lConnection = (org.zorbaxquery.api.xqj.ZorbaXQConnection)connection;
168  XQuery query = lConnection.getZorbaInstance().createQuery();
169  XQResultSequence result = null;
170  try {
171  int scrollable = XQConstants.SCROLLTYPE_FORWARD_ONLY;
172  if (staticContext!=null) {
173  query.compile(value, ((org.zorbaxquery.api.xqj.ZorbaXQStaticContext)staticContext).getZorbaStaticContext());
174  scrollable = staticContext.getScrollability();
175  } else {
176  query.compile(value);
177  }
178  DynamicContext dynamicContext = query.getDynamicContext();
179  if (implicitTimeZone!=null) {
180  dynamicContext.setImplicitTimezone((implicitTimeZone.getRawOffset()/60000));
181  implicitTimeZone=null;
182  }
183  for (String key: itemsToBind.keySet()){
184  dynamicContext.setVariable(key, itemsToBind.get(key) );
185  //itemsToBind.remove(key);
186  }
187  if (scrollable == XQConstants.SCROLLTYPE_FORWARD_ONLY) {
188  result = new org.zorbaxquery.api.xqj.ZorbaXQResultSequence(connection, query, false);
189  } else {
190  result = new org.zorbaxquery.api.xqj.ZorbaXQResultSequenceScrollable(connection, query, false);
191  }
192  resultSequences.add(result);
193  } catch (Exception e) {
194  throw new XQException ("Error executing query: " + e.getLocalizedMessage());
195  }
196  return result;
197  }
198 
199  /** \brief Executes a query expression.
200  *
201  * This implicitly closes any previous result sequences obtained from this expression.
202  *
203  * @param value - the input query expression reader object. Cannot be null
204  * @return an ZorbaXQResultSequence object containing the result of the query execution
205  * @throw XQException - if (1) there are errors when executing the query, (2) the expression is in a closed state, (3) the execution is cancelled, (4) the query parameter is null
206  */
207  @Override
208  public XQResultSequence executeQuery(Reader value) throws XQException {
209  isClosedXQException();
210  isNullXQException(value);
211 
212  StringBuffer string = new StringBuffer();
213  CharBuffer buffer = CharBuffer.allocate(1024);
214  Writer writer = new StringWriter();
215 
216  try {
217  while( value.read(buffer) >= 0 ) {
218  buffer.flip();
219  writer.append(buffer);
220  buffer.clear();
221  }
222  value.close();
223  } catch (Exception ex) {
224  throw new XQException("Error preparing expression" + ex.getLocalizedMessage());
225  }
226 
227  return executeQuery(writer.toString());
228  }
229 
230  /** \brief Executes a query expression.
231  *
232  * This implicitly closes any previous result sequences obtained from this expression.
233  *
234  * @param value - the input query expression inputstream object. Cannot be null
235  * @return an ZorbaXQResultSequence object containing the result of the query execution
236  * @throw XQException - if (1) there are errors when executing the query, (2) the expression is in a closed state, (3) the execution is cancelled, (4) the query parameter is null
237  */
238  @Override
239  public XQResultSequence executeQuery(InputStream value) throws XQException {
240  isClosedXQException();
241  isNullXQException(value);
242  StringBuffer out = new StringBuffer ();
243  try {
244  byte[] b = new byte[4096];
245  for (int n; (n = value.read(b)) != -1;) {
246  out.append(new String(b, 0, n));
247  }
248  } catch (Exception ex) {
249  throw new XQException("Error preparing expression" + ex.getLocalizedMessage());
250  }
251  return executeQuery(out.toString());
252  }
253 
254  /** \brief Gets an ZorbaXQStaticContext representing the values for all expression properties.
255  *
256  * Note that these properties cannot be changed; in order to change, a new ZorbaXQExpression needs to be created.
257  *
258  * @return an ZorbaXQStaticContext representing the values for all expression properties
259  * @throw XQException - if the expression is in a closed state
260  */
261  @Override
262  public XQStaticContext getStaticContext() throws XQException {
263  isClosedXQException();
264  if (staticContext==null) {
265  return connection.getStaticContext();
266  } else {
267  return staticContext;
268  }
269  }
270 
271  /** \brief Gets the implicit timezone
272  *
273  * @return the implicit timezone. This may have been set by an application using the setImplicitTimeZone method or provided by the implementation
274  * @throw XQException - if the expression is in a closed state
275  */
276  @Override
277  public TimeZone getImplicitTimeZone() throws XQException {
278  isClosedXQException();
279  if (implicitTimeZone!=null) {
280  return implicitTimeZone;
281  }
282  XQuery query = ((org.zorbaxquery.api.xqj.ZorbaXQConnection)connection).getZorbaInstance().compileQuery("1");
283  DynamicContext dc = query.getDynamicContext();
284  Integer timeZone = (dc.getImplicitTimezone()/60); // in minutes
285  TimeZone result = TimeZone.getTimeZone("GMT"+timeZone.toString());
286  return result;
287  }
288 
289  /** \brief Binds a value to the given external variable or the context item.
290  *
291  * The value is converted into an instance of the specified type according to the casting from xs:string rules outlined in 17.1.1 Casting from xs:string and xs:untypedAtomic, XQuery 1.0 and XPath 2.0 Functions and Operators. If the cast fails, or if there is a mismatch between the static and dynamic types, an XQException is thrown either by this method or during query evaluation.
292  *
293  * @param varName - the name of the external variable to bind to
294  * @param value - the lexical string value of the type
295  * @param type - the item type of the bind
296  * @throw XQException - if (1) any of the arguments are null, (2) given type is not an atomic type, (3) the conversion of the value to an XDM instance failed, (4) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (5) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (6) the expression is in a closed state
297  */
298  @Override
299  public void bindAtomicValue(QName varName, String value, XQItemType type) throws XQException {
300  isClosedXQException();
301  isNullXQException(varName);
302  isNullXQException(value);
303  try {
304  XQItem item = connection.createItemFromAtomicValue(value, type);
305  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
306  } catch (Exception e) {
307  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
308  }
309  }
310 
311  /** \brief Binds a value to the given external variable or the context item.
312  *
313  * The value is converted into an instance of the specified type, which must represent an xs:string or a type derived by restriction from xs:string. If the specified type is null, it defaults to xs:string.
314  * Subsequently the value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0,. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
315  *
316  * @param varName - the name of the external variable to bind to, cannot be null
317  * @param value - the value to be converted, cannot be null
318  * @param type - the type of the value to be bound to the external variable. The default type, xs:string, is used in case null is specified
319  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
320  */
321  @Override
322  public void bindString(QName varName, String value, XQItemType type) throws XQException {
323  isClosedXQException();
324  isNullXQException(varName);
325  isNullXQException(value);
326  try {
327  XQItem item = connection.createItemFromString(value, type);
328  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
329  } catch (Exception e) {
330  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
331  }
332  }
333 
334  /** \brief Binds a value to the given external variable or the context item.
335  *
336  * If the value represents a well-formed XML document, it will be parsed and results in a document node. The kind of the input type must be null, XQITEMKIND_DOCUMENT_ELEMENT, or XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT.
337  *
338  * The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
339  *
340  * If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
341  *
342  * @param varName - the name of the external variable to bind to, cannot be null
343  * @param value - the value to be converted, cannot be null
344  * @param baseURI - an optional base URI, can be null. It can be used, for example, to resolve relative URIs and to include in error messages.
345  * @param type - the type of the value for the created document node. If null is specified, it behaves as if XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))
346  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
347  */
348  @Override
349  public void bindDocument(QName varName, String value, String baseURI, XQItemType type) throws XQException {
350  isClosedXQException();
351  isNullXQException(varName);
352  isNullXQException(value);
353  try {
354  XQItem item = connection.createItemFromDocument(value, baseURI, type);
355  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
356  } catch (Exception e) {
357  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
358  }
359  }
360 
361  /** \brief Binds a value to the given external variable or the context item.
362  *
363  * If the value represents a well-formed XML document, it will be parsed and results in a document node. The kind of the input type must be null, XQITEMKIND_DOCUMENT_ELEMENT, or XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT.
364  *
365  * The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
366  *
367  * If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
368  *
369  * @param varName - the name of the external variable to bind to, cannot be null
370  * @param value - the value to be converted, cannot be null
371  * @param baseURI - an optional base URI, can be null. It can be used, for example, to resolve relative URIs and to include in error messages.
372  * @param type - the type of the value for the created document node. If null is specified, it behaves as if XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))
373  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
374  */
375  @Override
376  public void bindDocument(QName varName, Reader value, String baseURI, XQItemType type) throws XQException {
377  isClosedXQException();
378  isNullXQException(varName);
379  isNullXQException(value);
380  try {
381  XQItem item = connection.createItemFromDocument(value, baseURI, type);
382  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
383  } catch (Exception e) {
384  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
385  }
386  }
387 
388  /** \brief Binds a value to the given external variable or the context item.
389  *
390  * If the value represents a well-formed XML document, it will be parsed and results in a document node. The kind of the input type must be null, XQITEMKIND_DOCUMENT_ELEMENT, or XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT.
391  *
392  * The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
393  *
394  * If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
395  *
396  * @param varName - the name of the external variable to bind to, cannot be null
397  * @param value - the value to be converted, cannot be null
398  * @param baseURI - an optional base URI, can be null. It can be used, for example, to resolve relative URIs and to include in error messages.
399  * @param type - the type of the value for the created document node. If null is specified, it behaves as if XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))
400  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
401  */
402  @Override
403  public void bindDocument(QName varName, InputStream value, String baseURI, XQItemType type) throws XQException {
404  isClosedXQException();
405  isNullXQException(varName);
406  isNullXQException(value);
407  try {
408  XQItem item = connection.createItemFromDocument(value, baseURI, type);
409  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
410  } catch (Exception e) {
411  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
412  }
413  }
414 
415  /** \brief Binds a value to the given external variable or the context item.
416  *
417  * If the value represents a well-formed XML document, it will be parsed and results in a document node. The kind of the input type must be null, XQITEMKIND_DOCUMENT_ELEMENT, or XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT.
418  *
419  * The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
420  *
421  * If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
422  *
423  * @param varName - the name of the external variable to bind to, cannot be null
424  * @param value - the value to be converted, cannot be null
425  * @param type - the type of the value for the created document node. If null is specified, it behaves as if XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))
426  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
427  */
428  @Override
429  public void bindDocument(QName varName, XMLStreamReader value, XQItemType type) throws XQException {
430  isClosedXQException();
431  isNullXQException(varName);
432  isNullXQException(value);
433  try {
434  XQItem item = connection.createItemFromDocument(value, type);
435  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
436  } catch (Exception e) {
437  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
438  }
439  }
440 
441  /** \brief Binds a value to the given external variable or the context item.
442  *
443  * An XQJ implementation must at least support the following implementations:
444  * - javax.xml.transform.dom.DOMSource
445  * - javax.xml.transform.sax.SAXSource
446  * - javax.xml.transform.stream.StreamSource
447  *
448  * If the value represents a well-formed XML document, it will be parsed and results in a document node. The kind of the input type must be null, XQITEMKIND_DOCUMENT_ELEMENT, or XQITEMKIND_DOCUMENT_SCHEMA_ELEMENT.
449  *
450  * The value is converted into an instance of the specified type according to the rules defined in 14.3 Mapping a Java XML document to an XQuery document node, XQuery API for Java (XQJ) 1.0.
451  *
452  * If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation. If the value is not well formed, or if a kind of the input type other than the values list above is specified, behavior is implementation defined and may raise an exception.
453  *
454  * @param varName - the name of the external variable to bind to, cannot be null
455  * @param value - the value to be converted, cannot be null
456  * @param type - the type of the value for the created document node. If null is specified, it behaves as if XQDataFactory.createDocumentElementType( XQDataFactory.createElementType(null, XQItemType.XQBASETYPE_XS_UNTYPED)) were passed in as the type parameter. That is, the type represents the XQuery sequence type document-node(element(*, xs:untyped))
457  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
458  */
459  @Override
460  public void bindDocument(QName varName, Source value, XQItemType type) throws XQException {
461  isClosedXQException();
462  isNullXQException(varName);
463  isNullXQException(value);
464  try {
465  XQItem item = connection.createItemFromDocument(value, type);
466  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
467  } catch (Exception e) {
468  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
469  }
470  }
471 
472  /** \brief Sets the implicit timezone
473  *
474  * @param value - time zone to be set
475  * @throw XQException - if the expression is in a closed state
476  */
477  @Override
478  public void setImplicitTimeZone(TimeZone value) throws XQException {
479  isClosedXQException();
480  isNullXQException(value);
481  try {
482  implicitTimeZone = value;
483  } catch (Exception e) {
484  throw new XQException("Error setting implicit TimeZone: " + e.getLocalizedMessage());
485  }
486  }
487 
488  /** \brief Binds a value to the given external variable.
489  *
490  * The dynamic type of the value is derived from the ZorbaXQItem. In case of a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
491  *
492  * @param varName - the name of the external variable to bind to, cannot be null
493  * @param value - the value to be bound, cannot be null
494  * @throw XQException - if (1) any of the arguments are null, (2) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (3) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, (4) the expression is in a closed state, or (5) the specified item is closed
495  */
496  @Override
497  public void bindItem(QName varName, XQItem value) throws XQException {
498  isClosedXQException();
499  isNullXQException(varName);
500  isNullXQException(value);
501  try {
502  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)value).getZorbaItem());
503  } catch (Exception e) {
504  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
505  }
506  }
507 
508  /** \brief Binds a value to the given external variable.
509  *
510  * The input sequence is consumed from its current position to the end, after which the input sequence's position will be set to point after the last item. The dynamic type of the value is derived from the items in the sequence. In case of a mismatch between the static and dynamic types, an XQException is be raised either by this method, or during query evaluation.
511  *
512  * @param varName - the name of the external variable to bind to, cannot be null
513  * @param value - the value to be bound, cannot be null
514  * @throw XQException - if (1) any of the arguments are null, (2) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (3) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, (4) the expression is in a closed state, or (5) the specified item is closed
515  */
516  @Override
517  public void bindSequence(QName varName, XQSequence value) throws XQException {
518  isClosedXQException();
519  isNullXQException(varName);
520  isNullXQException(value);
521  try {
522  Item item = new Item(((org.zorbaxquery.api.xqj.ZorbaXQItem)value.getItem()).getZorbaItem());
523  itemsToBind.put(varName.getLocalPart(), item);
524  } catch (Exception e) {
525  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
526  }
527  }
528 
529  /** \brief Binds a value to the given external variable or the context item.
530  *
531  * The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
532  *
533  * @param varName - the name of the external variable to bind to, cannot be null
534  * @param value - the value to be bound, cannot be null
535  * @param type - the type of the value to be bound to the external variable. The default type of the value is used in case null is specified
536  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
537  */
538  @Override
539  public void bindObject(QName varName, Object value, XQItemType type) throws XQException {
540  isClosedXQException();
541  isNullXQException(varName);
542  isNullXQException(value);
543  try {
544  XQItem item = null;
545  if (value instanceof XQItem) {
546  item = (XQItem)value;
547  } else {
548  item = connection.createItemFromObject(value, type);
549  }
550  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
551  } catch (Exception e) {
552  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
553  }
554  }
555 
556  /** \brief Binds a value to the given external variable or the context item.
557  *
558  * The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
559  *
560  * @param varName - the name of the external variable to bind to, cannot be null
561  * @param value - the value to be bound, cannot be null
562  * @param type - the type of the value to be bound to the external variable. The default type of the value is used in case null is specified
563  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
564  */
565  @Override
566  public void bindBoolean(QName varName, boolean value, XQItemType type) throws XQException {
567  isClosedXQException();
568  isNullXQException(varName);
569  try {
570  XQItem item = connection.createItemFromBoolean(value, type);
571  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
572  } catch (Exception e) {
573  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
574  }
575  }
576 
577  /** \brief Binds a value to the given external variable or the context item.
578  *
579  * The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
580  *
581  * @param varName - the name of the external variable to bind to, cannot be null
582  * @param value - the value to be bound, cannot be null
583  * @param type - the type of the value to be bound to the external variable. The default type of the value is used in case null is specified
584  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
585  */
586  @Override
587  public void bindByte(QName varName, byte value, XQItemType type) throws XQException {
588  isClosedXQException();
589  isNullXQException(varName);
590  try {
591  XQItem item = connection.createItemFromByte(value, type);
592  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
593  } catch (Exception e) {
594  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
595  }
596  }
597 
598  /** \brief Binds a value to the given external variable or the context item.
599  *
600  * The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
601  *
602  * @param varName - the name of the external variable to bind to, cannot be null
603  * @param value - the value to be bound, cannot be null
604  * @param type - the type of the value to be bound to the external variable. The default type of the value is used in case null is specified
605  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
606  */
607  @Override
608  public void bindDouble(QName varName, double value, XQItemType type) throws XQException {
609  isClosedXQException();
610  isNullXQException(varName);
611  try {
612  XQItem item = connection.createItemFromDouble(value, type);
613  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
614  } catch (Exception e) {
615  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
616  }
617  }
618 
619  /** \brief Binds a value to the given external variable or the context item.
620  *
621  * The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
622  *
623  * @param varName - the name of the external variable to bind to, cannot be null
624  * @param value - the value to be bound, cannot be null
625  * @param type - the type of the value to be bound to the external variable. The default type of the value is used in case null is specified
626  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
627  */
628  @Override
629  public void bindFloat(QName varName, float value, XQItemType type) throws XQException {
630  isClosedXQException();
631  isNullXQException(varName);
632  try {
633  XQItem item = connection.createItemFromFloat(value, type);
634  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
635  } catch (Exception e) {
636  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
637  }
638  }
639 
640  /** \brief Binds a value to the given external variable or the context item.
641  *
642  * The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
643  *
644  * @param varName - the name of the external variable to bind to, cannot be null
645  * @param value - the value to be bound, cannot be null
646  * @param type - the type of the value to be bound to the external variable. The default type of the value is used in case null is specified
647  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
648  */
649  @Override
650  public void bindInt(QName varName, int value, XQItemType type) throws XQException {
651  isClosedXQException();
652  isNullXQException(varName);
653  try {
654  XQItem item = connection.createItemFromInt(value, type);
655  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
656  } catch (Exception e) {
657  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
658  }
659  }
660 
661  /** \brief Binds a value to the given external variable or the context item.
662  *
663  * The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
664  *
665  * @param varName - the name of the external variable to bind to, cannot be null
666  * @param value - the value to be bound, cannot be null
667  * @param type - the type of the value to be bound to the external variable. The default type of the value is used in case null is specified
668  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
669  */
670  @Override
671  public void bindLong(QName varName, long value, XQItemType type) throws XQException {
672  isClosedXQException();
673  isNullXQException(varName);
674  try {
675  XQItem item = connection.createItemFromLong(value, type);
676  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
677  } catch (Exception e) {
678  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
679  }
680  }
681 
682  /** \brief Binds a value to the given external variable or the context item.
683  *
684  * The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
685  *
686  * @param varName - the name of the external variable to bind to, cannot be null
687  * @param value - the value to be bound, cannot be null
688  * @param type - the type of the value to be bound to the external variable. The default type of the value is used in case null is specified
689  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
690  */
691  @Override
692  public void bindNode(QName varName, Node value, XQItemType type) throws XQException {
693  isClosedXQException();
694  isNullXQException(varName);
695  isNullXQException(value);
696  try {
697  XQItem item = connection.createItemFromNode(value, type);
698  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
699  } catch (Exception e) {
700  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
701  }
702  }
703 
704  /** \brief Binds a value to the given external variable or the context item.
705  *
706  * The value is converted into an instance of the specified type according to the rule defined in 14.2 Mapping a Java Data Type to an XQuery Data Type, XQuery API for Java (XQJ) 1.0. If the conversion fails, or if there is a mismatch between the static and dynamic types, an XQException is raised either by this method, or during query evaluation.
707  *
708  * @param varName - the name of the external variable to bind to, cannot be null
709  * @param value - the value to be bound, cannot be null
710  * @param type - the type of the value to be bound to the external variable. The default type of the value is used in case null is specified
711  * @throw XQException - if (1) the varName or value argument is null, (2) the conversion of the value to an XDM instance failed, (3) in case of an XQPreparedExpression, the dynamic type of the bound value is not compatible with the static type of the variable, (4) in case of an XQPreparedExpression, the variable is not defined in the prolog of the expression, or (5) if the expression is in a closed state
712  */
713  @Override
714  public void bindShort(QName varName, short value, XQItemType type) throws XQException {
715  isClosedXQException();
716  isNullXQException(varName);
717  try {
718  XQItem item = connection.createItemFromShort(value, type);
719  itemsToBind.put(varName.getLocalPart(),((org.zorbaxquery.api.xqj.ZorbaXQItem)item).getZorbaItem());
720  } catch (Exception e) {
721  throw new XQException ("Error binding object: " + e.getLocalizedMessage());
722  }
723  }
724 
725  private void isClosedXQException() throws XQException {
726  if (closed) {
727  throw new XQException("This expression is closed");
728  }
729  }
730  private void isNullXQException(Object value) throws XQException {
731  if (value==null) {
732  throw new XQException("Parameter shouldn't be null");
733  }
734  }
735 
736 
737 }