Apache Qpid - AMQP Messaging for Java JMS, C++, Python, Ruby, and .NET Apache Qpid Documentation
ManagementAgent.h
Go to the documentation of this file.
1 #ifndef _qpid_agent_ManagementAgent_
2 #define _qpid_agent_ManagementAgent_
3 
4 //
5 // Licensed to the Apache Software Foundation (ASF) under one
6 // or more contributor license agreements. See the NOTICE file
7 // distributed with this work for additional information
8 // regarding copyright ownership. The ASF licenses this file
9 // to you under the Apache License, Version 2.0 (the
10 // "License"); you may not use this file except in compliance
11 // with the License. You may obtain a copy of the License at
12 //
13 // http://www.apache.org/licenses/LICENSE-2.0
14 //
15 // Unless required by applicable law or agreed to in writing,
16 // software distributed under the License is distributed on an
17 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 // KIND, either express or implied. See the License for the
19 // specific language governing permissions and limitations
20 // under the License.
21 //
22 
28 
29 namespace qpid {
30 namespace management {
31 
32 class Notifyable {
33 public:
34  virtual ~Notifyable() {}
35  virtual void notify() = 0;
36 };
37 
39 {
40  public:
41 
42  class Singleton {
43  public:
44  QMF_AGENT_EXTERN Singleton(bool disableManagement = false);
47  };
48 
49  typedef enum {
50  SEV_EMERG = 0,
51  SEV_ALERT = 1,
52  SEV_CRIT = 2,
53  SEV_ERROR = 3,
54  SEV_WARN = 4,
55  SEV_NOTE = 5,
56  SEV_INFO = 6,
57  SEV_DEBUG = 7,
59  } severity_t;
60 
62  virtual ~ManagementAgent() {}
63 
64  virtual int getMaxThreads() = 0;
65 
66  // Set the name of the agent
67  //
68  // vendor - Vendor name or domain (i.e. "apache.org")
69  // product - Product name (i.e. "qpid")
70  // instance - A unique identifier for this instance of the agent.
71  // If empty, the agent will create a GUID for the instance.
72  // Note: the ":" character is reserved - do no use it in the vendor or product name.
73  //
74  virtual void setName(const std::string& vendor,
75  const std::string& product,
76  const std::string& instance="") = 0;
77 
78  // Retrieve the name of the agent as assigned by setName()
79  //
80  virtual void getName(std::string& vendor,
81  std::string& product,
82  std::string& instance) = 0;
83 
84  // Obtain the fully qualified name of the agent
85  //
86  virtual const std::string& getAddress() = 0;
87 
88  // Connect to a management broker
89  //
90  // brokerHost - Hostname or IP address (dotted-quad) of broker.
91  //
92  // brokerPort - TCP port of broker.
93  //
94  // intervalSeconds - The interval (in seconds) that this agent shall use
95  // between broadcast updates to the broker.
96  //
97  // useExternalThread - If true, the thread of control used for callbacks
98  // must be supplied by the user of the object (via the
99  // pollCallbacks method).
100  //
101  // If false, callbacks shall be invoked on the management
102  // agent's thread. In this case, the callback implementations
103  // MUST be thread safe.
104  //
105  // storeFile - File where this process has read and write access. This
106  // file shall be used to store persistent state.
107  //
108  virtual void init(const std::string& brokerHost = "localhost",
109  uint16_t brokerPort = 5672,
110  uint16_t intervalSeconds = 10,
111  bool useExternalThread = false,
112  const std::string& storeFile = "",
113  const std::string& uid = "",
114  const std::string& pwd = "",
115  const std::string& mech = "PLAIN",
116  const std::string& proto = "tcp") = 0;
117 
118  virtual void init(const management::ConnectionSettings& settings,
119  uint16_t intervalSeconds = 10,
120  bool useExternalThread = false,
121  const std::string& storeFile = "") = 0;
122 
123 
124  // Register a schema with the management agent. This is normally called by the
125  // package initializer generated by the management code generator.
126  //
127  virtual void
128  registerClass(const std::string& packageName,
129  const std::string& className,
130  uint8_t* md5Sum,
132 
133  virtual void
134  registerEvent(const std::string& packageName,
135  const std::string& eventName,
136  uint8_t* md5Sum,
138 
139  // Add a management object to the agent. Once added, this object shall be visible
140  // in the greater management context.
141  //
142  // Please note that ManagementObject instances are not explicitly deleted from
143  // the management agent. When the core object represented by a management object
144  // is deleted, the "resourceDestroy" method on the management object must be called.
145  // It will then be reclaimed in due course by the management agent.
146  //
147  // Once a ManagementObject instance is added to the agent, the agent then owns the
148  // instance. The caller MUST NOT free the resources of the instance at any time.
149  // When it is no longer needed, invoke its "resourceDestroy" method and discard the
150  // pointer. This allows the management agent to report the deletion of the object
151  // in an orderly way.
152  //
153  virtual ObjectId addObject(ManagementObject* objectPtr, uint64_t persistId = 0) = 0;
154  virtual ObjectId addObject(ManagementObject* objectPtr,
155  const std::string& key,
156  bool persistent = true) = 0;
157 
158  //
159  //
160  virtual void raiseEvent(const ManagementEvent& event,
161  severity_t severity = SEV_DEFAULT) = 0;
162 
163  // If "useExternalThread" was set to true in init, this method must
164  // be called to provide a thread for any pending method calls that have arrived.
165  // The method calls for ManagementObject instances shall be invoked synchronously
166  // during the execution of this method.
167  //
168  // callLimit may optionally be used to limit the number of callbacks invoked.
169  // if 0, no limit is imposed.
170  //
171  // The return value is the number of callbacks that remain queued after this
172  // call is complete. It can be used to determine whether or not further calls
173  // to pollCallbacks are necessary to clear the backlog. If callLimit is zero,
174  // the return value will also be zero.
175  //
176  virtual uint32_t pollCallbacks(uint32_t callLimit = 0) = 0;
177 
178  // In the "useExternalThread" scenario, there are three ways that an application can
179  // use to be notified that there is work to do. Of course the application may periodically
180  // call pollCallbacks if it wishes, but this will cause long latencies in the responses
181  // to method calls.
182  //
183  // The notification methods are:
184  //
185  // 1) Register a C-style callback by providing a pointer to a function
186  // 2) Register a C++-style callback by providing an object of a class that is derived
187  // from Notifyable
188  // 3) Call getSignalFd() to get a file descriptor that can be used in a select
189  // call. The file descriptor shall become readable when the agent has work to
190  // do. Note that this mechanism is specific to Posix-based operating environments.
191  // getSignalFd will probably not function correctly on Windows.
192  //
193  // If a callback is registered, the callback function will be called on the agent's
194  // thread. The callback function must perform no work other than to signal the application
195  // thread to call pollCallbacks.
196  //
197  typedef void (*cb_t)(void*);
198  virtual void setSignalCallback(cb_t callback, void* context) = 0;
199  virtual void setSignalCallback(Notifyable& notifyable) = 0;
200  virtual int getSignalFd() = 0;
201 };
202 
203 }}
204 
205 #endif

Qpid C++ API Reference
Generated on Mon Feb 11 2013 for Qpid C++ Client API by doxygen 1.8.1.1