//
// COMPONENT NAME: somOS::Server
//
//  @(#) 1.4 src/somos/core/somos/somos.idl, somos, som3.0 9/3/96 18:22:40 [12/22/96 21:48:01]
//
//  25H7912  (C)  IBM Corporation 1994,1996 
//
// COMMENTS:
//
// This file defines the somOS module containing interfaces for
//      Server, ServiceBase, ServiceBasePRef, ServiceBaseCORBA, ServiceBasePRefCORBA
//

/*============================================================================*
 *                                                                            *
 * Classes defined in this module:                                            *
 *     Server, ServiceBase,                                                   *
 *     ServiceBasePRef, ServiceBaseCORBA, ServiceBasePRefCORBA                *
 *                                                                            *
 *                                                                            *
 *----------------------------------------------------------------------------*
 *                                                                            *
 * Methods defined in this module:                                            *
 *                                                                            *
 *                                                                            *
 *----------------------------------------------------------------------------*
 *                                                                            *
 * Classes used by this module:                                               *
 *    SOMDServer, SOMObject,  CosObjectIdentity::IdentifiableObject           *
 *                                                                            *
 *============================================================================*/


#ifndef SOMOS_IDL
#define SOMOS_IDL

#include <somobj.idl>
#include <somdserv.idl>
#include <somdcprx.idl>
#include <xmscssae.idl>
#include <omgidobj.idl>

//#----------------------------------------------------------------------------#
//# somOS module                                                               #
//#----------------------------------------------------------------------------#
//# This module provides the interfaces that will be used by the common        #
//# services in order to manage persistent references, initializers, and       #
//# uninitializers.                                                            #
//#----------------------------------------------------------------------------#

module somOS {

//# Enum defining service ids for OMG services

    typedef enum service_id {
        somOSNaming,
        somOSEvents,
        somOSLifeCycle,
        somOSPersistence,
        somOSSecurity,
        somOSObjectIdentity,
        somOSTransactions,
        somOSConcurrecny,
        somOSExternalization,
        somOSAttributePersistence,
        somOSLastEnum
    } service_id_e;

//# Structure for holding the metastate of a single service

    typedef struct metastate_struct {
        service_id_e svc_id;
        unsigned short version_major;
        unsigned short version_minor;
        any service_metastate;
    } metastate_struct_t;

//#----------------------------------------------------------------------------#
//# This interface provides the operations that manage persistent references,  #
//# persistent metastate for services, and object passivation                  #
//#----------------------------------------------------------------------------#

    interface Server: SOMDServer {
        SOMObject make_persistent_ref(in SOMObject referenced_object)
            raises(SysAdminException::ExExists,
                   SysAdminException::ExNotFound,
                   SysAdminException::ExFailed,
                   SysAdminException::ExFileIO);
            // - Make an entry in the reference-data-table and persistent storage.
            //   An empty metadata (place holder) is stored in the persistent storage.
            // - If an entry already exists then no action is taken and the operation
            //   is considered successful but the exception
            //   SysAdminException::ExExists is returned (see RETURN value below).
            // - RETURNS OBJECT_NIL              if unsuccessful
            //           referenced_object        if successful

        void delete_ref(in SOMObject referenced_object)
            raises(SysAdminException::ExNotFound,
                   SysAdminException::ExFailed,
                   SysAdminException::ExFileIO);
            // Remove its entry in the persistent storage.
            // It does not delete the in-memory object or the entry in reference-data-table.

        boolean has_persistent_ref(in SOMObject referenced_object);
            // Indicate whether the specified object has a persistent reference.
            // RETURNS TRUE iff an entry exists in reference-data-table or in the
            //                  persistent storage, or it is a transaction ref.

        void passivate_object(in SOMObject referenced_object)
            raises(SysAdminException::ExNotFound,
                   SysAdminException::ExFileIO,
                   SysAdminException::ExFailed);
            // Capture and store the metastate,
            // uninit_for_object_passivation (removes entries from reference table),
            // and somdestruct 
            // It DOES NOT delete references on persistent storage.

        void passivate_all_objects()
            raises(SysAdminException::ExNotFound,
                   SysAdminException::ExFileIO,
                   SysAdminException::ExFailed);
            // passivate all active objects.

        void store_service_metastate(in SOMObject referenced_object,
                                     in service_id_e somos_service_id,
                                     in any service_metadata)
            raises(SysAdminException::ExNotFound,
                   SysAdminException::ExFileIO,
                   SysAdminException::ExFailed);
            // Store the metastate (service_metadata) of a service (somos_service_id)
            // for the specified object (referenced_object).

        void store_metastate(in SOMObject referenced_object)
            raises(SysAdminException::ExNotFound,
                   SysAdminException::ExFileIO,
                   SysAdminException::ExFailed);
            // Call capture on the specified object and put it in persistent storage.
            // Stores metadata of all services.

