/****************************************************************************
 *   rt.h : 
 *   		header file for RTree class.
 *
 *   Change Log :
 *		  09-17-1997 Initial version,  Liujian Qian
 *
 *   $Id: rt.h,v 1.4 1998/07/19 19:03:30 qian Exp $
 ***************************************************************************/
#ifndef _RTREE_H_
#define _RTREE_H_

#include "rtbasic.h"
#include "rtnode.h"	//for RTree nodes
#include "rtstore.h"	//for RTree storage (page allocation etc)


/**
 * @internal
 * THe class for internal cursor structure
 */
struct RCursor_i
{
    REntryStk	stack;
    RPtrStk	path;
    
    RPred	pred;
    int		last_level;
    int	        n_records;	//number of records retrieved
    bool	no_more;
    bool	first;
    bool        in_use;        

    NOP		RCursor_i() :last_level(-1), no_more(1),first(1), in_use(0) {};

    void	init();
};



/**
 *   @short This class provides the RTree spatial index interface.
 *
 *    RTrees are  balanced multidimensional indexing structures. It is 
      an extension of B+Trees, and is initialy devised by Guttman (1984).
      RTrees can be used to index spatial objects such as points, lines
      and polygons. It uses the minimum bounding rectangl (MBR) as the
      abstracted representation of such spatial objects, and provides
      efficient lookup of objects based on their locations. 
      
      The RTree implemented here is similar to the generalized search
      tree (GiST) of Berkeley, but is a complete rewriting for the sake of
      simplicity and efficiency, as well as better integration w/ the rest
      of the GFC code.
      
      Each node (RNode) in an RTree is stored as a page in the disk file (object of 
      the RTStore class) A node contains a set of entries (REntry) of the form 
      <Key, Pointer >, where the  Key (RKey) is a MBR of type GRect, and the 
      Pointer may be a node ID or an object id, based on whether the entry is 
      in a non-leaf node or leaf  node.

      RTree class supports four types of search predicates, using the operator
      "EQUALS, OVERLAPS, CONTAINS, WITHIN".  Combination of such operators is not
      supported yet.

      This implementation is a version of Guttman's original RTree (using the
      poly-time spliting algorithm). There have been various extensions of RTree
      such as R*Tree, but they are not implemented here (yet).

*/
class RTree
{
    RTStore*	store;
    int		is_open;

    RCursor_i	*cursor_i;	 //internal cursors for searching
    static int	cur;		 //the cursor returned to user; will keep increasing
    const  int  max_cursor; //maximum # of concurrent searchings

public:
    /**
     */
    NOP			RTree();
    virtual             ~RTree();

    /**
     * create an empty RTree with the given name
     */
    virtual Result	create(const char* name);
    /**
     * open an existing RTree (for search/insertion etc)
     */
    virtual Result	open (const char* name);
    /**
     * close an open RTree (flush the storage etc)
     */
    virtual Result	close();

    /**
     * report the statistics (contained in the header).
     * This includes the total number of entries, nodes,
     * the bounding box, and the average occupancy of the
     * nodes.
     */
    virtual RTHdr*	stats();
    /**
     * travase and print all the nodes of the RTree nicely
     */
    virtual void	printAll();    
    /**
     */
    friend  ostream&	operator<<(ostream& os, const RTree& r);
        
    /**
     * Launch a search using the predicate p. It returns
     * a cursor (an integer), which indicates the next available
     * entry. The next() method is then subsequently called
     * to retrieve all the satisfying entries.
     */
    virtual int		search (const RPred& p);
    /**
     * retrieves the next availabe entry indicated by the cursor.
     * returns NULL if there is no more entries available, upon
     * which the cursor is closed and no longer valid.
     */
    virtual REntry*	next   (int cursor);

    /**
     * bulk load the pre-sorted entries from "file"
     */
    virtual Result	bulkLoad (const char* file);
    /**
     */
    virtual Result	insert (const REntry& e);
    /**
     */
    virtual Result	remove (const RPred& p);
    /**
     */
    virtual RNode*	readNode    (const RPtr& p);
    /**
     */
    virtual void	writeNode   (RNode* nd);

protected:
    
    virtual RTStore*	newStore    () ;
    virtual RNode*	newNode     () ;
    
       
    enum FunctionID {BAD=0, INSERT=1, CREATE=2, OPEN=3, CLOSE=4, SEARCH=5};
        
        

private:

    // does the real work of insertion
    
    Result		_insert	(const REntry& e, int level);
    //
    RNode*		pickLeaf (const RPtr& pg, const REntry& e, int level);
    //
    Result		split 	   (RNode** nd, const REntry& e);
    //
    Result		adjustKeys (RNode* nd, RNode **parent);
    //
    int			condenseTree(RNode* leaf);
    //
    Result		shortenTree ();
    //
    void		_print(const RPtr& p);
    
};



#endif

Documentation generated by lqian@lqian-sun on Wed Jul 14 09:36:10 EDT 1999