/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-    */
/* ex: set filetype=cpp softtabstop=4 shiftwidth=4 tabstop=4 cindent expandtab: */

/*
  $Id: cmnGenericObject.h,v 1.13 2007/04/26 19:33:57 anton Exp $

  Author(s):	Anton Deguet
  Created on:	2004-08-18

  (C) Copyright 2004-2007 Johns Hopkins University (JHU), All Rights
  Reserved.

--- begin cisst license - do not edit ---

This software is provided "as is" under an open source license, with
no warranty.  The complete license can be found in license.txt and
http://www.cisst.org/cisst/license.txt.

--- end cisst license ---

*/


/*!
  \file
  \brief Defines cmnGenericObject
*/

#ifndef _cmnGenericObject_h
#define _cmnGenericObject_h

#include <cisstCommon/cmnPortability.h>

#include <string>
#include <iostream>

#include <cisstCommon/cmnExport.h>


class cmnClassServicesBase;

/*!
  \brief Base class for high level objects.
  
  \ingroup cisstCommon
  
  \sa cmnClassRegister cmnClassServiceBase
*/
class CISST_EXPORT cmnGenericObject {
public:

    /*! Destructor.  Does nothing specific. */
    virtual ~cmnGenericObject(void) {};

    /*! Pure virtual method to access the class services.  The derived
      classes should always declare and implement this method using
      the macros #CMN_DECLARE_SERVICES,
      #CMN_DECLARE_SERVICES_INSTANTIATION and #CMN_IMPLEMENT_SERVICES.
      In NO WAY, a user should redefine/overload this method
      otherwise.
      
      \return A pointer on the class services.  This points to the
      unique instance of cmnClassServiceBase for a given class.

      \sa cmnClassRegister cmnClassServiceBase
    */  
    virtual cmnClassServicesBase* const Services(void) const = 0;

    
    /*! Formatted IO to a string.  This method relies on ToStream
      which should be overloaded for each class. */ 
    std::string ToString(void) const;

  
    /*! The default ToStream method returns the name of the class.
      This method must be overloaded to provide a useful message. */
    virtual void ToStream(std::ostream & outputStream) const;


    /*! Serialize the content of the object without any extra
        information, i.e. no class type nor format version.  The
        "receiver" is supposed to already know what to expect. */ 
    virtual void SerializeRaw(std::ostream & outputStream) const;

    /*! De-serialize the content of the object without any extra
      information, i.e. no class type nor format version. */
    virtual void DeSerializeRaw(std::istream & inputStream);

};


/*! Stream out operator. */
inline
std::ostream & operator << (std::ostream & output,
                            const cmnGenericObject & object) {
    object.ToStream(output);
    return output;
}



#endif // _cmnGenericObject_h


// ****************************************************************************
//                              Change History
// ****************************************************************************
//
// $Log: cmnGenericObject.h,v $
// Revision 1.13  2007/04/26 19:33:57  anton
// All files in libraries: Applied new license text, separate copyright and
// updated dates, added standard header where missing.
//
// Revision 1.12  2007/04/17 17:29:56  anton
// cmnGenericObject:  Added virtual methods for serialization.  See #149 and #252
//
// Revision 1.11  2006/11/20 20:33:19  anton
// Licensing: Applied new license to cisstCommon, cisstVector, cisstNumerical,
// cisstInteractive, cisstImage and cisstOSAbstraction.
//
// Revision 1.10  2006/11/03 04:28:00  anton
// cisstCommon: Major update of Doxygen documentation following changes re.
// ticket #234.
//
// Revision 1.9  2006/10/06 14:29:33  anton
// All libraries: Re-ordered #include to include cmnPortability.h before any
// other file, including system header files.
//
// Revision 1.8  2005/09/26 15:41:46  anton
// cisst: Added modelines for emacs and vi.
//
// Revision 1.7  2005/08/14 00:51:26  anton
// cisstCommon: Port to gcc-4.0 (use template<> for template specialization).
//
// Revision 1.6  2005/08/11 17:24:18  anton
// cmnGenericObject: Added ToString() and ToStream() methods for all classes
// derived from cmnGenericObject.  Updated cmnPath to reflect these changes.
// See also ticket #68.
//
// Revision 1.5  2005/07/06 02:32:57  anton
// cmnGenericObject: virtual method Services is now const and returns a const
// pointer.
//
// Revision 1.4  2005/05/19 19:29:00  anton
// cisst libs: Added the license to cisstCommon and cisstVector
//
// Revision 1.3  2004/10/25 13:52:05  anton
// Doxygen documentation:  Cleanup all the useless \ingroup.
//
// Revision 1.2  2004/09/03 19:32:03  anton
// cisstCommon: Documentation of the new log and class registration system,
// see check-in [718]
//
// Revision 1.1  2004/08/19 21:00:41  anton
// cisstCommon: Major update of the class register and class services.  This
// follows the numerous meetings regarding the registration of classes, the
// dynamic creation and the runtime type information.  Please see the LaTeX
// documents "Base class and base tools".  Other minor changes include:
// *: Two macros have been introduced, CMN_DECLARE_SERVICES and
// CMN_IMPLEMENT_SERVICES.  This solves the issue #31.
// *: Removed the cumbersome registered/not registered status which was
// introduced to allow users to set preferences before the class was
// registered.  The new design forces the registration before "main()".  This
// solves the issue #29.
// *: LoD is now logLoD which tells a bit more about this Level Of Detail.
// *: Test programs have been updated too.
//
//
// ****************************************************************************