d2_process.h 4.64 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
// Copyright (C) 2013  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

#ifndef D2_PROCESS_H
#define D2_PROCESS_H

#include <d2/d_process.h>

namespace isc {
namespace d2 {

23
/// @brief DHCP-DDNS Application Process
24
///
25 26 27
/// D2Process provides the top level application logic for DHCP-driven DDNS
/// update processing.  It provides the asynchronous event processing required
/// to receive DNS mapping change requests and carry them out.
28
/// It implements the DProcessBase interface, which structures it such that it
29
/// is a managed "application", controlled by a management layer.
30

31
class D2Process : public DProcessBase {
32 33 34 35
public:
    /// @brief Constructor
    ///
    /// @param name name is a text label for the process. Generally used
36
    /// in log statements, but otherwise arbitrary.
37 38 39
    /// @param io_service is the io_service used by the caller for
    /// asynchronous event handling.
    ///
40
    /// @throw DProcessBaseError is io_service is NULL.
41 42
    D2Process(const char* name, IOServicePtr io_service);

43 44 45 46 47
    /// @brief Will be used after instantiation to perform initialization
    /// unique to D2. @TODO This will likely include interactions with
    /// QueueMgr and UpdateMgr, to prepare for request receipt and processing.
    /// Current implementation successfully does nothing.
    /// @throw throws a DProcessBaseError if the initialization fails.
48 49
    virtual void init();

50 51
    /// @brief Implements the process's event loop.
    /// The initial implementation is quite basic, surrounding calls to
52
    /// io_service->runOne() with a test of the shutdown flag.
53 54 55 56
    /// Once invoked, the method will continue until the process itself is
    /// exiting due to a request to shutdown or some anomaly forces an exit.
    /// @throw throws a DProcessBaseError if an error is encountered.
    virtual void run();
57

58 59 60 61 62 63
    /// @brief Implements the process's shutdown processing. When invoked, it
    /// should ensure that the process gracefully exits the run method.
    /// Current implementation simply sets the shutdown flag monitored by the
    /// run method. @TODO this may need to expand as the implementation evolves.
    /// @throw throws a DProcessBaseError if an error is encountered.
    virtual void shutdown();
64

65 66
    /// @brief Processes the given configuration.
    ///
67 68 69 70
    /// 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
71
    /// below.
72 73 74 75
    ///
    /// @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),
76
    /// and a string explanation of the outcome.
77 78 79
    virtual isc::data::ConstElementPtr configure(isc::data::ConstElementPtr
                                                 config_set);

80 81 82 83
    /// @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
84 85 86 87
    /// 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
88
    /// command. It can be a NULL pointer if no arguments exist for a command.
89 90
    /// @return an Element that contains the results of command composed
    /// of an integer status value (0 means successful, non-zero means failure),
91 92
    /// and a string explanation of the outcome.
    virtual isc::data::ConstElementPtr command(const std::string& command,
93
                                               isc::data::ConstElementPtr args);
94
    /// @brief Destructor
95 96 97
    virtual ~D2Process();
};

98
}; // namespace isc::d2
99 100 101
}; // namespace isc

#endif