shibsp/remoting/ListenerService.h

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