ZorbaXQResultSequence.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.OutputStream;
19 import java.io.Reader;
20 import java.io.StringReader;
21 import java.io.Writer;
22 import java.net.URI;
23 import java.util.ArrayList;
24 import java.util.Collection;
25 import java.util.Properties;
26 import javax.xml.stream.XMLInputFactory;
27 import javax.xml.stream.XMLStreamException;
28 import javax.xml.stream.XMLStreamReader;
29 import javax.xml.transform.Result;
30 import javax.xml.xquery.XQConnection;
31 import javax.xml.xquery.XQException;
32 import javax.xml.xquery.XQItem;
33 import javax.xml.xquery.XQItemType;
34 import org.w3c.dom.Node;
35 import org.xml.sax.ContentHandler;
36 import org.zorbaxquery.api.Item;
37 import org.zorbaxquery.api.Iterator;
38 import org.zorbaxquery.api.SerializationOptions;
39 
40  /**
41  * This class represents a sequence of items obtained as a result of evaluation XQuery expressions. The result sequence is tied to the XQconnection object on which the expression was evaluated.
42  *
43  * This sequence can be obtained by performing an executeQuery on the expression object. It represents a cursor-like class.
44  *
45  * The ZorbaXQResultSequence object is dependent on the connection and the expression from which it was created and is only valid for the duration of those objects. Thus, if any one of those objects is closed, this ZorbaXQResultSequence object will be implicitly closed and it can no longer be used. Similarly re-executing the expression also implicitly closes the associated result sequences.
46  *
47  * 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.
48  *
49  * When the ZorbaXQResultSequence is closed any ZorbaXQResultItem objects obtained from it are also implicitly closed.
50  *
51  * Example -
52  *
53  * \code{.java}
54  * XQPreparedExpression expr = conn.prepareExpression("for $i ..");
55  * ZorbaXQResultSequence result = expr.executeQuery();
56  *
57  * // create the ItemTypes for string and integer
58  * XQItemType strType = conn.createAtomicType(XQItemType.XQBASETYPE_STRING);
59  * XQItemType intType = conn.createAtomicType(XQItemType.XQBASETYPE_INT);
60  *
61  * // posititioned before the first item
62  * while (result.next())
63  * {
64  * XQItemType type = result.getItemType();
65  *
66  * // If string, then get the string value out
67  * if (type.equals(strType))
68  * String str = result.getAtomicValue();
69  * else if (type.equals(intType)) // if it is an integer..
70  * int intval = result.getInt();
71  * ...
72  * }
73  *
74  * result.close(); // explicitly close the result sequence
75  * \endcode
76  */
77 public class ZorbaXQResultSequence implements javax.xml.xquery.XQResultSequence {
78 
79  private boolean closed = false;
80  private boolean delivered = false;
81  //private boolean isonitem = false;
82  private boolean consumedItem = false;
83  private boolean iterDeleted = false;
84 
85  private XQConnection connection = null;
86  private Iterator iter = null;
87  private ZorbaXQResultItem current = null;
88  private Collection<ZorbaXQResultItem> items = new ArrayList<ZorbaXQResultItem>();
89  private org.zorbaxquery.api.XQuery lQuery=null;
90  private boolean preparedExpression;
91  private ZorbaXQStaticCollectionManager lStaticCollectionManager;
92 
93  public ZorbaXQResultSequence(XQConnection conn, org.zorbaxquery.api.XQuery query, boolean prepared) {
94  lQuery = query;
95  iter = query.iterator();
96  iter.open();
97  connection = conn;
98  preparedExpression = prepared;
99  }
100 
101  /** \brief Gets the XQuery connection associated with this result sequence
102  *
103  * @return the connection associated with this result sequence
104  * @throw XQException - if the result sequence is in a closed state
105  */
106  @Override
107  public XQConnection getConnection() throws XQException {
108  isClosedXQException();
109  return connection;
110  }
111 
112  /** \brief Moves the XQSequence's position to the given item number in this object.
113  *
114  * If the item number is positive, the XQSequence moves to the given item number with respect to the beginning of the XQSequence.
115  * The first item is item 1, the second is item 2, and so on.
116  *
117  * If the given item number is negative, the XQSequence positions itself on an absolute item position with respect to the end of the sequence.
118  *
119  * For example, calling the method absolute(-1) positions the XQSequence on the last item; calling the method absolute(-2) moves the XQSequence to the next-to-last item, and so on. absolute(0) will position the sequence before the first item.
120  *
121  * An attempt to position the sequence beyond the first/last item set leaves the current position to be before the first item or after the last item.
122  *
123  * Calling this method on an empty sequence will return false.
124  *
125  * @param i - the item position to jump to
126  * @return true if the current position is within the sequence, false otherwise
127  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state
128  */
129  @Override
130  public boolean absolute(int i) throws XQException {
131  isClosedXQException();
132  throw new XQException("This sequence is forward-only");
133  }
134 
135  /** \brief Move to the position after the last item.
136  *
137  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state
138  */
139  @Override
140  public void afterLast() throws XQException {
141  isClosedXQException();
142  throw new XQException("This sequence is forward-only");
143  }
144 
145  /** \brief Moves to the position before the first item.
146  *
147  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state
148  */
149  @Override
150  public void beforeFirst() throws XQException {
151  isClosedXQException();
152  throw new XQException("This sequence is forward-only");
153  }
154 
155  /** \brief Closes the sequence and frees all resources associated with this sequence.
156  *
157  * Closing an XQSequence object also implicitly closes all XQItem objects obtained from it. All methods other than the isClosed or close method will raise exceptions when invoked after closing the sequence. Calling close on an XQSequence object that is already closed has no effect.
158  *
159  * @throw XQException - if there are errors during closing of the sequence
160  */
161  @Override
162  public void close() throws XQException {
163  if (!closed) {
164  closed = true;
165  for (ZorbaXQResultItem xitem: items){
166  xitem.close();
167  }
168  items.removeAll(items);
169  if (!iterDeleted) {
170  if (iter.isOpen()) {
171  iter.close();
172  iter.delete();
173  }
174  if (!preparedExpression) {
175  lQuery.delete();
176  }
177  }
178  if (lStaticCollectionManager != null) {
179  lStaticCollectionManager.close();
180  }
181  }
182  }
183 
184  /** \brief Checks if the sequence is closed.
185  *
186  * @return true if the sequence is in a closed state, false otherwise
187  */
188  @Override
189  public boolean isClosed() {
190  return closed;
191  }
192 
193  /** \brief Returns a number indicating the number of items in the sequence.
194  *
195  * @return the number of items in this sequence
196  * @throw XQException - if (1) the sequence is forward-only, or (2) the sequence is closed
197  */
198  @Override
199  public int count() throws XQException {
200  isClosedXQException();
201  throw new XQException("This sequence is forward-only");
202  }
203 
204  /** \brief Gets the current cursor position.
205  *
206  * 0 indicates that the position is before the first item and count() + 1 indicates position after the last item. A specific position indicates that the cursor is positioned on the item at that position. Use the isOnItem method to verify if the cursor is positioned on the item.
207  *
208  * Calling this method on an empty sequence will return 0.
209  *
210  * @throw XQException - if (1) the sequence is forward-only, or (2) the sequence is closed
211  */
212  @Override
213  public int getPosition() throws XQException {
214  isClosedXQException();
215  throw new XQException("This sequence is forward-only");
216  }
217 
218  /** \brief Check if the sequence is positioned on an item or not.
219  *
220  * Calling this method on an empty sequence will return false.
221  *
222  * @return true if the sequence is currently positioned on an item, false if sequence is positioned before the first item, or after the last item
223  * @throw XQException - if the sequence is in a closed state
224  */
225  @Override
226  public boolean isOnItem() throws XQException {
227  isClosedXQException();
228  return (current!=null);
229  }
230 
231  /** \brief Checks if the sequence is scrollable.
232  *
233  * @return true if the sequence can be scrolled backward or forward, false otherwise
234  * @throw XQException - if the sequence is in a closed state
235  */
236  @Override
237  public boolean isScrollable() throws XQException {
238  isClosedXQException();
239  return false;
240  }
241 
242  /** \brief Moves to the first item in the sequence.
243  *
244  * The method returns true, if it was able to move to the first item in the sequence false, otherwise. Calling this method on an empty sequence will return false.
245  *
246  * @return true if the sequence was positioned on the first item, false otherwise
247  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state
248  */
249  @Override
250  public boolean first() throws XQException {
251  isClosedXQException();
252  throw new XQException("This sequence is forward-only");
253  }
254 
255  /** \brief Get the current item as an immutable XQItem object.
256  *
257  * In case of an ZorbaXQResultSequence, the item is an ZorbaXQResultItem. In the case of forward only sequences, this method or any other get or write method may only be called once on the curent item.
258  *
259  * The XQItem object is dependent on the sequence from which it was created and is only valid for the duration of XQSequence lifetime. Thus, the XQSequence is closed, this XQItem object will be implicitly closed and it can no longer be used.
260  *
261  * @return an XQItem object
262  * @throw XQException - if (1) there are errors retrieving the item, or (2) in the case of a forward only sequence, a get or write method has already been invoked on the current item.
263  */
264  @Override
265  public XQItem getItem() throws XQException {
266  isClosedXQException();
267  isItemDeliveredXQException();
268  isOnItemXQException();
269 
270  delivered = true;
271  consumedItem = true;
272  return current;
273  }
274 
275  /** \brief Read the entire sequence starting from the current position as an XMLStreamReader object.
276  *
277  * Read the entire sequence starting from the current position as an XMLStreamReader object, as described in Section 12.1 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0. Note that the serialization process might fail, in which case a XQException is thrown. While the stream is being read, the application MUST NOT do any other concurrent operations on the sequence. The operation on the stream is undefined if the underlying sequence position or state is changed by concurrent operations. After all items are written to the stream, the current position of the cursor is set to point after the last item. Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods.
278  *
279  * @return an XML reader object as XMLStreamReader
280  * @throw XQException - if (1) there are errors accessing any of the items in the sequence, (2) the sequence is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) in case of an error during serialization of the sequence into a StAX event stream as defined in Section 12.1 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0
281  */
282  @Override
283  public XMLStreamReader getSequenceAsStream() throws XQException {
284  isClosedXQException();
285  isConsumedXQException();
286  Properties properties = null;
287  String str = getSequenceAsString(properties);
288  XMLInputFactory fac = XMLInputFactory.newInstance();
289  Reader read = new StringReader(str);
290  XMLStreamReader result = null;
291  try {
292  result = fac.createXMLStreamReader(read);
293  } catch (XMLStreamException ex) {
294  throw new XQException("Problem reading the stream: " + str + " - with error: " + ex.getLocalizedMessage());
295  }
296  return result;
297  }
298 
299  /** \brief Serializes the sequence starting from the current position to a String.
300  *
301  * Serializes the sequence starting from the current position to a String according to the XSLT 2.0 and XQuery 1.0 serialization. Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information. Reading the sequence during the serialization process performs implicit next operations to read the items. After all items are written to the stream, the current position of the cursor is set to point after the last item. Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods.
302  *
303  * @param prprts - specifies the serialization parameters, null is considered equivalent to an empty Properties object
304  * @return the serialized representation of the sequence
305  * @throw XQException - if (1) there are errors accessing the items in the sequence, (2) there are errors during serialization, (3) the sequence is in a closed state, or (4) in the case of a forward only sequence, a get or write method has already been invoked on the current item
306  */
307  @Override
308  public String getSequenceAsString(Properties prprts) throws XQException {
309  isClosedXQException();
310  isConsumedXQException();
311  String result = null;
312  try {
313  SerializationOptions opts = new SerializationOptions();
314  if ((prprts!=null) && prprts.size()>0) {
315  for(String key : prprts.stringPropertyNames()) {
316  String value = prprts.getProperty(key);
317  opts.setSerializerOption(key, value);
318  }
319  }
320  if (iter.isOpen()) {
321  iter.close();
322  iter.delete();
323  }
324  iterDeleted = true;
325  consumedItem = true;
326  result = lQuery.execute(opts).replace("&gt;", ">").replace("&lt;", "<");
327  } catch (Exception e) {
328  throw new XQException("Error getting stream: " + e.getLocalizedMessage());
329  } finally {
330  if (!preparedExpression) {
331  lQuery.delete();
332  }
333  }
334  return result;
335  }
336 
337  /** \brief Checks if the current position is after the last item in the sequence.
338  *
339  * Calling this method on an empty sequence will return false.
340  *
341  * @return true if the current position is after the last item, false otherwise
342  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state
343  */
344  @Override
345  public boolean isAfterLast() throws XQException {
346  isClosedXQException();
347  throw new XQException("This sequence is forward-only");
348  }
349 
350  /** \brief Checks if the current position before the first item in the sequence.
351  *
352  * Calling this method on an empty sequence will return false.
353  *
354  * @return true if the current position is before the first item, false otherwise
355  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state
356  */
357  @Override
358  public boolean isBeforeFirst() throws XQException {
359  isClosedXQException();
360  throw new XQException("This sequence is forward-only");
361  }
362 
363  /** \brief Checks if the current position at the first item in the sequence.
364  *
365  * Calling this method on an empty sequence will return false.
366  *
367  * @return true if the current position is at the first item, false otherwise
368  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state
369  */
370  @Override
371  public boolean isFirst() throws XQException {
372  isClosedXQException();
373  throw new XQException("This sequence is forward-only");
374  }
375 
376  /** \brief Checks if the current position at the last item in the sequence.
377  *
378  * Calling this method on an empty sequence will return false.
379  *
380  * @return true if the current position is at the last item, false otherwise
381  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state
382  */
383  @Override
384  public boolean isLast() throws XQException {
385  isClosedXQException();
386  throw new XQException("This sequence is forward-only");
387  }
388 
389  /** \brief Moves to the last item in the sequence.
390  *
391  * This method returns true, if it was able to move to the last item in the sequence false, otherwise. Calling this method on an empty sequence will return false.
392  *
393  * @return true if the sequence was positioned on the last item, false otherwise
394  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state
395  */
396  @Override
397  public boolean last() throws XQException {
398  isClosedXQException();
399  throw new XQException("This sequence is forward-only");
400  }
401 
402  /** \brief Moves to the next item in the sequence.
403  *
404  * Calling this method on an empty sequence will return false.
405  *
406  * @return true if the new item is valid, false if there are no more items
407  * @throw XQException - if the sequence is in a closed state
408  */
409  @Override
410  public boolean next() throws XQException {
411  isClosedXQException();
412  Item lItem = new Item();
413  current = null;
414  if (iter.next(lItem)) {
415  current = new ZorbaXQResultItem(lItem, connection);
416  items.add(current);
417  delivered = false;
418  lItem.delete();
419  }
420  return (current != null);
421  }
422 
423  /** \brief Moves to the previous item in the sequence.
424  *
425  * Calling this method on an empty sequence will return false.
426  *
427  * @return true if the new current position is within the sequence, (i.e., not before first); false otherwise.
428  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state.
429  */
430  @Override
431  public boolean previous() throws XQException {
432  isClosedXQException();
433  throw new XQException("This sequence is forward-only");
434  }
435 
436  /** \brief Moves the cursor a relative number of items.
437  *
438  * Moves the cursor a relative number of items, either positive or negative. Attempting to move beyond the first/last item in the sequence positions the sequence before/after the the first/last item. Calling relative(0) is valid, but does not change the cursor position.
439  * Note: Calling the method relative(1) is identical to calling the method next and calling the method relative(-1) is identical to calling the method previous(). Calling this method on an empty sequence will return false.
440  *
441  * @param i - the item position to jump to
442  * @return true if the new current position is within the sequence (i.e., not before first or after last); false otherwise.
443  * @throw XQException - if (1) the sequence is forward only, or (2) the sequence is in a closed state.
444  */
445  @Override
446  public boolean relative(int i) throws XQException {
447  isClosedXQException();
448  throw new XQException("This sequence is forward-only");
449  }
450 
451  /** \brief Serializes the sequence starting from the current position to an OutputStream.
452  *
453  * Serializes the sequence starting from the current position to an OutputStream according to the XSLT 2.0 and XQuery 1.0 serialization. Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information. Reading the sequence during the serialization process performs implicit next operations to read the items. After all items are written to the stream, the current position of the cursor is set to point after the last item. Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods.
454  *
455  * @param out - the output stream into which the sequence is to be serialized
456  * @param prprts - specifies the serialization parameters, null is considered equivalent to an empty Properties object
457  * @throw XQException - if (1) there are errors accessing the items in the sequence, (2) there are errors during serialization, (3) the sequence is in a closed state, (4) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (5) the os parameter is null
458  */
459  @Override
460  public void writeSequence(OutputStream out, Properties prprts) throws XQException {
461  isClosedXQException();
462  isNullXQException(out);
463  if (isOnItem()) {
464  getItem().writeItem(out, prprts);
465  }
466  while (next()) {
467  getItem().writeItem(out, prprts);
468  }
469  }
470 
471  /** \brief Serializes the sequence starting from the current position to a Writer.
472  *
473  * Serializes the sequence starting from the current position to a Writer according to the XSLT 2.0 and XQuery 1.0 serialization. Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.
474  *
475  * Warning: When outputting to a Writer, make sure the writer's encoding matches the encoding parameter if specified as a property or the default encoding.
476  *
477  * Reading the sequence during the serialization process performs implicit next operations to read the items. After all items are written to the stream, the current position of the cursor is set to point after the last item. Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods.
478  *
479  * @param writer - the writer object into which the sequence is to be serialized
480  * @param prprts - specifies the serialization parameters, null is considered equivalent to an empty Properties object
481  * @throw XQException - if (1) there are errors accessing the items in the sequence, (2) there are errors during serialization, (3) the sequence is in a closed state, (4) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (5) the ow parameter is null
482  */
483  @Override
484  public void writeSequence(Writer writer, Properties prprts) throws XQException {
485  isClosedXQException();
486  isNullXQException(writer);
487  if (isOnItem()) {
488  getItem().writeItem(writer, prprts);
489  }
490  while (next()) {
491  getItem().writeItem(writer, prprts);
492  }
493  }
494 
495  /** \brief Writes the entire sequence starting from the current position to a SAX handler.
496  *
497  * Writes the entire sequence starting from the current position to a SAX handler, as described in Section 12.2 Serializing an XDM instance into a SAX event stream, XQuery API for Java (XQJ) 1.0. Note that the serialization process might fail, in which case a XQException is thrown. After all items are written to the stream, the current position of the cursor is set to point after the last item. Also, in the case of forward only sequences, this method may only be called if the current item has not yet been read through any of the get or write methods. The specified org.xml.sax.ContentHandler can optionally implement the org.xml.sax.LexicalHandler interface. An implementation must check if the specified ContentHandler implements LexicalHandler. If the handler is a LexicalHandler comment nodes are reported, otherwise they will be silently ignored.
498  *
499  * @param ch - the SAX content handler, optionally a lexical handler
500  * @throw XQException - if (1) there are errors accessing any of the items in the sequence, (2) the sequence is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, (4) in case of an error during serializing the XDM instance into a SAX event stream, or (5) the saxhdlr parameter is null
501  */
502  @Override
503  public void writeSequenceToSAX(ContentHandler ch) throws XQException {
504  isClosedXQException();
505  isNullXQException(ch);
506  if (isOnItem()) {
507  getItem().writeItemToSAX(ch);
508  }
509  while (next()) {
510  getItem().writeItemToSAX(ch);
511  }
512  }
513 
514  /** \brief Writes the entire sequence starting from the current position to a Result.
515  *
516  * First the sequence is normalized as described in XSLT 2.0 and XQuery 1.0 serialization. Subsequently it is serialized to the Result object.
517  * Note that the normalization process can fail, in which case an XQException is thrown. An XQJ implementation must at least support the following implementations:
518  * - javax.xml.transform.dom.DOMResult
519  * - javax.xml.transform.sax.SAXResult
520  * - javax.xml.transform.stream.StreamResult
521  *
522  * @param result - the result object into which the sequence is to be serialized
523  * @throw XQException - if (1) there are errors accessing any of the items in the sequence, (2) the sequence is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, (4) in case of an error while serializing the sequence into the Result object, or (5) the result parameter is null
524  */
525  @Override
526  public void writeSequenceToResult(Result result) throws XQException {
527  isClosedXQException();
528  isNullXQException(result);
529  if (isOnItem()) {
530  getItem().writeItemToResult(result);
531  }
532  while (next()) {
533  getItem().writeItemToResult(result);
534  }
535  }
536 
537  /** \brief Gets the current item as a boolean.
538  *
539  * The current item must be an atomic value of type xs:boolean or a subtype.
540  *
541  * @return a boolean representing the current item
542  * @throw XQException - if (1) the conversion of the current item to a boolean fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item
543  */
544  @Override
545  public boolean getBoolean() throws XQException {
546  isClosedXQException();
547  isOnItemXQException();
548  return getItem().getBoolean();
549  }
550 
551  /** \brief Gets the current item as a byte.
552  *
553  * The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of byte.
554  *
555  * @return a byte representing the current item
556  * @throw XQException - if (1) the conversion of the current item to a byte fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item
557  */
558  @Override
559  public byte getByte() throws XQException {
560  isClosedXQException();
561  isOnItemXQException();
562  return getItem().getByte();
563  }
564 
565  /** \brief Gets the current item as a double.
566  *
567  * The current item must be an atomic value of type xs:double or a subtype.
568  *
569  * @return a double representing the current item
570  * @throw XQException - if (1) the conversion of the current item to a double fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item
571  */
572  @Override
573  public double getDouble() throws XQException {
574  isClosedXQException();
575  isOnItemXQException();
576  return getItem().getDouble();
577  }
578 
579  /** \brief Gets the current item as a float.
580  *
581  * The current item must be an atomic value of type xs:float or a subtype.
582  *
583  * @return a float representing the current item
584  * @throw XQException - if (1) the conversion of the current item to a float fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item
585  */
586  @Override
587  public float getFloat() throws XQException {
588  isClosedXQException();
589  isOnItemXQException();
590  return getItem().getFloat();
591  }
592 
593  /** \brief Gets the current item as an int.
594  *
595  * The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of int.
596  *
597  * @return an int representing the current item
598  * @throw XQException - if (1) the conversion of the current item to a int fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item
599  */
600  @Override
601  public int getInt() throws XQException {
602  isClosedXQException();
603  isOnItemXQException();
604  return getItem().getInt();
605  }
606 
607  /** \brief Gets the type of the item.
608  *
609  * On a forward only sequence this method can be called independent of any other get or write method. It will not raise an error if such method has been called already, nor will it affect subsequent invocations of any other get or write method.
610  *
611  * @return the type of the item
612  * @throw XQException - if (1) there are errors accessing the type of the item, or (2) the underlying sequence or item is in a closed state
613  */
614  @Override
615  public XQItemType getItemType() throws XQException {
616  isClosedXQException();
617  isOnItemXQException();
618  return current.getItemType();
619  }
620 
621  /** \brief Gets the current item as a Java String.
622  *
623  * The current item must be an atomic value. This function casts the current item to an xs:string value according to the casting rules defined in 17.1.2 Casting to xs:string and xs:untypedAtomic, XQuery 1.0 and XPath 2.0 Functions and Operators, and then returns the value as a Java String.
624  *
625  * @return the string representation of the item
626  * @throw XQException - if (1) there are errors accessing the item's value, (2) the item is not an atomic value, (3) there is an error when casting the item to a string representation, (4) the underlying sequence or item is in a closed state, or (5) in the case of forward only sequences, a get or write method was already invoked on the current item
627  */
628  @Override
629  public String getAtomicValue() throws XQException {
630  isClosedXQException();
631  isOnItemXQException();
632  return getItem().getAtomicValue();
633  }
634 
635  /** \brief Gets the current item as a long.
636  *
637  * The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of long.
638  *
639  * @return a long representing the current item
640  * @throw XQException - if (1) the conversion of the current item to a long fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item
641  */
642  @Override
643  public long getLong() throws XQException {
644  isClosedXQException();
645  isOnItemXQException();
646  return getItem().getLong();
647  }
648 
649  /** \brief Gets the item as a DOM node.
650  *
651  * The current item must be a node. The type of the returned DOM node is governed by Table 7 - XQuery Node Types and Corresponding Java Object Types XQuery API for Java (XQJ) 1.0 The instance of the returned node is implementation dependent. The node may be a reference or a copy of the internal state of the item. It is advisable to make a copy of the node if the application plans to modify it.
652  *
653  * @return a DOM node representing the current item
654  * @throw XQException - if (1) if there are errors accessing the current item, (2) the current item is not a node, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item
655  */
656  @Override
657  public Node getNode() throws XQException {
658  isClosedXQException();
659  isOnItemXQException();
660  return getItem().getNode();
661  }
662 
663  /** \brief Returns the URI for this item.
664  *
665  * If the item is a document node, then this method returns the absolute URI of the resource from which the document node was constructed. If the document URI is not available, then the empty string is returned. If the document URI is available, the returned value is the same as if fn:document-uri were evaluated on this document node. If the item is of a node kind other than document node, then the returned URI is implementation-defined.
666  * On a forward only sequence this method can be called independent of any other get or write method. It will not raise an error if such method has been called already, nor will it affect subsequent invocations of any other get or write method on the current item.
667  *
668  * @return the document URI for this document node or the empty string if not available. For other node kinds, the result is implementation-defined
669  * @throw XQException - if (1) if there are errors accessing the current item, (2) the current item is not a node, (3) if the underlying sequence or item is in a closed state
670  */
671  @Override
672  public URI getNodeUri() throws XQException {
673  isClosedXQException();
674  isOnItemXQException();
675  return current.getNodeUri();
676  }
677 
678  /** \brief Gets the current item as an Object.
679  *
680  * The data type of the returned object will be the Java Object type as specified in 14.4 Mapping an XQuery Atomic Value to a Java Object Type and 14.5 Mapping an XQuery Node to a Java Object Type, XQuery API for Java (XQJ) 1.0.
681  *
682  * @return an object representing the current item
683  * @throw XQException - if (1) if there are errors accessing the current item, (2) if the underlying sequence or item is in a closed state, or (3) in the case of forward only sequences, a get or write method was already invoked on the current item
684  */
685  @Override
686  public Object getObject() throws XQException {
687  isClosedXQException();
688  isOnItemXQException();
689  return getItem().getObject();
690  }
691 
692  /** \brief Read the current item as an XMLStreamReader object.
693  *
694  * Read the current item as an XMLStreamReader object, as described in Section 12.1 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0. Note that the serialization process might fail, in which case a XQException is thrown. While the stream is being read, the application MUST NOT do any other concurrent operations on the underlying item or sequence. The operation on the stream is undefined if the underlying sequence is repositioned or the state of the underlying item or sequence is changed by concurrent operations.
695  *
696  * @return an XML reader object as XMLStreamReader
697  * @throw XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) in case of an error during serialization of the current item into a StAX event stream as defined in Section 12.1 Serializing an XDM instance into a StAX event stream (XMLStreamReader), XQuery API for Java (XQJ) 1.0
698  */
699  @Override
700  public XMLStreamReader getItemAsStream() throws XQException {
701  isClosedXQException();
702  isOnItemXQException();
703  return getItem().getItemAsStream();
704  }
705 
706  /** \brief Serializes the current item according to the XSLT 2.0 and XQuery 1.0 serialization.
707  *
708  * Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.
709  *
710  * @param prprts - specifies the serialization parameters, null is considered equivalent to an empty Properties object
711  * @return the serialized representation of the item
712  * @throw XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, or (4) if there are errors during serialization
713  */
714  @Override
715  public String getItemAsString(Properties prprts) throws XQException {
716  isClosedXQException();
717  return getItem().getItemAsString(prprts);
718  }
719 
720  /** \brief Gets the current item as a short.
721  *
722  * The current item must be an atomic value of type xs:decimal or a subtype, and its value must be in the value space of short.
723  *
724  * @return a short representing the current item
725  * @throw XQException - if (1) the conversion of the current item to a short fails, (2) if there are errors accessing the current item, (3) if the underlying sequence or item is in a closed state, or (4) in the case of forward only sequences, a get or write method was already invoked on the current item
726  */
727  @Override
728  public short getShort() throws XQException {
729  isClosedXQException();
730  return getItem().getShort();
731  }
732 
733  /** \brief Checks if the item "matches" an item type.
734  *
735  * Checks if the item "matches" an item type, as defined in 2.5.4.2 Matching an Item Type and an Item, XQuery 1.0: An XML Query Language. You can use this method to first check the type of the result before calling the specific get methods.
736  *
737  * Example -
738  * \code{.java}
739  * ...
740  * XQItemType strType = conn.createAtomicType(XQItemType.XQBASETYPE_STRING);
741  * XQItemType nodeType = conn.createNodeType();
742  *
743  * XQSequence result = preparedExpr.executeQuery();
744  * while (result.next())
745  * {
746  * // Generic check for node..
747  * if (result.instanceOf(nodeType))
748  * org.w3.dom.Node node = result.getNode();
749  * else if (result.instanceOf(strType))
750  * String str = result.getAtomicValue();
751  * }
752  *
753  *
754  * If either the type of the XQItemAccessor or the input XQItemType is not a built-in type, then this method is allowed to raise exception if it can NOT determine the instanceOf relationship due to the lack of the access of the XML schema that defines the user defined schema types if the XQMetaData.isUserDefinedXMLSchemaTypeSupported() method returns false.
755  * Otherwise, this method must determine if the type of the XQItemAccessor is an instance of the input XQItemType. Note even if isUserDefinedXMLSchemaTypeSupported() returns false, an XQJ implementation may still be able to determine the instanceOf relationship for certain cases involving user defined schema type. For example, if the type of an XQItemAccessor is of mySchema:hatSize sequence type and the input parameter XQItemType is of item() sequence type, the return value for instanceOf relationship should always be true even though the XQJ implementation does not know the precise type information of mySchema:hatSize type defined in XML schema 'mySchema'.
756  * \endcode
757  * @param xqit - item type to match
758  * @return true if this item matches the input item type as defined in 2.5.4.2 Matching an Item Type and an Item, XQuery 1.0: An XML Query Language, and false if it does not
759  * @throw XQException - if (1) there are errors accessing the item's type, (2) if the underlying sequence or item is in a closed state, (3) if the implementation is unable to determine the schema definition of a user defined schema type, or (4) the type parameter is null
760  */
761  @Override
762  public boolean instanceOf(XQItemType xqit) throws XQException {
763  isClosedXQException();
764  isOnItemXQException();
765  isNullXQException(xqit);
766  return current.instanceOf(xqit);
767  }
768 
769  /** \brief Serializes the current item to a Writer.
770  *
771  * Serializes the current item to a Writer according to XSLT 2.0 and XQuery 1.0 serialization. Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.
772  *
773  * @param out - the output stream into which the current item is to be serialized
774  * @param prprts - specifies the serialization parameters, null is considered equivalent to an empty Properties object
775  * @throw XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, (4) if there are errors during serialization, or (5) the os parameter is null
776  */
777  @Override
778  public void writeItem(OutputStream out, Properties prprts) throws XQException {
779  isClosedXQException();
780  isNullXQException(out);
781  isNullXQException(prprts);
782  getItem().writeItem(out, prprts);
783  }
784 
785  /** \brief Serializes the current item to a Writer.
786  *
787  * Serializes the current item to a Writer according to XSLT 2.0 and XQuery 1.0 serialization. Serialization parameters, which influence how serialization is performed, can be specified. Refer to the XSLT 2.0 and XQuery 1.0 serialization and Section 12 Serialization, XQuery API for Java (XQJ) 1.0 for more information.
788  *
789  * Warning: When outputting to a Writer, make sure the writer's encoding matches the encoding parameter if specified as a property or the default encoding.
790  * @param writer - the output stream into which the current item is to be serialized
791  * @param prprts - specifies the serialization parameters, null is considered equivalent to an empty Properties object
792  * @throw XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, (4) if there are errors during serialization, or (5) the os parameter is null
793  */
794  @Override
795  public void writeItem(Writer writer, Properties prprts) throws XQException {
796  isClosedXQException();
797  isNullXQException(writer);
798  isNullXQException(prprts);
799  getItem().writeItem(writer, prprts);
800  }
801 
802  /** \brief Writes the current item to a SAX handler.
803  *
804  * Writes the current item to a SAX handler, as described in in Section 12.2 Serializing an XDM instance into a SAX event stream, XQuery API for Java (XQJ) 1.0. Note that the serialization process might fail, in which case a XQException is thrown. The specified org.xml.sax.ContentHandler can optionally implement the org.xml.sax.LexicalHandler interface. An implementation must check if the specified ContentHandler implements LexicalHandler. If the handler is a LexicalHandler comment nodes are reported, otherwise they will be silently ignored.
805  *
806  * @param ch - the SAX content handler, optionally a lexical handler
807  * @throw XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, (4) in case of an error while serializing the XDM instance into a SAX event stream, or (5) the saxhdlr parameter is null
808  */
809  @Override
810  public void writeItemToSAX(ContentHandler ch) throws XQException {
811  isClosedXQException();
812  isNullXQException(ch);
813  getItem().writeItemToSAX(ch);
814  }
815 
816  /** \brief Writes the current item to a Result.
817  *
818  * First the item is normalized as described in XSLT 2.0 and XQuery 1.0 serialization. Subsequently it is serialized to the Result object.
819  * Note that the normalization process can fail, in which case an XQException is thrown. An XQJ implementation must at least support the following implementations:
820  * - javax.xml.transform.dom.DOMResult
821  * - javax.xml.transform.sax.SAXResult
822  * - javax.xml.transform.stream.StreamResult
823  *
824  * @param result - the result object into which the item is to be serialized
825  * @throw XQException - if (1) there are errors accessing the current item or the underlying sequence, (2) the underlying sequence or item is in a closed state, (3) in the case of a forward only sequence, a get or write method has already been invoked on the current item, (4) in case of an error while serializing the current item into the Result object, or (5) the result parameter is null
826  */
827  @Override
828  public void writeItemToResult(Result result) throws XQException {
829  isClosedXQException();
830  isNullXQException(result);
831  getItem().writeItemToResult(result);
832  }
833 
834  /** \brief Returns a StaticCollectionManager.
835  *
836  * Returns a CollectionManager responsible for all collections which are statically declared in the static context of this query (main module) or any transitively imported library module.
837  * The collection manager provides a set of functions for managing collections and their contents.
838  *
839  * @return ZorbaXQStaticCollectionManager The collection manager responsible for managing collections of this Sequence.
840  * @throw XQException - if the object is closed
841  */
843  isClosedXQException();
844  if (lStaticCollectionManager==null) {
845  lStaticCollectionManager = new ZorbaXQStaticCollectionManager(lQuery.getStaticCollectionManager());
846  }
847  return lStaticCollectionManager;
848  }
849 
850  private void isClosedXQException() throws XQException {
851  if (closed) {
852  throw new XQException("This sequence is closed");
853  }
854  }
855  private void isConsumedXQException() throws XQException {
856  if (consumedItem) {
857  throw new XQException("Items already consumed");
858  }
859  }
860  private void isItemDeliveredXQException() throws XQException {
861  if (delivered) {
862  throw new XQException("Item already consumed");
863  }
864  }
865  private void isOnItemXQException() throws XQException {
866  if (current==null) {
867  throw new XQException("There are no more items to consume");
868  }
869  }
870 
871  private void isNullXQException(Object value) throws XQException {
872  if (value==null) {
873  throw new XQException("Parameter shouldn't be null");
874  }
875  }
876 }