Repository design

From OpenCog
Jump to: navigation, search

Things to think about: not all repository implementations will support all methods... these throw Repository::UnsupportedException when they are not supported (e.g. initialize).

Some methods are implemented by the Repository class, but implementations can have optimised versions (e.g. storeAtomBulk is a frequent one, especially for distributed databases)

Pluggable AtomSpace Indexes should also be able to be added to the repository.

// Various methods are not required to be supported by a repository, but are
// handy

class Repository
{
public:
    
    virtual ~Repository() {}

    /**
      * Check the repository to see if all the necessary tables etc are there.
      * @return true if repository appears to be set up.
      */
    virtual bool check();

    /** 
     * Return a pointer to a link of the indicated type and outset,
     * if it exists; else return NULL.
     */
    virtual Link * getLink(const Type, const std::vector<Handle>&) const = 0;

    /** 
     * Return a pointer to a node of the indicated type and name,
     * if it exists; else return NULL.
     */
    virtual Node * getNode(Type, const char *) const = 0;
    virtual Node * getNodeBulk(const std::vector<Type>&, const std::vector<const char *>&)
        const throw (UnsupportedException) = 0;

    /** 
     * Return a pointer to an Atom associated with the given
     * handle, if it exists; else return NULL.
     */
    virtual Atom * getAtom(const Handle) const = 0;

    /**
     * Return a vector containing the handles of the entire incoming
     * set of the indicated handle. 
     */
    virtual std::vector<Handle> getIncomingSet(const Handle) const = 0;

    /**
     * Recursively store the atom and anything in it's outgoing set.
     * If the atom is already in storage, this will update it's 
     * truth value, etc. (but will not update the atoms in the outgoing set).
     */
    virtual void storeAtom(const Handle) = 0;

    /** 
     * Recursively store a set of atoms and anything each atom's outgoing set.
     * If the atom is already in storage, this will update it's 
     * truth value, etc. (but will not update the atoms in the outgoing set).
     * @note This defaults to iteratively calling storeAtom, but individual
     * implementations can be more efficient with bulk updates.
     */
    virtual void storeAtomBulk (const std::vector<Handle>&);

    /**
      * Initialise the repository, by creating basic tables and indexes.
      * Muct checks that repository is empty first.
      * @note Perhaps we should do this in a shell script separate from the
      * server and leave it users to do?
      * @return true if initialization is successful
      */
    virtual bool initialize() throw (UnsupportedException);

    virtual createIndex(const IndexDefinition) = 0;
};