shibsp/remoting/ListenerService.h

   1 /*
   2  *  Copyright 2001-2007 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file shibsp/remoting/ListenerService.h
  19  *
  20  * Interprocess remoting engine.
  21  */
  22
  23 #ifndef __shibsp_listener_h__
  24 #define __shibsp_listener_h__
  25
  26 #include <shibsp/remoting/ddf.h>
  27 #include <map>
  28
  29 namespace shibsp {
  30
  31     /**
  32      * Interface to a remoted service
  33      *
  34      * Classes that support remoted messages delivered by the Listener runtime
  35      * support this interface and register themselves with the runtime to receive
  36      * particular messages.
  37      */
  38     class SHIBSP_API Remoted
  39     {
  40         MAKE_NONCOPYABLE(Remoted);
  41     protected:
  42         Remoted() {}
  43     public:
  44         virtual ~Remoted() {}
  45
  46         /**
  47          * Remoted classes implement this method to process incoming messages.
  48          *
  49          * @param in    incoming DDF message
  50          * @param out   stream to write outgoing DDF message to
  51          */
  52         virtual void receive(DDF& in, std::ostream& out)=0;
  53     };
  54
  55 #if defined (_MSC_VER)
  56     #pragma warning( push )
  57     #pragma warning( disable : 4250 4251 )
  58 #endif
  59
  60     /**
  61      * Interface to a remoting engine.
  62      *
  63      * A ListenerService supports the remoting of DDF objects, which are dynamic data trees
  64      * that other class implementations can use to remote themselves by calling an
  65      * out-of-process peer implementation with arbitrary data to carry out tasks
  66      * on the implementation's behalf that require isolation from the dynamic process
  67      * fluctuations that web servers are prone to. The ability to pass arbitrary data
  68      * trees across the boundary allows arbitrary separation of duty between the
  69      * in-process and out-of-process "halves". The ListenerService is responsible
  70      * for marshalling and transmitting messages, as well as managing connections
  71      * and communication errors.
  72      */
  73     class SHIBSP_API ListenerService : public virtual Remoted
  74     {
  75     public:
  76         virtual ~ListenerService() {}
  77
  78         /**
  79          * Send a remoted message and return the response.
  80          *
  81          * @param in    input message to send
  82          * @return      response from remote service
  83          */
  84         virtual DDF send(const DDF& in)=0;
  85
  86         void receive(DDF& in, std::ostream& out);
  87
  88         // Remoted classes register and unregister for messages using these methods.
  89         // Registration returns any existing listeners, allowing message hooking.
  90
  91         /**
  92          * Register for a message. Returns existing remote service, allowing message hooking.
  93          *
  94          * @param address   message address to register
  95          * @param svc       pointer to remote service
  96          * @return  previous service registered for message, if any
  97          */
  98         virtual Remoted* regListener(const char* address, Remoted* svc);
  99
 100         /**
 101          * Unregisters service from an address, possibly restoring an original.
 102          *
 103          * @param address   message address to modify
 104          * @param current   pointer to unregistering service
 105          * @param restore   service to "restore" registration for
 106          * @return  true iff the current service was still registered
 107          */
 108         virtual bool unregListener(const char* address, Remoted* current, Remoted* restore=NULL);
 109
 110         /**
 111          * Returns current service registered at an address, if any.
 112          *
 113          * @param address message address to access
 114          * @return  registered service, or NULL
 115          */
 116         virtual Remoted* lookup(const char* address) const;
 117
 118         /**
 119          * OutOfProcess servers can implement server-side transport handling by
 120          * calling the run method and supplying a flag to monitor for shutdown.
 121          *
 122          * @param shutdown  pointer to flag that caller will set when shutdown is required
 123          * @return true iff ListenerService initialization was successful
 124          */
 125         virtual bool run(bool* shutdown)=0;
 126
 127     private:
 128         std::map<std::string,Remoted*> m_listenerMap;
 129     };
 130
 131 #if defined (_MSC_VER)
 132     #pragma warning( pop )
 133 #endif
 134
 135     /**
 136      * Registers ListenerService classes into the runtime.
 137      */
 138     void SHIBSP_API registerListenerServices();
 139
 140     /** Listener based on TCP socket remoting. */
 141     #define TCP_LISTENER_SERVICE "TCPListener"
 142
 143     /** Listener based on UNIX domain socket remoting. */
 144     #define UNIX_LISTENER_SERVICE "UnixListener"
 145 };
 146
 147 #endif /* __shibsp_listener_h__ */