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: CollectionClient.java,v 1.3 2004/07/28 16:52:49 bradford Exp $
 */

import java.util.Map;

import org.w3c.dom.Document;

import com.dbxml.db.core.Collection;
import com.dbxml.util.dbXMLException;

/**
 * CollectionClient is the standard interface for working with a
 * dbXML Collection in a client/server fashion.
 */

public interface CollectionClient {
   static final int TYPE_DOCUMENTS = Collection.TYPE_DOCUMENTS;
   static final int TYPE_VALUES = Collection.TYPE_RECORDS;

   /**
    * getClient returns the dbXMLClient instance for this CollectionClient.
    *
    * @return The dbXMLClient instance
    */
   dbXMLClient getClient();

   /**
    * getName returns the name for this Object.
    *
    * @return The name
    */
   String getName() throws dbXMLException;

   /**
    * getCollectionType returns the type of Objects that the Collection
    * is allowed to store.  Currently this value can either be TYPE_DOCUMENTS
    * or TYPE_VALUES.
    *
    * @return The Collection type
    */
   int getCollectionType() throws dbXMLException;

   /**
    * getCanonicalName returns the canonical name for this Object.
    * <br>
    * ex: /local/test/ocs
    *
    * @return The canonical name
    */
   String getCanonicalName() throws dbXMLException;

   /**
    * getParentCollection returns the parent Collection of this
    * Collection.
    *
    * @return The parent CollectionClient
    */
   CollectionClient getParentCollection() throws dbXMLException;

   /**
    * getDatabase returns the Database owner for this Collection.
    *
    * @return The Database CollectionClient
    */
   CollectionClient getDatabase() throws dbXMLException;

   /**
    * getSystemCollection returns the System Collection.
    *
    * @return The System CollectionClient
    */
   CollectionClient getSystemCollection() throws dbXMLException;

   // Collection Management

   /**
    * getCollection retrieves a Collection by name.
    *
    * @param path The Collection path
    * @return The CollectionClient
    */
   CollectionClient getCollection(String name) throws dbXMLException;

   /**
    * createCollection creates a new Collection object and any associated
    * system resources that the Collection will need.
    *
    * @param path The relative path of the Collection
    * @param configuration The Collection's configuration
    * @return The newly created CollectionClient
    */
   CollectionClient createCollection(String path, Document configuration) throws dbXMLException;

   /**
    * listCollections retrieves a list of Collections as an array of
    * Strings.
    *
    * @return The Collection list
    */
   String[] listCollections() throws dbXMLException;

   /**
    * dropCollection physically removes the specified Collection and any
    * associated system resources that the Collection uses.
    *
    * @param collection The Collection to drop
    * @return Whether or not the Collection was dropped
    */
   boolean dropCollection(String name) throws dbXMLException;

   // Trigger Management

   /**
    * createTrigger creates a new Trigger object and any associated
    * system resources that the Trigger will need.
    *
    * @param configuration The Trigger's configuration
    * @return The newly created Trigger
    */
   String createTrigger(Document configuration) throws dbXMLException;

   /**
    * dropTrigger physically removes the specified Trigger and any
    * associated system resources that the Trigger uses.
    *
    * @param name The Trigger to drop
    * @return Whether or not the Trigger was dropped
    */
   boolean dropTrigger(String name) throws dbXMLException;

   /**
    * listTriggers returns a list of the currently registered Triggers
    * as an array of String.
    *
    * @return The Trigger list
    */
   String[] listTriggers() throws dbXMLException;

   // Index Management

   /**
    * createIndexer creates a new Indexer object and any associated
    * system resources that the Indexer will need.
    *
    * @param configuration The Indexer's configuration
    * @return The newly created Indexer
    */
   String createIndexer(Document configuration) throws dbXMLException;

   /**
    * dropIndexer physically removes the specified Indexer and any
    * associated system resources that the Indexer uses.
    *
    * @param name The Indexer to drop
    * @return Whether or not the Indexer was dropped
    */
   boolean dropIndexer(String name) throws dbXMLException;

   /**
    * listIndexers returns a list of the currently registered Indexers
    * as an array of String.
    *
    * @return The Indexer list
    */
   String[] listIndexers() throws dbXMLException;

   // Extension Management

   /**
    * getExtension retrieves an Extension by name.
    *
    * @param name The Extension's name
    * @return The Extension
    */
   String getExtension(String name) throws dbXMLException;

