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