---

d_Extent.h

Go to the documentation of this file.

//------------------------------------------------------------------------------
#ifndef d_Extent_h
#define d_Extent_h 1

//------------------------------------------------------------------------------
#include "d_Iterator.h"

//------------------------------------------------------------------------------
template <class T> class _ODLL d_Varray;
template <class T> class _ODLL d_Ref;
class oRefSeg;
class _ODLL d_Database;
class _ODLL oStorage;
class _ODLL oQueryEngine;
//------------------------------------------------------------------------------

/**
 * The class Extent is a virtual collection of all objects of a class updated
 * automatically by the Orient engine.
 *
 * QUERIES:
 * Making a query on an Extent means to query all the objects of a class.
 *
 * LOCATION:
 * d_Extent.h
 *
 * USAGE:
 * d_Extent< <pers-class-name> >                <variable-name>;
 * 
 * Where:
 * 
 * <pers-class-name>:   persistent class to use
 * <variable-name>:     is the name of d_Extent object
 *
 * EXAMPLES:
 * d_Ref<Customer>                objCustomer;
 * d_Iterator< d_Ref<Customer> >  itCustomer;
 * d_Extent<Customer>             customers( &db );
 * 
 * itCustomer = customers.select( "Customer.code = 1" );
 * 
 * while( itCustomer.next( objCustomer ) )
 * {
 *    * DISPLAY OBJECT
 *   printf( "\nCode......: %d", objCustomer->code );
 *   printf( "\nName......: %s", objCustomer->name.c_str() );
 *   printf( "\nSurname...: %s", objCustomer->surname.c_str() );
 *   printf( "\nAge.......: %d", objCustomer->age );
 *   printf( "\nNotes.....: %s", objCustomer->notes.c_str() );
 * }
 *
 * SEE ALSO:
 * d_Iterator
 *
 * ODMG:
 * Compliant
 */

template <class T>
class _ODLL d_Extent
{
  public:

    /**
     * Create an d_Extent object.
     *
     * Creates an extent for class specified as template argument (<> bracets)
     * of database <iDb>. Parameter <iSubClasses> is not used but available
     * for ODMG compatibility.
     *
     * ODMG    :  Compliant 
     */
    d_Extent (const d_Database* iDb, d_Boolean iSubClasses = d_True);

    /**
     * Destructor.
     *
     * ODMG    :  Compliant 
     */
    ~d_Extent();


    /**
     * Returns total number of object in the extent.
     *
     * This is equal to the total of objects present in the database for that
     * class.
     *
     * ODMG    :  Compliant
     */
    unsigned long cardinality () const;

    /**
     * Returns true if the extent doesn't contain objects.
     *
     * ODMG    :  Compliant
     */
    d_Boolean is_empty () const;

    /**
     * Returns always false. It's maintained for compatibility with collection
     * classes.
     *
     * ODMG    :  Compliant
     */
    d_Boolean allows_duplicates () const;

    /**
     * Returns always false. It's maintained for compatibility with collection
     * classes.
     *
     * ODMG    :  Compliant
     */
    d_Boolean is_ordered () const;

    /**
     * Creates an iterator that points to the first element of extent and
     * returns it.
     *
     * SEE ALSO:  d_Iterator, begin()
     * ODMG    :  Compliant
     */
    d_Iterator< d_Ref<T> > create_iterator ();

    /**
     * Creates an iterator that points to the first element of extent and
     * returns it.
     *
     * It works like create_iterator() member and is maintained for
     * compatibility with C++ STL containers.
     *
     * SEE ALSO:  d_Iterator, create_iterator()
     * ODMG    :  Compliant
     */
    d_Iterator< d_Ref<T> > begin ();

    /**
     * Creates an iterator that points to the last element of extent and
     * returns it.
     *
     * Is maintained for compatibility with C++ STL containers.
     *
     * SEE ALSO:  d_Iterator, begin()
     * ODMG    :  Compliant
     */
    d_Iterator< d_Ref<T> > end ();

    /**
     * Makes a query on the extent.
     *
     * <iTextQuery> is the text of query to execute. It returns a reference
     * to the object that matches the query predicate.
     *
     * If more than one object matches the query, then only the first one
     * object scanned is returned.
     *
     * For best performance use this method instead of general select()
     * method when the field of research is unique and doesn't contain
     * duplicates. In this way the research will stop after the first,
     * and unique, match.
     *
     * SEE ALSO:  d_Ref, select()
     * ODMG    :  Compliant
     */
    d_Ref<T> select_element (const char* iTextQuery) const;
 
    /**
     * Makes a query on the extent.
     *
     * <iTextQuery> is the text of query to execute.
     *
     * It returns an iterator that point to the first object that matches
     * the query predicate. To browse the result set use d_Iterator object.
     *
     * SEE ALSO:  d_Iterator, d_Ref, select_element()
     * ODMG    :  Compliant
     */
    d_Iterator< d_Ref<T> > select (const char* iTextQuery);
 
    /**
     * Delete objects that satisfy query predicate.
     *
     * <iTextQuery> is the text of query to execute.
     *
     * SEE ALSO:  select()
     * ODMG    :  Extension
     */
    void deleteObjects (const char* iTextQuery);

    /**
     * Counts the number of objects that matches the query predicate.
     *
     * SEE ALSO:  select(), cardinality()
     * ODMG    :  Compliant
     */
    unsigned long count (const char* iTextQuery);
 
    /**
     *
     * SEE ALSO:  d_Iterator, d_Ref, select_element()
     * ODMG    :  Compliant
     */
    int query (d_Collection<d_Ref<T> >& iColl, const char* iTextQuery) const;
 
    /**
     * Returns true if there is at least one object that matches the query
     * predicate.
     *
     * SEE ALSO:  select_element(), select()
     * ODMG    :  Compliant
     */
    d_Boolean exists_element (const char* iTextQuery) const;

    /**
     * Set query language engine. This allow the user to change the language
     * for query at run-time just calling this method.
     *
     * Query engine must be previously registered in the oQueryEngineManager
     * object taken by oQueryEngineManager::getInstance() method.
     *
     * SEE ALSO:  oQueryEngineManager
     * ODMG    :  Extension
     */
    void setQueryEngine( const char* iQueryEngineName );


  protected:
    // Avoid copy constructor.
    d_Extent (const d_Extent<T>& iSource);
    // Avoid copy assignment.
    d_Extent<T>& operator = (const d_Extent<T>& iSource);

  private:
    // Internal.
    oQueryEngine* queryEngine;
    // Internal.
    oStorage* storage;
    // Internal.
    oClass* refClass;
    // Internal.
    d_Varray< d_Ref<T> > result;
    // Internal.
    d_Boolean subClasses;
    // Internal.
    bool        queryExecuted;
};
//------------------------------------------------------------------------------
template <class T>
inline d_Boolean d_Extent<T>::is_empty () const
{
  return ( cardinality() ? false : true );
}
//------------------------------------------------------------------------------
template <class T>
inline d_Boolean d_Extent<T>::allows_duplicates () const
{
  return false;
}
//------------------------------------------------------------------------------
template <class T>
inline d_Boolean d_Extent<T>::is_ordered () const
{
  return false;
}
//------------------------------------------------------------------------------
#include "d_Extent.cti"
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

#endif

---