00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file Pluggable_Messaging.h 00006 * 00007 * Pluggable_Messaging.h,v 1.32 2006/04/20 12:37:17 jwillemsen Exp 00008 * 00009 * Interface for the TAO pluggable messaging framework. 00010 * 00011 * 00012 * @author Balachandran Natarajan <bala@cs.wustl.edu> 00013 */ 00014 //============================================================================= 00015 00016 #ifndef TAO_PLUGGABLE_MESSAGING_H 00017 #define TAO_PLUGGABLE_MESSAGING_H 00018 00019 #include /**/ "ace/pre.h" 00020 00021 #include "tao/TAO_Export.h" 00022 00023 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00024 # pragma once 00025 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00026 00027 #include "tao/Basic_Types.h" 00028 00029 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00030 class ACE_Time_Value; 00031 ACE_END_VERSIONED_NAMESPACE_DECL 00032 00033 TAO_BEGIN_VERSIONED_NAMESPACE_DECL 00034 00035 namespace CORBA 00036 { 00037 class Exception; 00038 } 00039 00040 class TAO_Target_Specification; 00041 class TAO_Pluggable_Reply_Params; 00042 class TAO_Pluggable_Reply_Params_Base; 00043 class TAO_Transport; 00044 class TAO_Operation_Details; 00045 class TAO_Target_Specification; 00046 class TAO_OutputCDR; 00047 class TAO_Queued_Data; 00048 class TAO_GIOP_Fragmentation_Strategy; 00049 00050 // @@ The more I think I about this class, I feel that this class need 00051 // not be a ABC as it is now. Instead we have these options 00052 // (1) Parametrize this class with the "Messaging Object". Then the 00053 // implementations can just redirect the request to the class 00054 // that it has been specialised with 00055 // (2) Use a bridge pattern here ie. the interface exposed by this 00056 // class will redirect the request to the implementation which 00057 // would be "right messaging" object. 00058 // Both of them feasible. If we are not going like templates much, (2) 00059 // is seems to be a better option. 00060 // I am going to take a closer look on this after my MS defense - 00061 // Bala 00062 00063 /** 00064 * @class TAO_Pluggable_Messaging 00065 * 00066 * @brief Generic definitions Messaging class. 00067 * 00068 * This interface tries to define generic methods that could be 00069 * different messaging protocols 00070 */ 00071 class TAO_Export TAO_Pluggable_Messaging 00072 { 00073 public: 00074 /// Dtor 00075 virtual ~TAO_Pluggable_Messaging (void); 00076 00077 /// Write the RequestHeader in to the @a cdr stream. The underlying 00078 /// implementation of the mesaging should do the right thing. 00079 virtual int generate_request_header ( 00080 TAO_Operation_Details &op, 00081 TAO_Target_Specification &spec, 00082 TAO_OutputCDR &cdr) = 0; 00083 00084 /// Write the RequestHeader in to the @a cdr stream. 00085 virtual int generate_locate_request_header ( 00086 TAO_Operation_Details &op, 00087 TAO_Target_Specification &spec, 00088 TAO_OutputCDR &cdr) = 0; 00089 00090 /** 00091 * Write the reply header 00092 * The reply header is a part of any messaging protocol. The 00093 * messaging protocol implementation would implement the way the 00094 * reply header is written. 00095 */ 00096 virtual int generate_reply_header ( 00097 TAO_OutputCDR &cdr, 00098 TAO_Pluggable_Reply_Params_Base ¶ms) = 0; 00099 00100 /** 00101 * Write the locate reply header 00102 * The locate reply header is a part of any messaging protocol. The 00103 * messaging protocol implementation would implement the way the 00104 * locate reply header is written. 00105 */ 00106 virtual int generate_locate_reply_header ( 00107 TAO_OutputCDR &cdr, 00108 TAO_Pluggable_Reply_Params_Base ¶ms) = 0; 00109 00110 virtual int generate_fragment_header (TAO_OutputCDR & cdr, 00111 CORBA::ULong request_id) = 0; 00112 00113 /// Format the message in the @a cdr. May not be needed in 00114 /// general. 00115 virtual int format_message (TAO_OutputCDR &cdr) = 0; 00116 00117 /// Do any initialisations that may be needed. 00118 virtual void init (CORBA::Octet major, 00119 CORBA::Octet minor) = 0; 00120 00121 /// Parse the details of the next message from the @a incoming 00122 /// and initializes attributes of @a qd. Returns 0 if the message 00123 /// header could not be parsed completely, returns a 1 if the message 00124 /// header could be parsed completely and returns -1 on error. As the 00125 /// parsed data is stored directly in @a qd, no state must be stored 00126 /// in instance of implementation. 00127 virtual int parse_next_message (ACE_Message_Block &incoming, 00128 TAO_Queued_Data &qd, /* out */ 00129 size_t &mesg_length) = 0; /* out */ 00130 00131 /// Extract the details of the next message from the @a incoming 00132 /// through @a qd. Returns 0 if the message header could not be 00133 /// parsed completely, returns a 1 if the message header could be 00134 /// parsed completely and returns -1 on error. 00135 virtual int extract_next_message (ACE_Message_Block &incoming, 00136 TAO_Queued_Data *&qd) = 0; 00137 00138 /// Check whether the node @a qd needs consolidation from @a incoming, 00139 /// @r 0 on success, -1 on error 00140 virtual int consolidate_node (TAO_Queued_Data *qd, 00141 ACE_Message_Block &incoming) = 0; 00142 00143 /// Parse the request message, make an upcall and send the reply back 00144 /// to the "request initiator" 00145 virtual int process_request_message (TAO_Transport *transport, 00146 TAO_Queued_Data *qd) = 0; 00147 00148 00149 /// Parse the reply message that we received and return the reply 00150 /// information through @a reply_info 00151 virtual int process_reply_message ( 00152 TAO_Pluggable_Reply_Params &reply_info, 00153 TAO_Queued_Data *qd) = 0; 00154 00155 00156 /// Generate a reply message with the exception @a ex. 00157 virtual int generate_exception_reply ( 00158 TAO_OutputCDR &cdr, 00159 TAO_Pluggable_Reply_Params_Base ¶ms, 00160 CORBA::Exception &ex) = 0; 00161 00162 /// Is the messaging object ready for processing BiDirectional 00163 /// request/response? 00164 virtual int is_ready_for_bidirectional (TAO_OutputCDR &msg) = 0; 00165 00166 /// Reset the messaging the object 00167 virtual void reset (void) = 0; 00168 00169 /// Header length 00170 virtual size_t header_length (void) const = 0; 00171 00172 /// Fragment header length 00173 virtual size_t fragment_header_length (CORBA::Octet major, 00174 CORBA::Octet minor) const = 0; 00175 00176 /// Accessor for the output CDR stream 00177 virtual TAO_OutputCDR &out_stream (void) = 0; 00178 00179 /// Consolidate newly received fragment with previously arrived 00180 /// associated fragments to achieve consolidated message. All 00181 /// fragments having been received previously are being managed 00182 /// within implementation. If reliable transport is used (like TCP) 00183 /// this operation will be invoked with fragments being received 00184 /// partially ordered, last fragment being received last. Otherwise 00185 /// If un-reliable transport is used (like UDP) fragments may be 00186 /// received dis-ordered, and must be ordered before consolidation 00187 /// within implementation. @return 0 on success and @a con_msg 00188 /// points to consolidated message, 1 if there are still fragmens 00189 /// outstanding, in case of error -1 is being returned. The 00190 /// implementation is responsible to release @a qd. 00191 virtual int consolidate_fragmented_message (TAO_Queued_Data *qd, 00192 TAO_Queued_Data *&con_msg) = 0; 00193 00194 /// Discard all fragments associated to request-id encoded in 00195 /// cancel_request. Transport implementaion guarantees that this 00196 /// operation will never be invoked // concurrently by multiplpe 00197 /// threads nor concurrently to consolidate_fragmented_message 00198 /// @return -1 on failure, 0 on success, 1 no fragment on stack 00199 /// relating to CancelRequest. 00200 virtual int discard_fragmented_message (const TAO_Queued_Data *cancel_request) = 0; 00201 00202 /// Outgoing GIOP message fragmentation strategy. 00203 virtual TAO_GIOP_Fragmentation_Strategy * fragmentation_strategy (void) = 0; 00204 }; 00205 00206 TAO_END_VERSIONED_NAMESPACE_DECL 00207 00208 #include /**/ "ace/post.h" 00209 00210 #endif /*TAO_PLUGGABLE_MESSAGING_H*/