   /**
    * createExtension creates a new Extension object and any associated
    * system resources that the Extension will need.
    *
    * @param configuration The Extension's configuration
    * @return The newly created Extension
    */
   String createExtension(Document configuration) throws dbXMLException;

   /**
    * listExtensions returns a list of the currently registered Extensions
    * as an array of String.
    *
    * @return The Extension list
    */
   String[] listExtensions() throws dbXMLException;

   /**
    * dropExtension physically removes the specified Extension and any
    * associated system resources that the Extension uses.
    *
    * @param name The Extension to drop
    * @return Whether or not the Extension was dropped
    */
   boolean dropExtension(String name) throws dbXMLException;

   // Document Management

   /**
    * createKey creates a new Collection unique Key.  No
    * promises are made as to global uniqueness, but every
    * effort is made to ensure this.
    *
    * @return a new unique Key
    */
   String createKey() throws dbXMLException;

   /**
    * getDocument retrieves a Document by Key.
    *
    * @param docKey The Document Key
    * @return The Document
    */
   Document getDocument(String docKey) throws dbXMLException;

   /**
    * getDocumentAsText retrieves a Document by Key.
    *
    * @param docKey The Document Key
    * @return The Document
    */
   String getDocumentAsText(String docKey) throws dbXMLException;

   /**
    * getContent returns a ContentClient instance by Key.
    *
    * @param key The Content Key
    * @return The ContentClient
    */
   ContentClient getContent(String key) throws dbXMLException;

   /**
    * insertDocument inserts a new Document into a dbXML Collection.
    *
    * @param document The Document
    * @return The new Object Identifier
    */
   String insertDocument(Document document) throws dbXMLException;

   /**
    * insertDocumentAsText inserts a new Document into a dbXML
    * Collection.
    *
    * @param document The Document
    * @return The new Object Identifier
    */
   String insertDocumentAsText(String document) throws dbXMLException;

   /**
    * setDocument overwrites/updates an existing Document in a
    * dbXML Collection.
    *
    * @param docKey The Document Key
    * @param document The Document
    */
   void setDocument(String docKey, Document document) throws dbXMLException;

   /**
    * setDocumentAsText overwrites/updates an existing Document in
    * a dbXML Collection.
    *
    * @param docKey The Document Key
    * @param document The Document
    */
   void setDocumentAsText(String docKey, String document) throws dbXMLException;

   /**
    * remove removes an object from the Collection based on its Key,
    * regardless of its type.
    *
    * @param key The Object's Key
    */
   void remove(String docKey) throws dbXMLException;

   /**
    * listKeys returns a list of all Object keys stored by this
    * collection.
    *
    * @return the list of object keys
    */
   String[] listKeys() throws dbXMLException;

   /**
    * getKeyCount returns the count of Objects being maintained
    * by this Collection.
    *
    * @return The object count
    */
   long getKeyCount() throws dbXMLException;

   // Record Content Management

   /**
    * insertValue stores a binary Record in the Collection and
    * returns a newly generated Key.
    *
    * @param value The Value to store
    */
   String insertValue(byte[] value) throws dbXMLException;

   /**
    * setValue stores a binary Record in the Collection.
    *
    * @param key The Key to use
    * @param value The Value to store
    */
   void setValue(String key, byte[] value) throws dbXMLException;

   /**
    * getValue retrieves a binary Record from the Collection.
    *
    * @param key The Record's Key
    * @return The Record
    */
   byte[] getValue(String key) throws dbXMLException;

   // Query Processing

   /**
    * queryCollection performs a query against the current Collection
    * using the specified style and query String.
    *
    * @param style The query style to use (ex: XPath)
    * @param query The query to execute
    * @param nsMap The namespace Map (if any)
    * @return The ResultSetClient
    */
   ResultSetClient queryCollection(String style, String query, Map nsMap) throws dbXMLException;

   /**
    * queryDocument performs a query against a single Document using
    * the specified style, query string, and Document ID.
    *
    * @param style The query style to use (ex: XPath)
    * @param query The query to execute
    * @param nsMap The namespace Map (if any)
    * @param key The Document to query
    * @return The ResultSetClient
    */
   ResultSetClient queryDocument(String style, String query, Map nsMap, String key) throws dbXMLException;
}
