[2956] Created the initial, implementation of DHCP-DDNS service controller

 class, D2Controller, the base class DControllerBase, and unit tests.

1 files changed, 62 insertions, 49 deletions

diff --git a/src/bin/d2/d_process.h b/src/bin/d2/d_process.h
index cb7b3a0c7d..73bbc17ba3 100644
--- a/src/bin/d2/d_process.h
+++ b/src/bin/d2/d_process.h
@@ -40,26 +40,26 @@ static const std::string SHUT_DOWN_COMMAND("shutdown");
 
 /// @brief Application Process Interface
 ///
-/// DProcessBase is an abstract class represents the primary "application" 
-/// level object in a "managed" asynchronous application. It provides a uniform 
-/// interface such that a managing layer can construct, intialize, and start
+/// DProcessBase is an abstract class represents the primary "application"
+/// level object in a "managed" asynchronous application. It provides a uniform
+/// interface such that a managing layer can construct, initialize, and start
 /// the application's event loop.  The event processing is centered around the
-/// use of isc::asiolink::io_service. The io_service is shared between the 
-/// the managing layer and the DProcessBase.  This allows management layer IO 
-/// such as directives to be sensed and handled, as well as processing IO 
-/// activity specific to the application.  In terms of management layer IO,
-/// there are methods shutdown, configuration updates, and commands unique
-/// to the application.  
+/// use of isc::asiolink::io_service. The io_service is shared between the
+/// managing layer and the DProcessBase.  This allows management layer IO such
+/// as directives to be sensed and handled, as well as processing IO activity
+/// specific to the application.  In terms of management layer IO, there are
+/// methods shutdown, configuration updates, and commands unique to the
+/// application.
 class DProcessBase {
 public:
     /// @brief Constructor
     ///
     /// @param name name is a text label for the process. Generally used
-    /// in log statements, but otherwise arbitrary. 
+    /// in log statements, but otherwise arbitrary.
     /// @param io_service is the io_service used by the caller for
     /// asynchronous event handling.
     ///
-    /// @throw DProcessBaseError is io_service is NULL. 
+    /// @throw DProcessBaseError is io_service is NULL.
     DProcessBase(const char* name, IOServicePtr io_service) : name_(name),
         io_service_(io_service), shut_down_flag_(false) {
 
@@ -69,78 +69,91 @@ public:
     };
 
     /// @brief May be used after instantiation to perform initialization unique
-    /// to application. It must be invoked prior to invoking run. This would 
-    /// likely include the creation of additional IO sources and their 
-    /// integration into the io_service. 
-    virtual void init() = 0; 
-
-    /// @brief Implements the process's event loop. In its simplest form it 
-    /// would an invocation io_service_->run().  This method should not exit 
-    /// until the process itself is exiting due to a request to shutdown or 
-    /// some anomaly is forcing an exit.   
-    /// @return  returns EXIT_SUCCESS upon a successful, normal termination, 
-    /// and EXIT_FAILURE to indicate an abnormal termination.    
-    virtual int run() = 0; 
-
-    /// @brief Implements the process's shutdown processing. When invoked, it 
-    /// should ensure that the process gracefully exits the run method. 
-    virtual int shutdown() = 0;
-
-    /// @brief Processes the given configuration. 
-    /// 
+    /// to application. It must be invoked prior to invoking run. This would
+    /// likely include the creation of additional IO sources and their
+    /// integration into the io_service.
+    /// @throw throws a DProcessBaseError if the initialization fails.
+    virtual void init() = 0;
+
+    /// @brief Implements the process's event loop. In its simplest form it
+    /// would an invocation io_service_->run().  This method should not exit
+    /// until the process itself is exiting due to a request to shutdown or
+    /// some anomaly is forcing an exit.
+    /// @throw throws a DProcessBaseError if an operational error is encountered.
+    virtual void run() = 0;
+
+    /// @brief Implements the process's shutdown processing. When invoked, it
+    /// should ensure that the process gracefully exits the run method.
+    /// @throw throws a DProcessBaseError if an operational error is encountered.
+    virtual void shutdown() = 0;
+
+    /// @brief Processes the given configuration.
+    ///
     /// This method may be called multiple times during the process lifetime.
     /// Certainly once during process startup, and possibly later if the user
     /// alters configuration. This method must not throw, it should catch any
     /// processing errors and return a success or failure answer as described
-    /// below. 
+    /// below.
     ///
     /// @param config_set a new configuration (JSON) for the process
     /// @return an Element that contains the results of configuration composed
     /// of an integer status value (0 means successful, non-zero means failure),
-    /// and a string explanation of the outcome. 
+    /// and a string explanation of the outcome.
     virtual isc::data::ConstElementPtr configure(isc::data::ConstElementPtr
-                                                 config_set) = 0; 
+                                                 config_set) = 0;
 
-    /// @brief Processes the given command. 
-    /// 
-    /// This method is called to execute any custom commands supported by the 
-    /// process. This method must not throw, it should catch any processing 
+    /// @brief Processes the given command.
+    ///
+    /// This method is called to execute any custom commands supported by the
+    /// process. This method must not throw, it should catch any processing
     /// errors and return a success or failure answer as described below.
     ///
     /// @param command is a string label representing the command to execute.
     /// @param args is a set of arguments (if any) required for the given
-    /// command. 
+    /// command.
     /// @return an Element that contains the results of command composed
     /// of an integer status value (0 means successful, non-zero means failure),
-    /// and a string explanation of the outcome.  
+    /// and a string explanation of the outcome.
     virtual isc::data::ConstElementPtr command(
-            const std::string& command, isc::data::ConstElementPtr args) = 0; 
+            const std::string& command, isc::data::ConstElementPtr args) = 0;
 
-    /// @brief Destructor 
+    /// @brief Destructor
     virtual ~DProcessBase(){};
 
-    bool shouldShutdown() { 
-        return (shut_down_flag_); 
+    /// @brief Checks if the process has been instructed to shut down.
+    ///
+    /// @return returns true if process shutdown flag is true.
+    bool shouldShutdown() {
+        return (shut_down_flag_);
     }
 
-    void setShutdownFlag(bool value) { 
-        shut_down_flag_ = value; 
+    /// @brief Sets the process shut down flag to the given value.
+    ///
+    /// @param value is the new value to assign the flag.
+    void setShutdownFlag(bool value) {
+        shut_down_flag_ = value;
     }
 
+    /// @brief Fetches the name of the controller.
+    ///
+    /// @return returns a reference the controller's name string.
     const std::string& getName() const {
         return (name_);
     }
 
+    /// @brief Fetches the controller's IOService.
+    ///
+    /// @return returns a reference to the controller's IOService.
     IOServicePtr& getIoService() {
         return (io_service_);
     }
 
 private:
-    /// @brief Text label for the process. Generally used in log statements, 
-    /// but otherwise can be arbitrary. 
+    /// @brief Text label for the process. Generally used in log statements,
+    /// but otherwise can be arbitrary.
     std::string name_;
 
-    /// @brief The IOService to be used for asynchronous event handling. 
+    /// @brief The IOService to be used for asynchronous event handling.
     IOServicePtr io_service_;
 
     /// @brief Boolean flag set when shutdown has been requested.
@@ -150,7 +163,7 @@ private:
 /// @brief Defines a shared pointer to DProcessBase.
 typedef boost::shared_ptr<DProcessBase> DProcessBasePtr;
 
-}; // namespace isc::d2 
+}; // namespace isc::d2
 }; // namespace isc
 
 #endif