#ifndef _DAMLDB_IDAMLDB_HH
#define _DAMLDB_IDAMLDB_HH

#if defined (sun)
#  pragma ident "@(#)$Id: IDamlDB.hh,v 1.2 2002/04/09 02:04:46 neves Exp $"
#endif

#include "damldb/Export.hh"
#include "damldb/Portability.hh"
#include "damldb/Statement.hh"

#include <cstdlib>
#include <iostream>
#include <string>

#ifdef CCXX_NAMESPACES
namespace damldb {
USING(std);
#endif

  /** IDamlDB class is the main interface for accessing the damldb database.

      An IDamlDB conforming object can be obtained as follows:
      \begin{verbatim}

        #include <DAMLDB.hh>
	#include <IDamlDB.hh>

	int open_mode = ...;
	string datadir = ...;

	...

	DAMLDB::setDataDirectory(datadir);
	DAMLDB::set_open_mode(open_mode);
	IDamlDB& db = *DAMLDB::getInstance()->db;

	...
      \end{verbatim}
  */
  class __EXPORT IDamlDB {
  public:
    typedef size_t size_type;

  public:

    /** Append a resource record to the database.
	The fields of the resoure record are initialized to sane
	default values.
    */
    virtual void add_resource() = 0;

    /** Append the specified resource record to the database.
	@postcondition get_resource_count() == get_resource_count'() + 1
	@param resource the record to be appended.
    */
    virtual void add_resource(const Resource& resource) = 0;

    /** Return the number of Resource records in the database.
	The count includes all records appended by any add_resource
	method.
	@return the number of Resource records.
	@see add_resource
    */
    virtual size_type get_resource_count() const = 0;

    /** Return the Resource record associated with the specified ResourceID.
	@precondition 0 <= id < get_resource_count'()
	@param id the ResourceID of the record to return
	@return the specified Resource record
    */
    virtual const Resource& get_resource(const ResourceID& id) const = 0;

    /** Return the Resource record associated with the specified URI.
	@param uri the URI of a resource
	@return the specified Resource record
    */
    virtual const Resource& get_resource(const char* uri) = 0;

    /** Append a Statement record to the database.
	@postcondition get_statement_count() == get_statement_count'() + 1
	@param sourceURI the URI of the statement's source.
	@param subjectURI the URI of the statement's subject.
	@param predicateURI the URI of the statement's predicate.
	@param objectURI the URI of the statement's object.
	@return a new Statement record.
    */
    virtual const Statement& add_statement(const char* sourceURI,
					   const char* subjectURI,
					   const char* predicateURI,
					   const char* objectURI) = 0;

    /** Append a Statement record to the database.
	The required ResourceID must be obtained by via the 
	\emph{uri2resource} method.

	@precondition 0 <= sourceID < get_resource_count'()
	@precondition 0 <= subjectID < get_resource_count'()
	@precondition 0 <= predicateID < get_resource_count'()
	@precondition 0 <= objectID < get_resource_count'()
	@postcondition get_resource_count() == get_resource_count'()
	@postcondition get_statement_count() == get_statement_count'() + 1

	@param sourceID the ID of the statement's source.
	@param subjectID the ID of the statement's subject.
	@param predicateID the ID of the statement's predicate.
	@param objectID the ID of the statement's object.
	@return a new Statement record.
	@see uri2resource
    */
    virtual const Statement& add_statement(const ResourceID& sourceID,
					   const ResourceID& subjectID,
					   const ResourceID& predicateID,
					   const ResourceID& objectID) = 0;

    /** Append a Statement record to the database.
	@postcondition get_resource_count() == get_resource_count'()
	@postcondition get_statement_count() == get_statement_count'() + 1
	@param statement the Statement reccord to be appended.
	@return a new Statement record.
    */
    virtual const Statement& add_statement(const Statement& statement) = 0;

    /** Return the number of Statment records in the database.
	The count includes all records appended by any add_statement
	method.
	@return the number of Statement records.
	@see add_statement
    */
    virtual size_type get_statement_count() const = 0;

    /** Return the Statement record associated with the specified StatementID.
	@precondition 0 <= id < get_statement_count'()
	@param id the StatementID of the record to return
	@return the specified Statement record
    */
    virtual const Statement& get_statement(const StatementID& id) const = 0;

    /** Return the Resource record associated with the specified ResourceID.
	@precondition 0 <= resource < get_resoure_count'()
	@param resource the ResourceID of the record to return
	@param result a modifiable object used to compute the result.
	@return the specified Resource record
    */
    virtual const string& resource2uri(const ResourceID& resource, string& result) = 0;

    /** Return the ResourceID associated with the specified URI.
	If no such association exists, then one is created.
	@postcondition get_resource_count() >= get_resoure_count'()
	@param uri the URI of a resource
	@return the associated ResourceID
    */
    virtual ResourceID uri2resource(const char* uri) = 0;

    /** Synchronize damldb database buffers with the disk.
    */
    virtual void sync() = 0;

    /** Dump all Statement records to the specified output stream.

	Each record field is output as follows: statement[i].{field_name} = {value}
    */
    virtual void dump_statements(ostream& os) const = 0;

    /** Dump all Resource records to the specified output stream.

        Each record field is output as follows: resource[i].{field_name} = {value}
    */
    virtual void dump_resources(ostream& os) const = 0;

    /** Define a virtual destructor for this pure interface.
     */
    virtual ~IDamlDB() {}
  };

#ifdef CCXX_NAMESPACES
} // namespace damldb
#endif

#endif //!_DAMLDB_IDAMLDB_HH

// Emacs
// Local Variables:
// mode: c++
// c-basic-offset: 2
// End: