Navigating with XSequenceCursor

The XSequenceCursor interface gives you a view of our sequence data.

A sequence in the XPath and XQuery Data Model contains zero or more atomic values, nodes, or a mixture of both. An instance of the XSequenceCursor interface always contains at least one item. If a sequence is empty, it is always represented by a null reference.

Tasks

• At any given time, an instance of the XSequenceCursor interface is positioned to give we access to one of the items in a sequence. It is positioned initially at the first item in the sequence; and we can move forward or backward in the sequence, one item at a time, using the toNext() or toPrevious() methods, respectively.

  If the toNext() method or toPrevious() method is able to position the XSequenceCursor instance to the next or previous item in the sequence-that is, if there actually is a next or previous item-the method returns true. If the XSequenceCursor instance is already positioned at the last item in the case of the toNext() method or the first item in the case of the toPrevious() method, the method returns false and the instance of the XSequenceCursor interface remains positioned at the same item as before the call.

  The typical way of processing a sequence contained in an instance of the XSequenceCursor interface is as shown in the following example:

  XFactory factory = XFactory.newInstance();
  XPathExecutable expr = factory.prepareXPath("1 to 10");
  XSequenceCursor exprResult = expr.execute();
  long sum = 0;
  
  // If exprResult is null, it means the result sequence is empty
  if (exprResult != null) {
      do {
          // Get each value as a primitive Java long value, and accumulate
          sum = sum + exprResult.getLongValue();
  
          // Advance exprResult to the next item in the sequence
      } while (exprResult.toNext());
  }
  
  System.out.println("Sum is " + sum);
  

  The XSequenceCursor interface extends the XItemView interface. Use the methods inherited from the XItemView interface to access the value and the type of the item in the sequence at which the XSequenceCursor is currently positioned.

• If the application needs to refer to more than one item in the sequence at the same time, we can call the method XSequenceCursor.getSingletonItem() to get an instance of the XItemView interface containing the data associated with the current item in the instance of the XSequenceCursor interface.

  If we change the position of that instance of the XSequenceCursor interface through a call to the toNext() method or the toPrevious() method, the instance of the XItemView interface that was returned by an earlier call to the XSequenceCursor.getSingletonItem() method will still refer to that earlier item.

  Consider the following example, which counts the number of items in a sequence that have the same type and value as the first item.

  XFactory factory = XFactory.newInstance();
  
  // Make a path expression whose result contains ordered part number as first item
  // and all part numbers used by products in the catalog as the subsequent items
  XPathExecutable expr =
      factory.prepareXPath(
          "string(/order/item/@part-num),doc('catalog.xml')/catalog/product/part/string(@part-num)");
  
  // Read the invoice file
  XSequenceCursor exprResult = expr.execute(new StreamSource(invoiceFile));
  
  int sameAsFirstCount = 0;
  
  // If exprResult is null, it means the result sequence is empty
  if (exprResult != null) {
      // Get the first item in the result sequence
      XItemView firstItem = exprResult.getSingletonItem();
  
      // currentItem always refers to the current item in the result sequence
      XItemView currentItem = exprResult;
      do {
          // Get the type of the first item
          XTypeConstants.Type itemType = firstItem.getValueType();
  
          // Ensure the type of the first item is the same as the type of
          // the current item, and compare their values as Java objects
          if (itemType == currentItem.getValueType()
                  && firstItem.getObjectValue(itemType)
                        .equals(currentItem.getObjectValue(itemType))) {
              sameAsFirstCount++;
          }
  
          //Advance exprResult (and currentItem) to the next item in the sequence
      } while (exprResult.toNext());
  }
  
  System.out.println("Number of items same as the first == "+(sameAsFirstCount-1));
  

  The variable firstItem is created by the XSequenceCursor.getSingletonItem() method, so it always refers to the first item in the sequence. The variable currentItem contains a reference to the XSequenceCursor object, however, so it is always positioned at the current item in the sequence.

• If we ever need to access the items in the sequence non-sequentially, we might find it convenient to use the exportAsList method on the XSequenceCursor interface.

  This method returns an instance of the java.util.List<XItemView> interface containing the items in your sequence in sequence order.