qpid/agent/ManagementAgent.h Source File

Apache Qpid - AMQP Messaging for Java JMS, C++, Python, Ruby, and .NET | Apache Qpid Documentation

- Main Page
- Modules
- Namespaces
- Classes
- Files

- File List
- File Members

qpid/agent/ManagementAgent.h
Go to the documentation of this file.

    00001 #ifndef _qpid_agent_ManagementAgent_
    00002 #define _qpid_agent_ManagementAgent_
    00003
    00004 //
    00005 // Licensed to the Apache Software Foundation (ASF) under one
    00006 // or more contributor license agreements.  See the NOTICE file
    00007 // distributed with this work for additional information
    00008 // regarding copyright ownership.  The ASF licenses this file
    00009 // to you under the Apache License, Version 2.0 (the
    00010 // "License"); you may not use this file except in compliance
    00011 // with the License.  You may obtain a copy of the License at
    00012 //
    00013 //   http://www.apache.org/licenses/LICENSE-2.0
    00014 //
    00015 // Unless required by applicable law or agreed to in writing,
    00016 // software distributed under the License is distributed on an
    00017 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    00018 // KIND, either express or implied.  See the License for the
    00019 // specific language governing permissions and limitations
    00020 // under the License.
    00021 //
    00022
    00023 #include "qpid/agent/QmfAgentImportExport.h"
    00024 #include "qpid/management/ManagementObject.h"
    00025 #include "qpid/management/ManagementEvent.h"
    00026 #include "qpid/management/Manageable.h"
    00027 #include "qpid/management/ConnectionSettings.h"
    00028
    00029 namespace qpid {
    00030 namespace management {
    00031
    00032 class Notifyable {
    00033 public:
    00034     virtual ~Notifyable() {}
    00035     virtual void notify() = 0;
    00036 };
    00037
    00038 class ManagementAgent
    00039 {
    00040   public:
    00041
    00042     class Singleton {
    00043     public:
    00044         QMF_AGENT_EXTERN Singleton(bool disableManagement = false);
    00045         QMF_AGENT_EXTERN ~Singleton();
    00046         QMF_AGENT_EXTERN static ManagementAgent* getInstance();
    00047     };
    00048
    00049     typedef enum {
    00050     SEV_EMERG = 0,
    00051     SEV_ALERT = 1,
    00052     SEV_CRIT  = 2,
    00053     SEV_ERROR = 3,
    00054     SEV_WARN  = 4,
    00055     SEV_NOTE  = 5,
    00056     SEV_INFO  = 6,
    00057     SEV_DEBUG = 7,
    00058     SEV_DEFAULT = 8
    00059     } severity_t;
    00060
    00061     ManagementAgent() {}
    00062     virtual ~ManagementAgent() {}
    00063
    00064     virtual int getMaxThreads() = 0;
    00065
    00066     // Set the name of the agent
    00067     //
    00068     //   vendor   - Vendor name or domain (i.e. "apache.org")
    00069     //   product  - Product name (i.e. "qpid")
    00070     //   instance - A unique identifier for this instance of the agent.
    00071     //              If empty, the agent will create a GUID for the instance.
    00072     //   Note: the ":" character is reserved - do no use it in the vendor or product name.
    00073     //
    00074     virtual void setName(const std::string& vendor,
    00075                          const std::string& product,
    00076                          const std::string& instance="") = 0;
    00077
    00078     // Retrieve the name of the agent as assigned by setName()
    00079     //
    00080     virtual void getName(std::string& vendor,
    00081                          std::string& product,
    00082                          std::string& instance) = 0;
    00083
    00084     // Obtain the fully qualified name of the agent
    00085     //
    00086     virtual const std::string& getAddress() = 0;
    00087
    00088     // Connect to a management broker
    00089     //
    00090     //   brokerHost        - Hostname or IP address (dotted-quad) of broker.
    00091     //
    00092     //   brokerPort        - TCP port of broker.
    00093     //
    00094     //   intervalSeconds   - The interval (in seconds) that this agent shall use
    00095     //                       between broadcast updates to the broker.
    00096     //
    00097     //   useExternalThread - If true, the thread of control used for callbacks
    00098     //                       must be supplied by the user of the object (via the
    00099     //                       pollCallbacks method).
    00100     //
    00101     //                       If false, callbacks shall be invoked on the management
    00102     //                       agent's thread.  In this case, the callback implementations
    00103     //                       MUST be thread safe.
    00104     //
    00105     //   storeFile         - File where this process has read and write access.  This
    00106     //                       file shall be used to store persistent state.
    00107     //
    00108     virtual void init(const std::string& brokerHost = "localhost",
    00109                       uint16_t brokerPort = 5672,
    00110                       uint16_t intervalSeconds = 10,
    00111                       bool useExternalThread = false,
    00112                       const std::string& storeFile = "",
    00113                       const std::string& uid = "",
    00114                       const std::string& pwd = "",
    00115                       const std::string& mech = "PLAIN",
    00116                       const std::string& proto = "tcp") = 0;
    00117
    00118     virtual void init(const management::ConnectionSettings& settings,
    00119                       uint16_t intervalSeconds = 10,
    00120                       bool useExternalThread = false,
    00121                       const std::string& storeFile = "") = 0;
    00122
    00123
    00124     // Register a schema with the management agent.  This is normally called by the
    00125     // package initializer generated by the management code generator.
    00126     //
    00127     virtual void
    00128     registerClass(const std::string& packageName,
    00129                   const std::string& className,
    00130                   uint8_t*    md5Sum,
    00131                   management::ManagementObject::writeSchemaCall_t schemaCall) = 0;
    00132
    00133     virtual void
    00134     registerEvent(const std::string& packageName,
    00135                   const std::string& eventName,
    00136                   uint8_t*    md5Sum,
    00137                   management::ManagementEvent::writeSchemaCall_t schemaCall) = 0;
    00138
    00139     // Add a management object to the agent.  Once added, this object shall be visible
    00140     // in the greater management context.
    00141     //
    00142     // Please note that ManagementObject instances are not explicitly deleted from
    00143     // the management agent.  When the core object represented by a management object
    00144     // is deleted, the "resourceDestroy" method on the management object must be called.
    00145     // It will then be reclaimed in due course by the management agent.
    00146     //
    00147     // Once a ManagementObject instance is added to the agent, the agent then owns the
    00148     // instance.  The caller MUST NOT free the resources of the instance at any time.
    00149     // When it is no longer needed, invoke its "resourceDestroy" method and discard the
    00150     // pointer.  This allows the management agent to report the deletion of the object
    00151     // in an orderly way.
    00152     //
    00153     virtual ObjectId addObject(ManagementObject* objectPtr, uint64_t persistId = 0) = 0;
    00154     virtual ObjectId addObject(ManagementObject* objectPtr,
    00155                                const std::string& key,
    00156                                bool persistent = true) = 0;
    00157
    00158     //
    00159     //
    00160     virtual void raiseEvent(const ManagementEvent& event,
    00161                             severity_t severity = SEV_DEFAULT) = 0;
    00162
    00163     // If "useExternalThread" was set to true in init, this method must
    00164     // be called to provide a thread for any pending method calls that have arrived.
    00165     // The method calls for ManagementObject instances shall be invoked synchronously
    00166     // during the execution of this method.
    00167     //
    00168     // callLimit may optionally be used to limit the number of callbacks invoked.
    00169     // if 0, no limit is imposed.
    00170     //
    00171     // The return value is the number of callbacks that remain queued after this
    00172     // call is complete.  It can be used to determine whether or not further calls
    00173     // to pollCallbacks are necessary to clear the backlog.  If callLimit is zero,
    00174     // the return value will also be zero.
    00175     //
    00176     virtual uint32_t pollCallbacks(uint32_t callLimit = 0) = 0;
    00177
    00178     // In the "useExternalThread" scenario, there are three ways that an application can
    00179     // use to be notified that there is work to do.  Of course the application may periodically
    00180     // call pollCallbacks if it wishes, but this will cause long latencies in the responses
    00181     // to method calls.
    00182     //
    00183     // The notification methods are:
    00184     //
    00185     //  1) Register a C-style callback by providing a pointer to a function
    00186     //  2) Register a C++-style callback by providing an object of a class that is derived
    00187     //     from Notifyable
    00188     //  3) Call getSignalFd() to get a file descriptor that can be used in a select
    00189     //     call.  The file descriptor shall become readable when the agent has work to
    00190     //     do.  Note that this mechanism is specific to Posix-based operating environments.
    00191     //     getSignalFd will probably not function correctly on Windows.
    00192     //
    00193     // If a callback is registered, the callback function will be called on the agent's
    00194     // thread.  The callback function must perform no work other than to signal the application
    00195     // thread to call pollCallbacks.
    00196     //
    00197     typedef void (*cb_t)(void*);
    00198     virtual void setSignalCallback(cb_t callback, void* context) = 0;
    00199     virtual void setSignalCallback(Notifyable& notifyable) = 0;
    00200     virtual int getSignalFd() = 0;
    00201 };
    00202
    00203 }}
    00204
    00205 #endif