        void restore_metastate(in SOMObject referenced_object)
            raises(SysAdminException::ExNotFound,
                   SysAdminException::ExFileIO,
                   SysAdminException::ExFailed);
            // Get metadata from persistent storage and call reinit() on
            // referenced_object

//# Private methods

        #ifdef __SOMIDL__
        implementation
         {
            callstyle = idl;
            dllname = "somos.dll";
            metaclass = SOMMSingleInstance;
	    majorversion  = 3;
            minorversion  = 0;
//# Overrides

            somdRefFromSOMObj: override;
                // If it is a SOMDObject or it is  not a Servicebase object or
                //   it is a transient ServiceBase object which is not a transaction
                //   object THEN let the SOMDServer handle it.
                // For a persistent ServiceBase object (i.e., which has an entry
                //    in reference-data-table), return a reference containing
                //    the entire key as reference data.
                // For a transaction object let transaction-manager handle it.

            somdSOMObjFromRef: override;
                // RETURNS OBJECT_NIL iff object cannot be successfully created
                // If it is SOM_ref then let SOMDServer handle it
                // If the reference is not in somOS::Server family, return OBJECT_NIL
                // If the reference is a transaction reference, let TR-Manager handle it
                // If there is an entry in reference-data-table then
                //      return object-ptr stored in it
                // Otherwise, verify that it is in persistent store, create a new
                //      instance using somNewNoInit, init_for_object_reactivation,
                //      reinit, and add to reference-data-table.

            somdCreateObj: override;
                // If the input class has descended from ServiceBase
                //      THEN call somNewNoInit; init_for_object_creation()
                //      ELSE let SOMDServer handle it.

            somdDeleteObj: override;
                // If it is a SOMDObject or not a ServiceBase object
                //      THEN let SOMDServer handle it
                //      ELSE uninit_for_object_destruction(); somDestruct()

//# The order in which the methods will appear in the method table

            releaseorder: make_persistent_ref,
                          delete_ref,
                          passivate_object,
                          passivate_all_objects,
                          store_metastate,
                          restore_metastate,
                          has_persistent_ref,
                          store_service_metastate,
                          private1,
                          private2;
        }; //# End of implementation
        #endif //# __SOMIDL__
    }; //# End of Server interface


//#----------------------------------------------------------------------------#
//# ServiceBase contains methods that allow somOS::Server to exchange          #
//# metastate and properly initilialize and uninitialize objects during the    #
//# object lifecycle. It also provides identity to an object.                  #
//#----------------------------------------------------------------------------#

    interface ServiceBase: CosObjectIdentity::IdentifiableObject {

        //# Sequence for holding the metastate of all services

        typedef sequence<metastate_struct_t> metastate_t;


        void reinit(in metastate_t meta_data);
            // - somOS::Server calls this method when (1) an object is reactivated
            //   (in somdSOMObjFromRef()) and (2) somOS::Server is asked to
            //   restore_metastate().
            // - Services should override it do reinitialization using meta_data.
            // - reinitializes the identity metadata

        void capture(inout metastate_t meta_data);
            // - somos::Server call this method from store_metastate().
            // - Services should override this method to supply proper metadata.
            // - Capture() must free typecode in
            //          meta_data._buffer[service_id].service_metastate._type
            //    and data in ...._buffer prior to filling it using SOMFree
            // - Allocates memory to store metastate. It is somOS::Server's
            //   resposibility to free the metastate returned by services.
            // - captures identity metadata

        SOMObject GetInstanceManager( );
            // - Returns the server object which is either 
            //            an instance somOS::Server,
            //        OR  an instance of SOMDServer,
            //        OR  OBJECT_NIL
            // This method is usually not overriden. 
            // This method allows clients to get a reference to the server
            // object. It is introduced as somdFindServer... methods have been
            // deprecated.

        SOMObject init_for_object_creation( )
            raises(SysAdminException::ExException,
                   SysAdminException::ExInvalid);
            // somOS::somOS::Server calls this method from somdCreateObj().
            // - Services should override this method to do proper initialization
            //   at the time of object creation. (if necessary)
            // - it initializes the data for CosObjectIdentity

        SOMObject init_for_object_reactivation( );
            // - somOS::Server calls this method when an object is reactivated
            //   in somdSOMObjFromRef() (but prior to calling reinit())
            // - Services should override this method to do proper initialization
            //   at the time of object reactivation. (if necessary)

        SOMObject init_for_object_copy( );
            // Abstract method.
            // - Services should override this method to do proper initialization
            //   at the time of object copy. (if necessary)

        void uninit_for_object_move();
            // Abstract method.
            // - Services should override this method to do proper uninitialization
            //   at the time of object move. (if necessary)

