Apache Qpid - AMQP Messaging for Java JMS, C++, Python, Ruby, and .NET Apache Qpid Documentation
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 = "guest",
00114                       const std::string& pwd = "guest",
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  

Qpid C++ API Reference
Generated on Mon Aug 22 2011 for Qpid C++ Client API by doxygen 1.7.4