package com.dbxml.db.core.query;

/*
 * 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: QueryResolver.java,v 1.2 2004/02/12 00:17:57 bradford Exp $
 */

import com.dbxml.db.core.Collection;
import com.dbxml.db.core.data.Key;
import com.dbxml.db.core.transaction.Transaction;
import com.dbxml.util.Configurable;
import com.dbxml.xml.NamespaceMap;

/**
 * QueryResolver is an interface that has to be implemented to actually
 * perfrom query resolution.  dbXML provides an XPathQueryResolver to
 * handle XPath queries against sets of Documents in a Collection.
 */

public interface QueryResolver extends Configurable {
   /**
    * setQueryEngine hands a reference for the QueryEngine to the
    * Resolver.
    *
    * @param engine The QueryEngine
    */
   void setQueryEngine(QueryEngine engine);

   /**
    * getQueryStyle returns the Query style supported by this Resolver.
    *
    * @return The query style
    */
   String getQueryStyle();

   /**
    * compileQuery compiles a Query against the specified Collection
    * context and returns the compiled Query.  This DOES NOT actually
    * run the query, merely just parses it and primes any possible
    * Indexers that the query might need.
    *
    * @param context The Collection Context
    * @param query The Query
    * @param nsMap The namespace Map (if any)
    * @param keys The initial Key set to use (if any)
    * @return The compiled Query
    */
   Query compileQuery(Collection context, String query, NamespaceMap nsMap, Key[] keys) throws QueryException;

   /**
    * query compiles a Query against the specified Collection context
    * and returns the query results.
    *
    * @param tx The controlling Transaction
    * @param context The Collection Context
    * @param query The Query
    * @param nsMap The namespace Map (if any)
    * @param keys The initial Key set to use (if any)
    * @return The resulting ResultSet
    */
   ResultSet query(Transaction tx, Collection context, String query, NamespaceMap nsMap, Key[] keys) throws QueryException;

}
