TAO/tao/Transport_Connector.h

   1 //=============================================================================
   2 /**
   3  *  @file Transport_Connector.h
   4  *
   5  *  Define the interface for the Connector component in TAO's
   6  *  pluggable protocol framework.
   7  *
   8  *  @author  Fred Kuhns <fredk@cs.wustl.edu>
   9  */
  10 //=============================================================================
  11
  12 #ifndef TAO_CONNECTOR_H
  13 #define TAO_CONNECTOR_H
  14
  15 #include /**/ "ace/pre.h"
  16 #include "tao/Basic_Types.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include /**/ "tao/TAO_Export.h"
  23
  24 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  25 class ACE_Time_Value;
  26 ACE_END_VERSIONED_NAMESPACE_DECL
  27
  28 TAO_BEGIN_VERSIONED_NAMESPACE_DECL
  29
  30 class TAO_Transport_Descriptor_Interface;
  31 class TAO_InputCDR;
  32 class TAO_Endpoint;
  33 class TAO_Profile;
  34 class TAO_MProfile;
  35 class TAO_ORB_Core;
  36 class TAO_Connect_Strategy;
  37 class TAO_Transport;
  38 class TAO_Connection_Handler;
  39 class TAO_LF_Multi_Event;
  40
  41 namespace TAO
  42 {
  43   class Profile_Transport_Resolver;
  44 }
  45
  46 /**
  47  * @class TAO_Connector
  48  *
  49  * @brief Generic Connector interface definitions.
  50  *
  51  * Base class for connector bridge object.
  52  *
  53  * @todo Need to rename the class as TAO_Transport_Connector.
  54  */
  55 class TAO_Export TAO_Connector
  56 {
  57 public:
  58   /// Default constructor.
  59   TAO_Connector (CORBA::ULong tag);
  60
  61   /// The destructor.
  62   virtual ~TAO_Connector ();
  63
  64   /**
  65    * The tag identifying the specific ORB transport layer protocol.
  66    * For example IOP::TAG_INTERNET_IOP == 0.  The tag is used in the
  67    * IOR to identify the type of profile included. IOR -> {{tag0,
  68    * profile0} {tag1, profile1} ...}.  The IOP module defines the
  69    * ProfileId typedef to be a CORBA::ULong.
  70    */
  71   CORBA::ULong tag () const;
  72
  73   /// Parse a string containing a URL style IOR and return an
  74   /// MProfile.  Verify that ior is in the correct format.
  75   int make_mprofile (const char *ior, TAO_MProfile &mprofile);
  76
  77   /// Helper function to assist corbaloc parsing. The default simply validates
  78   /// the protocol identifier and scans up to the next comma or slash.
  79   /// Any protocol that has a specific need, such as uiop, can override this
  80   /// method to  provide a custom scanner.
  81   /// The profile returned is either null if this the ior does not match or an
  82   /// empty profile of the correct type, obtained from make_profile().
  83   virtual TAO_Profile *corbaloc_scan (const char *ior, size_t &len);
  84
  85   ///  Initialize object and register with reactor.
  86   virtual int open (TAO_ORB_Core *orb_core) = 0;
  87
  88   /// Shutdown Connector bridge and concrete Connector.
  89   virtual int close () = 0;
  90
  91   /**
  92    * To support pluggable we need to abstract away the details of the
  93    * connect ()  method so it can be called from the invocation code
  94    * independent of the actual transport protocol in use.
  95    */
  96   virtual TAO_Transport *connect (TAO::Profile_Transport_Resolver *r,
  97                                   TAO_Transport_Descriptor_Interface *desc,
  98                                   ACE_Time_Value *timeout);
  99
 100   /// A variation on connect that will try simultaneous connections
 101   /// on all endpoints listed in the desc.
 102   virtual TAO_Transport *parallel_connect (TAO::Profile_Transport_Resolver *r,
 103                                            TAO_Transport_Descriptor_Interface
 104                                            *desc, ACE_Time_Value *timeout);
 105
 106   /// Create a profile for this protocol and initialize it based on the
 107   /// encapsulation in @a cdr
 108   virtual TAO_Profile *create_profile (TAO_InputCDR &cdr) = 0;
 109
 110   /// Check that the prefix of the provided endpoint is valid for use
 111   /// with a given pluggable protocol.
 112   virtual int check_prefix (const char *endpoint) = 0;
 113
 114   /// Return the object key delimiter to use or expect.
 115   virtual char object_key_delimiter () const = 0;
 116
 117 protected:
 118   /// A flag indicating the actual connector supports parallel connection
 119   /// attempts. The base implementation always returns 0. Override to return
 120   /// non-zero if parallel connection attempts may be tried.
 121   virtual int supports_parallel_connects () const;
 122
 123   /// Create a profile with a given endpoint.
 124   virtual TAO_Profile *make_profile () = 0;
 125
 126   /// Set and validate endpoint. We need to do this to initialize our
 127   /// remote *_Addr's which have not been done during IOR decode.
 128   virtual int set_validate_endpoint (TAO_Endpoint *endpoint) = 0;
 129
 130   /// Make a connection
 131   virtual TAO_Transport *make_connection (TAO::Profile_Transport_Resolver *r,
 132                                           TAO_Transport_Descriptor_Interface
 133                                           &desc, ACE_Time_Value *timeout) = 0;
 134
 135   /// Make a connection using - not a pure virtual since not all
 136   /// protocols support this.
 137   virtual TAO_Transport* make_parallel_connection (
 138       TAO::Profile_Transport_Resolver *r,
 139       TAO_Transport_Descriptor_Interface &desc,
 140       ACE_Time_Value *timeout);
 141
 142   /// Cancel the passed @a svc_handler from the connector
 143   virtual int cancel_svc_handler (TAO_Connection_Handler *svc_handler) = 0;
 144
 145   /// Check whether the connection is not closed
 146   /**
 147    * @retval 0 The connection happens to be not closed, but is now open
 148    * because an other thread managed to open the handler
 149    * @retval -1 The connection is closed
 150    */
 151   virtual int check_connection_closure (TAO_Connection_Handler
 152                                         *connection_handler);
 153
 154   /**
 155    * Wait for connection completion. We have a transport that is not
 156    * connected yet, wait until it is connected.
 157    * @retval true When we could use @a transport
 158    * @return false When we can't use the @a transport
 159    */
 160   virtual bool wait_for_connection_completion(
 161       TAO::Profile_Transport_Resolver *r,
 162       TAO_Transport_Descriptor_Interface &desc,
 163       TAO_Transport *&transport,
 164       ACE_Time_Value *timeout);
 165
 166   /// In the case of a parallel connection attempt, we take an array of
 167   /// transports, and wait on any of them. When the first one completes,
 168   /// the rest are closed.
 169   virtual bool wait_for_connection_completion(
 170       TAO::Profile_Transport_Resolver *r,
 171       TAO_Transport *&the_winner,
 172       TAO_Transport **transport,
 173       unsigned int count,
 174       TAO_LF_Multi_Event *mev,
 175       ACE_Time_Value *timeout);
 176
 177   /// For a parallel connection attempt, any pending connection attempts
 178   /// present when the connection completes needs to be cleaned up. In
 179   /// some cases this happens before wait_for_connection_completion needs
 180   /// to be called, so the clean up logic is separated out here.
 181   void cleanup_pending (
 182       TAO_Transport *&the_winner,
 183       TAO_Transport **transport,
 184       unsigned int count);
 185
 186   /// See if a new connection is allowed
 187   bool new_connection_is_ok (size_t busy_count);
 188
 189   /// Wait for a transport to be connected
 190   /// Note: no longer changes transport reference count
 191   /// @retval true if wait was uneventful
 192   /// @retval false if error occurred during wait
 193   bool wait_for_transport (TAO::Profile_Transport_Resolver *r,
 194                            TAO_Transport *base_transport,
 195                            ACE_Time_Value * timeout,
 196                            bool force_wait);
 197
 198   /// Set the ORB Core pointer
 199   void orb_core (TAO_ORB_Core *orb_core);
 200
 201   /// Create a connect strategy
 202   int create_connect_strategy ();
 203
 204   /// Return the TAO_ORB_Core pointer
 205   TAO_ORB_Core *orb_core ();
 206
 207 protected:
 208   /// The (a)synch connect strategy
 209   TAO_Connect_Strategy *active_connect_strategy_;
 210
 211 private:
 212   /// IOP protocol tag.
 213   CORBA::ULong const tag_;
 214
 215   /// Pointer to our ORB core
 216   TAO_ORB_Core *orb_core_;
 217 };
 218
 219 TAO_END_VERSIONED_NAMESPACE_DECL
 220
 221 #if defined (__ACE_INLINE__)
 222 # include "tao/Transport_Connector.inl"
 223 #endif /* __ACE_INLINE__ */
 224
 225 #include /**/ "ace/post.h"
 226 #endif /*TAO_CONNECTOR_H*/