        void uninit_for_object_passivation();
            // - Asks somOS::Server to remove an entry from reference-data-table.
            // - No exceptions are raised. If there is no entry in the
            //   reference-data-table then the operation is considered to be successful.
            // - somOS::Server calls this method when an object is passivated
            //   (passivate_object()).
            // - Services should override this method to do proper uninitialization
            //   at the time of object passivation. (if necessary)

        void uninit_for_object_destruction();
            // - somOS::Server calls this method when a properly initialized object
            //   is destroyed. In particular, from somdDeleteObj().
            // - Services should override this method to do proper uninitialization
            //   at the time of object destruction. (if necessary)


        #ifdef __SOMIDL__
        implementation
        {
	    majorversion  = 3;
            minorversion  = 0;

            passthru C_h  =
                ""
                "#include <omgidobj.h>"
                "";
            passthru C_xh =
                ""
                "#include <omgidobj.xh>"
                "";

	    memory_management= corba;
            callstyle = idl;
            dllname = "somos.dll";

//# Overrides
            somDefaultInit: override, init;     // For efficiency
            somDestruct: override;              
                // Attempt to remove the entry for the object in the reference data table
                // by calling remove_from_reference_data_table on the server.

            override: is_identical,
                      _get_constant_random_id;

            som_uuid: nodata;

//# The order in which the methods will appear in the method table

            releaseorder: reinit,
                          capture,
                          init_for_object_creation,
                          init_for_object_reactivation,
                          init_for_object_copy,
                          uninit_for_object_move,
                          uninit_for_object_passivation,
                          uninit_for_object_destruction,
                          private1,
                          GetInstanceManager;
        }; //# End of implementation
        #endif //# __SOMIDL__
    }; //# End of ServiceBase interface

//#----------------------------------------------------------------------------#
//# ServiceBasePRef is a subclass of ServiceBase and it overrides              #
//# init_for_object_creation() and uninit_for_object_destruction() to          #
//# make and destroy persistent reference                                      #
//#----------------------------------------------------------------------------#

    interface ServiceBasePRef : ServiceBase {

        #ifdef __SOMIDL__
        implementation
        {
	    majorversion  = 3;
            minorversion  = 0;

            callstyle = idl;
            dllname = "somos.dll";

//# Overrides

            somDefaultInit: override, init;     // For efficiency
            somDestruct: override;              // For efficiency

            init_for_object_creation: override;
                // - somOS::Server calls this method from somdCreateObj().
                // - Performs initilialization for persistent objects by calling
                //   init_for_object_creation() on parent and make_persistent_ref()
                //   on somOS::server.
                // - Services should override this method to do proper
                //   initialization at the time of object creation. (if necessary)

            uninit_for_object_destruction: override;
                // - somOS::Server calls this method when a properly initialized object
                //   is destroyed. In particular, from somdDeleteObj().
                // - Performs uninitilialization for persistent objects by calling
                //   uninit_for_object_destruction() on parent and delete_ref()
                //   on somOS::server.

        }; //# End of implementation
        #endif //# __SOMIDL__
    };

//#----------------------------------------------------------------------------#
//# ServiceBaseCorba is a subclass of ServiceBase and it overrides             #
//# init_for_object_reactivation() to raise an exception.                      #
//#----------------------------------------------------------------------------#

    interface ServiceBaseCORBA : ServiceBase {

        #ifdef __SOMIDL__
        implementation
        {
	    majorversion  = 3;
            minorversion  = 0;

            callstyle = idl;
            dllname = "somos.dll";

//# Overrides

            somDefaultInit: override, init;     // For efficiency
            somDestruct: override;              // For efficiency

            init_for_object_reactivation: override;
            // Raises the system exception ex_StExcep_INV_OBJREF
            // - somOS::Server calls this method when an object is reactivated
            //   in somdSOMObjFromRef() (but prior to calling reinit())
            // - Services should override this method to do proper initialization
            //   at the time of object reactivation. (if necessary)

        }; //# End of implementation
        #endif //# __SOMIDL__
    };

//#----------------------------------------------------------------------------#
//# ServiceBasePRefCORBA is a subclass of                                      #
//#     ServiceBasePRef and ServiceBaseCORBA                                   #
//#----------------------------------------------------------------------------#

    interface ServiceBasePRefCORBA : ServiceBasePRef, ServiceBaseCORBA {

        #ifdef __SOMIDL__
        implementation
        {
	    majorversion  = 3;
            minorversion  = 0;

            callstyle = idl;
            dllname = "somos.dll";

//# Overrides

            somDefaultInit: override, init;     // For efficiency
            somDestruct: override;              // For efficiency
            init_for_object_reactivation: override, select = somOS_ServiceBaseCORBA;
            // init_for_object_reactivation must follow the right path instead
            // of default left path.

        }; //# End of implementation
        #endif //# __SOMIDL__
    };

}; //# End of somOS module
#endif //# SOMOS_IDL
