package com.dbxml.db.client;

/*
 * dbXML - Native XML Database
 * Copyright (C) 1999-2004  The dbXML Group, L.L.C.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 * $Id: ResultSetClient.java,v 1.2 2004/02/12 00:17:55 bradford Exp $
 */

import org.w3c.dom.Node;

import com.dbxml.util.dbXMLException;

/**
 * ResultSetClient is the standard interface for iterating over the results
 * of a query against a CollectionClient.
 */

public interface ResultSetClient {
   /**
    * getCollection returns the top-level Collection context.  Note
    * that this may not be the collection that individual results
    * belong to as the query may execute recursively over a
    * Collection tree.
    *
    * @return The Collection context
    */
   CollectionClient getCollection() throws dbXMLException;

   /**
    * getQueryStyle returns the QueryStyle (ex: XPath) for this Query
    * instance.
    *
    * @return The Query style
    */
   String getQueryStyle() throws dbXMLException;

   /**
    * getQueryString returns the String that was used to create the
    * Query instance.
    *
    * @return The Query String
    */
   String getQueryString() throws dbXMLException;

   /**
    * next moves the cursor down one object from its current position.
    * A ResultSet cursor is initially positioned before the
    * first object; the first call to the method next makes the
    * first object the current object; the second call makes the
    * second object the current object, and so on.
    *
    * @return true if there is another object, false otherwise
    */
   boolean next() throws dbXMLException;

   /**
    * close releases this ResultSet object's database
    * resources immediately instead of waiting for this to happen
    * when it is automatically closed.
    */
   void close() throws dbXMLException;

   /**
    * getCount returns the number of records returned or
    * modified by this query.  If this count is not available,
    * the query will return -1.
    *
    * @return The result/modified count
    */
   int getCount() throws dbXMLException;

   /**
    * getResult returns the result as a DOM Node structure.
    *
    * @return The result Node
    */
   Node getResult() throws dbXMLException;

   /**
    * getResultAsText returns the result as a Text String.
    *
    * @return The result String
    */
   String getResultAsText() throws dbXMLException;

   /**
    * getResultCollection returns the Collection context for the
    * current result in the cursor.
    *
    * @return The Collection context
    */
   CollectionClient getResultCollection() throws dbXMLException;

   /**
    * getResultKey return the Key for the current result in the
    * cursor.  Note that the key identifies the entire Document,
    * while the result may only be a fragment, in which case,
    * the key may be duplicated in the result set.
    */
   String getResultKey() throws dbXMLException;
}
