source: trunk/gsdl/src/recpt/recptproto.h@ 226

/**********************************************************************
 *
 * recptproto.h -- 
 * Copyright (C) 1999  The New Zealand Digital Library Project
 *
 * PUT COPYRIGHT NOTICE HERE
 *
 * $Id: recptproto.h 220 1999-03-31 23:44:49Z rjmcnab $
 *
 *********************************************************************/


#ifndef RECPTPROTO_H
#define RECPTPROTO_H

#include "gsdlconf.h"
#include "text_t.h"
#include "comtypes.h"

#if defined(GSDL_USE_OBJECTSPACE)
#  include <ospace\std\vector>
#elif defined(GSDL_USE_STL_H)
#  include <vector.h>
#else
#  include <vector>
#endif

#if defined(GSDL_USE_OBJECTSPACE)
#  include <ospace\std\iostream>
#elif defined(GSDL_USE_IOS_H)
#  include <iostream.h>
#else
#  include <iostream>
#endif


// recptproto is a generalisation of a protocol for communicating
// with a collection server.
class recptproto {
public:
  // configure should be called for each line in the configuration file
  virtual void configure (const text_t &key, const text_tarray &cfgline);

  // init should be called after the configuration but before any other
  // functions are called. If init returns false a message will be written
  // out to the log file and no other output should be produced.
  virtual bool init (ostream &logout);

  // get_protocol_name should return the name of this protocol (e.g. recptproto)
  // that can be used to do run time type identification and display information
  // about the protocol.
  virtual text_t get_protocol_name ();

  // get_collection_list returns the list of collections that
  // this protocol knows about
  virtual void get_collection_list (text_tarray &collist, comerror_t &err, 
                    ostream &logout);

  // has_collection sets 'hascollection' to be true if the protocol
  // can communicate with the collection (i.e. it is within its 
  // collection list). This function should be implemented in as
  // efficient time as possible as it will be called for each page
  // access and for each protocol.
  virtual void has_collection (const text_t &collection, bool &hascollection, 
                   comerror_t &err, ostream &logout);

  // sets 'wassuccess' to be true if a successful ping was done to
  // the given collection.
  virtual void ping (const text_t &collection, bool &wassuccess, 
             comerror_t &err, ostream &logout);

  // obtains general information about the collection
  virtual void get_collectinfo (const text_t &collection, 
                ColInfoResponse_t &collectinfo,
                comerror_t &err, ostream &logout);

  // gets a list of all the filters
  virtual void get_filterinfo (const text_t &collection,
                   InfoFiltersResponse_t &response,
                   comerror_t &err, ostream &logout);

  // gets all the filter options for a particular filter
  virtual void get_filteroptions (const text_t &collection,
                  const InfoFilterOptionsRequest_t &request,
                  InfoFilterOptionsResponse_t &response, 
                  comerror_t &err, ostream &logout);

  // filters (search or browse) a result set and returns information
  // about the filtered set including term frequency information and 
  // metadata
  virtual void filter (const text_t &collection,
               const FilterRequest_t &request,
               FilterResponse_t &response,
               comerror_t &err, ostream &logout);

  // just a dummy for now - not sure where or how this 
  // should be done - type should be one of hierarchy, book,
  // list, datelist or none. name should be one of subject,
  // date, title, author, series, howto, or organization
  virtual void get_classification_info (const text_t &/*OID*/, text_t &ctype, text_t &cname) {
    cname = "title";
    ctype = "list";
  }

  // return list of all classifications supported by this collection
  // e.g. "title", "subject" and "date". Should be tested somewhere I guess
  // to make sure all classifications are supported by this receptionist
  virtual void get_all_classifications (text_tarray &classifications) {
    classifications.push_back ("subject");
    classifications.push_back ("title");
    classifications.push_back ("series");
  }
};


// The recptprotoptr function does not 'own' the recptproto. The 
// recptproto should be deleted by the code which created it.
class recptprotoptr {
public:
  recptproto *p;

  recptprotoptr () {p=NULL;}
};

typedef vector<recptprotoptr> recptprotoptrlist;


// contains a list of recptprotos
class recptprotolistclass {
protected:
  recptprotoptrlist recptprotoptrs;

public:
  // type support for recptprotolistclass
  typedef recptprotoptrlist::iterator iterator;
  typedef recptprotoptrlist::const_iterator const_iterator;
  typedef recptprotoptrlist::reference reference;
  typedef recptprotoptrlist::const_reference const_reference;
  typedef recptprotoptrlist::size_type size_type;

  typedef recptprotoptrlist::difference_type difference_type;
  typedef recptprotoptrlist::const_reverse_iterator const_reverse_iterator;
  typedef recptprotoptrlist::reverse_iterator reverse_iterator;
  
  // basic container support
  iterator begin () {return recptprotoptrs.begin();}
  const_iterator begin () const {return recptprotoptrs.begin();}
  iterator end () {return recptprotoptrs.end();}
  const_iterator end () const {return recptprotoptrs.end();}

  void erase(iterator pos) {recptprotoptrs.erase(pos);}
  void erase(iterator first, iterator last) {recptprotoptrs.erase(first, last);}
  recptprotolistclass &operator=(const recptprotolistclass &x) 
    {recptprotoptrs=x.recptprotoptrs;return *this;}

  bool empty () const {return recptprotoptrs.empty();}
  size_type size() const {return recptprotoptrs.size();}


  // added functionality
  void clear () {recptprotoptrs.erase(recptprotoptrs.begin(),recptprotoptrs.end());}

  // therecptproto remains the property of the calling code but
  // should not be deleted until it is removed from this list.
  void addrecptproto (recptproto *therecptproto);

  // getrecptproto will return NULL if a recptproto for the given colelction
  // could not be found
  recptproto *getrecptproto (const text_t &collection, ostream &logout);
};


#endif