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