1 chip 1.1 //%//-*-c++-*-///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2000, 2001 The Open group, BMC Software, Tivoli Systems, IBM
4 //
5 // Permission is hereby granted, free of charge, to any person obtaining a copy
6 // of this software and associated documentation files (the "Software"), to
7 // deal in the Software without restriction, including without limitation the
8 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
9 // sell copies of the Software, and to permit persons to whom the Software is
10 // furnished to do so, subject to the following conditions:
11 //
12 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
13 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
14 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
15 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
16 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
17 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
18 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
19 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20 //
21 //==============================================================================
22 chip 1.1 //
23 // Author: Chip Vincent (cvincent@us.ibm.com)
24 //
25 // Modified By:
26 //
27 //%/////////////////////////////////////////////////////////////////////////////
28
29 #ifndef Pegasus_CIMIndicationProvider_h
30 #define Pegasus_CIMIndicationProvider_h
31
32 #include <Pegasus/Common/Config.h>
33 #include <Pegasus/Common/CIMIndication.h>
34 #include <Pegasus/Provider/CIMBaseProvider.h>
35
36 #include <Pegasus/Common/Array.h>
37 #include <Pegasus/Common/String.h>
38 #include <Pegasus/Common/CIMReference.h>
39 #include <Pegasus/Common/CIMDateTime.h>
40
41 PEGASUS_NAMESPACE_BEGIN
42
43 chip 1.1 /*
44 REVIEW: In CIMClient interfaces, we fully specify a class name using two
45 arguments:
46
47 const String& nameSpace
48 const String& className
49
50 In the provideIndication() method below, these two are represented like
51 this:
52
53 const CIMReference& classReference
54
55 The goal is to represent these:
56
57 namespace name
58 class name.
59
60 But using this type leaves open the possibility (ambiguity) of specifying
61 these components of CIMReference as well:
62
63 host name
64 chip 1.1 keybinding pairs
65
66 I think there should be consistency between the CIMClient and
67 CIMProvider interfaces? Further, I don't think using CIMReference is an
68 option for the client, since it would allow the client to pass host names
69 and keybinding pairs (which could be detected until run time). Further,
70 it is incomptible with the specification.
71
72 REVIEW: WITHIN clauses not supported by WQL.
73
74 REVIEW: Get clarification on use of handler.complete() method.
75
76 REVIEW: How do handlers get cleaned up?
77
78 REVIEW: What do you do with the old handler (you may have cached) when
79 you are passed a new handler by any of the methods. Why not just
80 have one handler for the whole class rather than passing a new
81 handler each time one of the methods of this class is called?
82
83 REVIEW: Why does cancelIndication() need a handler? Why do any of the
84 methods except for provideIndication() need a handler?
85 chip 1.1
86 REVIEW: Note that Microsoft's WMI only passes the handler (sink) to the
87 provideEvents() method.
88
89 REVIEW: Should we split this class into two distinct interfaces (since
90 it would appear that polled v.s. non-polled is a development time
91 decision and therefore a compile time decission). It may be cleaner
92 to resolve polled v.s. non-polled via provider registration.
93
94 REVIEW: Is an asynchronous indication provider asynchronous with respect
95 to all indications it might generate or can it be synchronous for some
96 and aysynchronous for others? Does synchronicity pertain to the each
97 class or just to the provider?
98 */
99
100 /**
101 This class defines the set of methods implemented by an indication
102 provider.
103
104 A provider that derives from this class must implement all methods. The
105 minimal method implementation simply throws the NotSupported exception.
106 chip 1.1
107 In general, the CIMOM classifies the provider as asynchronous or
108 synchronous depending on the methods implemented by the provider. An
109 asynchronous indication provider supports these methods:
110
111 <pre>
112 provideIndication()
113 updateIndication()
114 cancelIndication()
115 </pre>
116
117 Whereas, a synchronous provider supports this method:
118
119 <pre>
120 checkIndication()
121 </pre>
122
123 The CIMOM first attempts to call provideIndication(), given at least once
124 subscription exists. If the provider does not support this method, the
125 CIMOM assumes the provider generates indications synchronously using
126 checkIndication(). If the provider does not support any of the methods of
127 chip 1.1 this interface, it is not considered an indication provider and an error
128 is generated.
129 */
130 class PEGASUS_PROVIDER_LINKAGE CIMIndicationProvider
131 : public virtual CIMBaseProvider
132 {
133 public:
134
135 CIMIndicationProvider(void);
136
137 virtual ~CIMIndicationProvider(void);
138
139 /**
140 Instructs the provider to begin generating indications of the type
141 specified in the classReference parameter.
142
143 This method is invoked when the CIMOM has at least one active
144 subscription that links the indication type with a handler. Once
145 this method has been invoked, changes to the active subscriptions
146 are communicated via the updateIndication() method. The
147 cancelIndication() method is invoked when all active subscriptions
148 chip 1.1 have been removed.
149
150 For example, assume that two subscriptions exist that point to the
151 following filters.
152
153 <pre>
154 SELECT Property1 FROM Sample_Indication
155 WHERE Property1="foo" WITHIN 30000"
156
157 SELECT Property2 FROM Sample_Indication
158 WHERE Property1="bar" WITHIN 60000"
159 </pre>
160
161 The contents of the paramters (in string form) to this method might
162 look like the following.
163
164 <pre>
165 classReference = "localhost/root/cimv2:Sample_Indication"
166 minimumInterval = "00000000003000.000000:000" (30 minutes)
167 maximumInterval = "00000000006000.000000:000" (60 minutes)
168 propertyList = "Property1", "Property2"
169 chip 1.1 </pre>
170
171 NOTE: The WHERE clause is not evaluated by the provider. Providers
172 generate indications according to predefined events and are not
173 specified by indication filters. The existence of a filter simply
174 notifies a provider that some client is interested in indications
175 of a specified type. The filters specify the criteria for indication
176 delivery, not creation. In other words, the filter is resolved by
177 CIMOM, not the provider.
178
179 Assuming the above parameters, the provider should attach to some
180 resource and begin monitoring every 30 seconds (optimally). When
181 some predefined event occurs (a circumstance that merits an
182 indication), the provider should create an indication containing
183 the properties listed in the propertyList parameter. The provider
184 then delivers the indication to the handler associated with the
185 indication type and continues monitoring. A call to
186 updateIndication() means that the indication generation information
187 (minimumInterval, maximumInterval, and propertyList) has changed,
188 and a call to cancelIndication() notifies the provider to
189 discontinue monitoring (no subscriptions exist).
190 chip 1.1
191 NOTE: Under normal circumstances the provider should not call
192 handler.complete() in this method; it should be called in
193 cancelIndication(). Calling this method implies no more results are
194 available and will effectively disable result forwarding for the
195 handler.
196
197 @param contex contains security and locale information relevant
198 for the lifetime of this operation.
199
200 @param classReference provides a fully qualified reference of the
201 indication class of interest.
202
203 @param minimumInterval specifies the minimum requested indication
204 delivery frequency. This is an optional parameter where an
205 interval of zero ("0000000000.000000:000") implies not
206 specified.
207
208 @param maximumInterval specifies the maximum requested indication
209 delivery frequency. This is an optional parameter where an
210 interval of zero ("0000000000.000000:000") implies not
211 chip 1.1 specified.
212
213 @param propertyList specifies the properties of interest within the
214 class identified by the classReference parameter.
215
216 @param handler asynchronusly processes the results of this
217 operation.
218
219 @exception NotImplemented
220 @exception InvalidArgument
221 */
222 virtual void provideIndication(
223 const OperationContext & context,
224 const CIMReference & classReference,
225 const CIMDateTime & minimumInterval,
226 const CIMDateTime & maximumInterval,
227 const Array<String> & propertyList,
228 ResponseHandler<CIMIndication> & handler) = 0;
229
230 /**
231 Instructs the provider to update the information regarding the
232 chip 1.1 indication of the type specified in the classReference parameter.
233
234 Once the provideIndication method has been called, the CIMOM
235 communicates significant changes about the indication generatation
236 information (minimumInterval, maximumInterval, and propertyList)
237 via this method.
238
239 Assuming provideIndications() was called with the parameters in the
240 sample above, and a new subscription is created for the following
241 filter.
242
243 <pre>
244 SELECT Property1, Property3 FROM Sample_Indication
245 WHERE Property1="bar" WITHIN 60000
246 </pre>
247
248 The contents of the paramters (in string form) to this method might
249 look like the following.
250
251 <pre>
252 classReference = "localhost/root/cimv2:Sample_Indication"
253 chip 1.1 minimumInterval = "00000000003000.000000:000" (30 minutes)
254 maximumInterval = "00000000006000.000000:000" (60 minutes)
255 propertyList = "Property1", "Property2", "Property3"
256 </pre>
257
258 NOTE: The WHERE clause is not evaluated by the provider. Providers
259 generate indications according to predefined events and are not
260 specified by indication filters. The existence of a filter simply
261 notifies a provider that some client is interested in indications
262 of a specified type. The filters specify the criteria for
263 indication delivery, not creation. In other words, indications may
264 be created by this provider and later discarded by the CIMOM
265 (while evaluating the filter).
266
267 Assuming the above parameters, the provider should adjust add
268 Property3 to any indications generated from this point forward.
269
270 Subsequent subscriptions associated with existing filters do not
271 result in calls to the provider.
272
273 NOTE: Under normal circumstances the provider should not call
274 chip 1.1 handler.complete() in this method; it should be called in
275 cancelIndication(). Calling the handler.complete() method
276 implies no more results are available and will effectively
277 disable result forwarding for the handler.
278
279 @param context contains security and locale information
280 relevant for the lifetime of this operation.
281
282 @param classReference provides a fully qualified reference of the
283 indication class of interest.
284
285 @param minimumInterval specifies the minimum requested indication
286 delivery frequency. This is an optional parameter where an
287 interval of zero ("0000000000.000000:000") implies not
288 specified.
289
290 @param maximumInterval specifies the maximum requested indication
291 delivery frequency. This is an optional parameter where an
292 interval of zero ("0000000000.000000:000") implies not
293 specified.
294
295 chip 1.1 @param propertyList specifies the properties of interest within
296 the class identified by the classReference parameter.
297
298 @param handler asynchronusly processes the results of this
299 operation.
300
301 @exception NotImplemented
302 @exception InvalidArgument
303 */
304 virtual void updateIndication(
305 const OperationContext & context,
306 const CIMReference & classReference,
307 const CIMDateTime & minimumInterval,
308 const CIMDateTime & maximumInterval,
309 const Array<String> & propertyList,
310 ResponseHandler<CIMIndication> & handler) = 0;
311
312 /**
313 Instructs the provider to stop providing indications of the type
314 specified in the classReference parameter.
315
316 chip 1.1 This method is called after provideIndication() and implies that
317 either no subscriptions exist or that the CIMOM is shutting down.
318 The provider should release resources associated with generating
319 indications of the type specified in classReference. If a
320 subscription is later created, provideIndications will be called
321 again.
322
323 Upon completion of this method, the provider should call
324 handler.complete (the CIMOM will call it, if necessary) at which
325 point the handle is no longer guaranteed to be valid. Usage of the
326 handle after complete is undefined.
327
328 @param context contains security and locale information relevant
329 for the lifetime of this operation.
330
331 @param classReference provides a fully qualified reference of the
332 indication class of interest.
333
334 @param handler asynchronusly processes the results of this
335 operation.
336
337 chip 1.1 @exception NotImplemented
338 @exception InvalidArgument
339 */
340 virtual void cancelIndication(
341 const OperationContext & context,
342 const CIMReference & classReference,
343 ResponseHandler<CIMIndication> & handler) = 0;
344
345 /**
346 Instructs the provider to check the managed resource and
347 immediately generate indications, if necessary, and complete.
348
349 Note that this method is used (to the exclusion of the others) for
350 synchronous ("polled") indications.
351
352 This method is called periodically by the CIMOM to allow the
353 provider to create indications without actively monitoring a
354 resource.
355
356 Note the CIMOM frequency wherewith the CIMOM invokes this method
357 is related to the "intervals" defined by the filter.
358 chip 1.1
359 Because the method executes on the CIMOM's thread, the provider
360 should attempt to complete the method prompty to allow the CIMOM
361 to service other providers.
362
363 REVIEW: the above statement we hope is in error. This method
364 must not be invoked on the CIMOM's thread.
365
366 @param context contains security and locale information
367 relevant for the lifetime of this operation.
368
369 @param classReference provides a fully qualified reference of the
370 indication class of interest.
371
372 @param The propertyList specifies the properties of interest
373 within the class identified by the classReference parameter.
374
375 @param handler asynchronusly processes the results of this
376 operation.
377
378 @exception NotImplemented
379 chip 1.1 @exception InvalidArgument
380
381 Note the absense of interval parameters as these are processed by
382 the CIMOM itself.
383 */
384 virtual void checkIndication(
385 const OperationContext & context,
386 const CIMReference & classReference,
387 const Array<String> & propertyList,
388 ResponseHandler<CIMIndication> & handler) = 0;
389 };
390
391 PEGASUS_NAMESPACE_END
392
393 #endif /* Pegasus_CIMIndicationProvider_h */
|
Return to
CIMIndicationProvider.h
CVS log
Up to [Pegasus] / pegasus / src / Pegasus / Provider