home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / som30tk.zip / som30os2.zip / include / somos.idl < prev    next >
Text File  |  1996-12-24  |  20KB  |  435 lines
  1. //
  2. // COMPONENT NAME: somOS::Server
  3. //
  4. //  @(#) 1.4 src/somos/core/somos/somos.idl, somos, som3.0 9/3/96 18:22:40 [12/24/96 08:16:28]
  5. //
  6. //  25H7912  (C)  IBM Corporation 1994,1996 
  7. //
  8. // COMMENTS:
  9. //
  10. // This file defines the somOS module containing interfaces for
  11. //      Server, ServiceBase, ServiceBasePRef, ServiceBaseCORBA, ServiceBasePRefCORBA
  12. //
  13.  
  14. /*============================================================================*
  15.  *                                                                            *
  16.  * Classes defined in this module:                                            *
  17.  *     Server, ServiceBase,                                                   *
  18.  *     ServiceBasePRef, ServiceBaseCORBA, ServiceBasePRefCORBA                *
  19.  *                                                                            *
  20.  *                                                                            *
  21.  *----------------------------------------------------------------------------*
  22.  *                                                                            *
  23.  * Methods defined in this module:                                            *
  24.  *                                                                            *
  25.  *                                                                            *
  26.  *----------------------------------------------------------------------------*
  27.  *                                                                            *
  28.  * Classes used by this module:                                               *
  29.  *    SOMDServer, SOMObject,  CosObjectIdentity::IdentifiableObject           *
  30.  *                                                                            *
  31.  *============================================================================*/
  32.  
  33.  
  34. #ifndef SOMOS_IDL
  35. #define SOMOS_IDL
  36.  
  37. #include <somobj.idl>
  38. #include <somdserv.idl>
  39. #include <somdcprx.idl>
  40. #include <xmscssae.idl>
  41. #include <omgidobj.idl>
  42.  
  43. //#----------------------------------------------------------------------------#
  44. //# somOS module                                                               #
  45. //#----------------------------------------------------------------------------#
  46. //# This module provides the interfaces that will be used by the common        #
  47. //# services in order to manage persistent references, initializers, and       #
  48. //# uninitializers.                                                            #
  49. //#----------------------------------------------------------------------------#
  50.  
  51. module somOS {
  52.  
  53. //# Enum defining service ids for OMG services
  54.  
  55.     typedef enum service_id {
  56.         somOSNaming,
  57.         somOSEvents,
  58.         somOSLifeCycle,
  59.         somOSPersistence,
  60.         somOSSecurity,
  61.         somOSObjectIdentity,
  62.         somOSTransactions,
  63.         somOSConcurrecny,
  64.         somOSExternalization,
  65.         somOSAttributePersistence,
  66.         somOSLastEnum
  67.     } service_id_e;
  68.  
  69. //# Structure for holding the metastate of a single service
  70.  
  71.     typedef struct metastate_struct {
  72.         service_id_e svc_id;
  73.         unsigned short version_major;
  74.         unsigned short version_minor;
  75.         any service_metastate;
  76.     } metastate_struct_t;
  77.  
  78. //#----------------------------------------------------------------------------#
  79. //# This interface provides the operations that manage persistent references,  #
  80. //# persistent metastate for services, and object passivation                  #
  81. //#----------------------------------------------------------------------------#
  82.  
  83.     interface Server: SOMDServer {
  84.         SOMObject make_persistent_ref(in SOMObject referenced_object)
  85.             raises(SysAdminException::ExExists,
  86.                    SysAdminException::ExNotFound,
  87.                    SysAdminException::ExFailed,
  88.                    SysAdminException::ExFileIO);
  89.             // - Make an entry in the reference-data-table and persistent storage.
  90.             //   An empty metadata (place holder) is stored in the persistent storage.
  91.             // - If an entry already exists then no action is taken and the operation
  92.             //   is considered successful but the exception
  93.             //   SysAdminException::ExExists is returned (see RETURN value below).
  94.             // - RETURNS OBJECT_NIL              if unsuccessful
  95.             //           referenced_object        if successful
  96.  
  97.         void delete_ref(in SOMObject referenced_object)
  98.             raises(SysAdminException::ExNotFound,
  99.                    SysAdminException::ExFailed,
  100.                    SysAdminException::ExFileIO);
  101.             // Remove its entry in the persistent storage.
  102.             // It does not delete the in-memory object or the entry in reference-data-table.
  103.  
  104.         boolean has_persistent_ref(in SOMObject referenced_object);
  105.             // Indicate whether the specified object has a persistent reference.
  106.             // RETURNS TRUE iff an entry exists in reference-data-table or in the
  107.             //                  persistent storage, or it is a transaction ref.
  108.  
  109.         void passivate_object(in SOMObject referenced_object)
  110.             raises(SysAdminException::ExNotFound,
  111.                    SysAdminException::ExFileIO,
  112.                    SysAdminException::ExFailed);
  113.             // Capture and store the metastate,
  114.             // uninit_for_object_passivation (removes entries from reference table),
  115.             // and somdestruct 
  116.             // It DOES NOT delete references on persistent storage.
  117.  
  118.         void passivate_all_objects()
  119.             raises(SysAdminException::ExNotFound,
  120.                    SysAdminException::ExFileIO,
  121.                    SysAdminException::ExFailed);
  122.             // passivate all active objects.
  123.  
  124.         void store_service_metastate(in SOMObject referenced_object,
  125.                                      in service_id_e somos_service_id,
  126.                                      in any service_metadata)
  127.             raises(SysAdminException::ExNotFound,
  128.                    SysAdminException::ExFileIO,
  129.                    SysAdminException::ExFailed);
  130.             // Store the metastate (service_metadata) of a service (somos_service_id)
  131.             // for the specified object (referenced_object).
  132.  
  133.         void store_metastate(in SOMObject referenced_object)
  134.             raises(SysAdminException::ExNotFound,
  135.                    SysAdminException::ExFileIO,
  136.                    SysAdminException::ExFailed);
  137.             // Call capture on the specified object and put it in persistent storage.
  138.             // Stores metadata of all services.
  139.  
  140.         void restore_metastate(in SOMObject referenced_object)
  141.             raises(SysAdminException::ExNotFound,
  142.                    SysAdminException::ExFileIO,
  143.                    SysAdminException::ExFailed);
  144.             // Get metadata from persistent storage and call reinit() on
  145.             // referenced_object
  146.  
  147. //# Private methods
  148.  
  149.         #ifdef __SOMIDL__
  150.         implementation
  151.          {
  152.             callstyle = idl;
  153.             dllname = "somos.dll";
  154.             metaclass = SOMMSingleInstance;
  155.         majorversion  = 3;
  156.             minorversion  = 0;
  157. //# Overrides
  158.  
  159.             somdRefFromSOMObj: override;
  160.                 // If it is a SOMDObject or it is  not a Servicebase object or
  161.                 //   it is a transient ServiceBase object which is not a transaction
  162.                 //   object THEN let the SOMDServer handle it.
  163.                 // For a persistent ServiceBase object (i.e., which has an entry
  164.                 //    in reference-data-table), return a reference containing
  165.                 //    the entire key as reference data.
  166.                 // For a transaction object let transaction-manager handle it.
  167.  
  168.             somdSOMObjFromRef: override;
  169.                 // RETURNS OBJECT_NIL iff object cannot be successfully created
  170.                 // If it is SOM_ref then let SOMDServer handle it
  171.                 // If the reference is not in somOS::Server family, return OBJECT_NIL
  172.                 // If the reference is a transaction reference, let TR-Manager handle it
  173.                 // If there is an entry in reference-data-table then
  174.                 //      return object-ptr stored in it
  175.                 // Otherwise, verify that it is in persistent store, create a new
  176.                 //      instance using somNewNoInit, init_for_object_reactivation,
  177.                 //      reinit, and add to reference-data-table.
  178.  
  179.             somdCreateObj: override;
  180.                 // If the input class has descended from ServiceBase
  181.                 //      THEN call somNewNoInit; init_for_object_creation()
  182.                 //      ELSE let SOMDServer handle it.
  183.  
  184.             somdDeleteObj: override;
  185.                 // If it is a SOMDObject or not a ServiceBase object
  186.                 //      THEN let SOMDServer handle it
  187.                 //      ELSE uninit_for_object_destruction(); somDestruct()
  188.  
  189. //# The order in which the methods will appear in the method table
  190.  
  191.             releaseorder: make_persistent_ref,
  192.                           delete_ref,
  193.                           passivate_object,
  194.                           passivate_all_objects,
  195.                           store_metastate,
  196.                           restore_metastate,
  197.                           has_persistent_ref,
  198.                           store_service_metastate,
  199.                           private1,
  200.                           private2;
  201.         }; //# End of implementation
  202.         #endif //# __SOMIDL__
  203.     }; //# End of Server interface
  204.  
  205.  
  206. //#----------------------------------------------------------------------------#
  207. //# ServiceBase contains methods that allow somOS::Server to exchange          #
  208. //# metastate and properly initilialize and uninitialize objects during the    #
  209. //# object lifecycle. It also provides identity to an object.                  #
  210. //#----------------------------------------------------------------------------#
  211.  
  212.     interface ServiceBase: CosObjectIdentity::IdentifiableObject {
  213.  
  214.         //# Sequence for holding the metastate of all services
  215.  
  216.         typedef sequence<metastate_struct_t> metastate_t;
  217.  
  218.  
  219.         void reinit(in metastate_t meta_data);
  220.             // - somOS::Server calls this method when (1) an object is reactivated
  221.             //   (in somdSOMObjFromRef()) and (2) somOS::Server is asked to
  222.             //   restore_metastate().
  223.             // - Services should override it do reinitialization using meta_data.
  224.             // - reinitializes the identity metadata
  225.  
  226.         void capture(inout metastate_t meta_data);
  227.             // - somos::Server call this method from store_metastate().
  228.             // - Services should override this method to supply proper metadata.
  229.             // - Capture() must free typecode in
  230.             //          meta_data._buffer[service_id].service_metastate._type
  231.             //    and data in ...._buffer prior to filling it using SOMFree
  232.             // - Allocates memory to store metastate. It is somOS::Server's
  233.             //   resposibility to free the metastate returned by services.
  234.             // - captures identity metadata
  235.  
  236.         SOMObject GetInstanceManager( );
  237.             // - Returns the server object which is either 
  238.             //            an instance somOS::Server,
  239.             //        OR  an instance of SOMDServer,
  240.             //        OR  OBJECT_NIL
  241.             // This method is usually not overriden. 
  242.             // This method allows clients to get a reference to the server
  243.             // object. It is introduced as somdFindServer... methods have been
  244.             // deprecated.
  245.  
  246.         SOMObject init_for_object_creation( )
  247.             raises(SysAdminException::ExException,
  248.                    SysAdminException::ExInvalid);
  249.             // somOS::somOS::Server calls this method from somdCreateObj().
  250.             // - Services should override this method to do proper initialization
  251.             //   at the time of object creation. (if necessary)
  252.             // - it initializes the data for CosObjectIdentity
  253.  
  254.         SOMObject init_for_object_reactivation( );
  255.             // - somOS::Server calls this method when an object is reactivated
  256.             //   in somdSOMObjFromRef() (but prior to calling reinit())
  257.             // - Services should override this method to do proper initialization
  258.             //   at the time of object reactivation. (if necessary)
  259.  
  260.         SOMObject init_for_object_copy( );
  261.             // Abstract method.
  262.             // - Services should override this method to do proper initialization
  263.             //   at the time of object copy. (if necessary)
  264.  
  265.         void uninit_for_object_move();
  266.             // Abstract method.
  267.             // - Services should override this method to do proper uninitialization
  268.             //   at the time of object move. (if necessary)
  269.  
  270.         void uninit_for_object_passivation();
  271.             // - Asks somOS::Server to remove an entry from reference-data-table.
  272.             // - No exceptions are raised. If there is no entry in the
  273.             //   reference-data-table then the operation is considered to be successful.
  274.             // - somOS::Server calls this method when an object is passivated
  275.             //   (passivate_object()).
  276.             // - Services should override this method to do proper uninitialization
  277.             //   at the time of object passivation. (if necessary)
  278.  
  279.         void uninit_for_object_destruction();
  280.             // - somOS::Server calls this method when a properly initialized object
  281.             //   is destroyed. In particular, from somdDeleteObj().
  282.             // - Services should override this method to do proper uninitialization
  283.             //   at the time of object destruction. (if necessary)
  284.  
  285.  
  286.         #ifdef __SOMIDL__
  287.         implementation
  288.         {
  289.         majorversion  = 3;
  290.             minorversion  = 0;
  291.  
  292.             passthru C_h  =
  293.                 ""
  294.                 "#include <omgidobj.h>"
  295.                 "";
  296.             passthru C_xh =
  297.                 ""
  298.                 "#include <omgidobj.xh>"
  299.                 "";
  300.  
  301.         memory_management= corba;
  302.             callstyle = idl;
  303.             dllname = "somos.dll";
  304.  
  305. //# Overrides
  306.             somDefaultInit: override, init;     // For efficiency
  307.             somDestruct: override;              
  308.                 // Attempt to remove the entry for the object in the reference data table
  309.                 // by calling remove_from_reference_data_table on the server.
  310.  
  311.             override: is_identical,
  312.                       _get_constant_random_id;
  313.  
  314.             som_uuid: nodata;
  315.  
  316. //# The order in which the methods will appear in the method table
  317.  
  318.             releaseorder: reinit,
  319.                           capture,
  320.                           init_for_object_creation,
  321.                           init_for_object_reactivation,
  322.                           init_for_object_copy,
  323.                           uninit_for_object_move,
  324.                           uninit_for_object_passivation,
  325.                           uninit_for_object_destruction,
  326.                           private1,
  327.                           GetInstanceManager;
  328.         }; //# End of implementation
  329.         #endif //# __SOMIDL__
  330.     }; //# End of ServiceBase interface
  331.  
  332. //#----------------------------------------------------------------------------#
  333. //# ServiceBasePRef is a subclass of ServiceBase and it overrides              #
  334. //# init_for_object_creation() and uninit_for_object_destruction() to          #
  335. //# make and destroy persistent reference                                      #
  336. //#----------------------------------------------------------------------------#
  337.  
  338.     interface ServiceBasePRef : ServiceBase {
  339.  
  340.         #ifdef __SOMIDL__
  341.         implementation
  342.         {
  343.         majorversion  = 3;
  344.             minorversion  = 0;
  345.  
  346.             callstyle = idl;
  347.             dllname = "somos.dll";
  348.  
  349. //# Overrides
  350.  
  351.             somDefaultInit: override, init;     // For efficiency
  352.             somDestruct: override;              // For efficiency
  353.  
  354.             init_for_object_creation: override;
  355.                 // - somOS::Server calls this method from somdCreateObj().
  356.                 // - Performs initilialization for persistent objects by calling
  357.                 //   init_for_object_creation() on parent and make_persistent_ref()
  358.                 //   on somOS::server.
  359.                 // - Services should override this method to do proper
  360.                 //   initialization at the time of object creation. (if necessary)
  361.  
  362.             uninit_for_object_destruction: override;
  363.                 // - somOS::Server calls this method when a properly initialized object
  364.                 //   is destroyed. In particular, from somdDeleteObj().
  365.                 // - Performs uninitilialization for persistent objects by calling
  366.                 //   uninit_for_object_destruction() on parent and delete_ref()
  367.                 //   on somOS::server.
  368.  
  369.         }; //# End of implementation
  370.         #endif //# __SOMIDL__
  371.     };
  372.  
  373. //#----------------------------------------------------------------------------#
  374. //# ServiceBaseCorba is a subclass of ServiceBase and it overrides             #
  375. //# init_for_object_reactivation() to raise an exception.                      #
  376. //#----------------------------------------------------------------------------#
  377.  
  378.     interface ServiceBaseCORBA : ServiceBase {
  379.  
  380.         #ifdef __SOMIDL__
  381.         implementation
  382.         {
  383.         majorversion  = 3;
  384.             minorversion  = 0;
  385.  
  386.             callstyle = idl;
  387.             dllname = "somos.dll";
  388.  
  389. //# Overrides
  390.  
  391.             somDefaultInit: override, init;     // For efficiency
  392.             somDestruct: override;              // For efficiency
  393.  
  394.             init_for_object_reactivation: override;
  395.             // Raises the system exception ex_StExcep_INV_OBJREF
  396.             // - somOS::Server calls this method when an object is reactivated
  397.             //   in somdSOMObjFromRef() (but prior to calling reinit())
  398.             // - Services should override this method to do proper initialization
  399.             //   at the time of object reactivation. (if necessary)
  400.  
  401.         }; //# End of implementation
  402.         #endif //# __SOMIDL__
  403.     };
  404.  
  405. //#----------------------------------------------------------------------------#
  406. //# ServiceBasePRefCORBA is a subclass of                                      #
  407. //#     ServiceBasePRef and ServiceBaseCORBA                                   #
  408. //#----------------------------------------------------------------------------#
  409.  
  410.     interface ServiceBasePRefCORBA : ServiceBasePRef, ServiceBaseCORBA {
  411.  
  412.         #ifdef __SOMIDL__
  413.         implementation
  414.         {
  415.         majorversion  = 3;
  416.             minorversion  = 0;
  417.  
  418.             callstyle = idl;
  419.             dllname = "somos.dll";
  420.  
  421. //# Overrides
  422.  
  423.             somDefaultInit: override, init;     // For efficiency
  424.             somDestruct: override;              // For efficiency
  425.             init_for_object_reactivation: override, select = somOS_ServiceBaseCORBA;
  426.             // init_for_object_reactivation must follow the right path instead
  427.             // of default left path.
  428.  
  429.         }; //# End of implementation
  430.         #endif //# __SOMIDL__
  431.     };
  432.  
  433. }; //# End of somOS module
  434. #endif //# SOMOS_IDL
  435.