1 karl 1.1 <html>
2
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
5 <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
6 <meta name="ProgId" content="FrontPage.Editor.Document">
7 <title>Provider Interface Proposal</title>
8 </head>
9
10 <body>
11 <H1>Expanding the Pegasus Provider Interface Proposal</H1>
12
13 Mike Brasher, Karl Schopmeyer, Chip Vincent
14 22 May 2001
15
16 <h2>Introduction</h2>
17
18 We defined a set of interfaces for Pegasus providers based on the CIM Operations.
19
20 We recognized several limitations in that first set of interfaces, particularly the fact that there was no easy path back to the CIMOM from the provider. The initial interfaces provides a handle to get to the repository but not to put CIM operations back into the CIMOM.
21
22 karl 1.1 At a recent work group meeting, IBM proposed a further set of changes to provide a more consistent interface and to reduce the possibility that the interface will have to change with future changes to the CIM Operations.
23 <p>This document is a proposal to make these changes.</p>
24
25 <h2>Objectives </h2>
26
27 <OL>
28 <LI>Extend for the next set of functionality primarily indications.
29 <LI>Provide more information to the provider
30 <LI>Enable providers to perform varying levels of operation (dump and smart providers).
31 <LI>Support implementation specific objects.
32 <LI>Isolate the API from changes to the CIM standard and implementation specific objects.
33 <LI>Prepare for the implementation of standardized provider registration
34 </OL>
35
36 <h2>Summary of Proposed Changes</h2>
37
38 We propose the following changes:
39 <OL>
40 <LI>Create an operational context for each transaction. This context would allow us to pass information such as security and locale to the provider. In addition, we have considered that this interface could also make the target CIM class available to the provider so it would not have to be specifically requested.
41
42 <LI>Modify the boolean parameters passed so they get passed in a single variable. Today several of the CIM Operations include boolean parameters. While we are not sure these will change, any change would cause a signature change to the provider
43 karl 1.1
44 <LI>Simplify and unify the object identity parameters. - Today the object ID is passed as a set of parameters, Namespace, Class/instance ID. This could easily be consolidated into a single CIMReference parameter so that the namespace, object ID, etc. could be broken out by the provider.
45
46 WHY?
47
48 <LI>Subdivide the Provider interface. - Today we have a single interface to the provider that allows the provider to implement all of the possible CIM operations. First, it is not clear that the provider needs all of the operations. Second, there are subsets of provider functionality (method providers, property providers, etc.) that only implement a subset of the CIM Operations. The proposal is to create specific interfaces to support just these subsets.
49
50 <LI>Add a provider operation to shutdown a provider. We will have to provide a more organized shutdown than is provided today. One of the operations will be to shutdown the providers. To do this in an organized manner we will need to communicate the shutdown command to the providers.
51
52 <LI>Add the indication interfaces. - We are beginning to do the design for indications now. One of the interfaces will be the provider interface for moving indications from the provider to the Object Manager.</p>
53 </OL>
54 <h2>Definition of the Proposed Changes</h2>
55
56 This section defines the proposed implementation for each of these changes.
57
58 <h3>Context for each Provider and for each Operation</h3>
59
60 Operations do not currently support parameters to describe context information (such as security or localization parameters).
61 In addition, there will be additional requirements for the provider to request
62 information for things like system parameters, system state information, etc.
63 <p>As part of this we also want to create a handle so that CIM Operations can be
64 karl 1.1 effecitively passed from the provider back to the Object Manager.</p>
65 <p> </p>
66 <p>We propose modifying both the provider context and adding an operational
67 context parameter. </p>
68 <p> </p>
69 <h4>Provider Context</h4>
70 <p>Today - one parameter, the CIM Repository handle provided with the initialize
71 as follows:</p>
72 <pre>virtual void initialize(CIMRepository& repository);</pre>
73 The provider saves the repository handle for later access using the CIMRepository interface. We don't want providers to have access to the repository
74 but we do want them to have easy access back to the Object Manager with CIM
75 Operations.
76 <p>We could provide access to the Object Manager delegator except that this
77 would bypass any security features that we would want to implement. We
78 propose adding a new interface which will provide:</p>
79 <ul>
80 <li>A way to put CIM Operations (getClass, etc.) back into the Object
81 Manager</li>
82 <li>Additional specific operations required by the provider -</li>
83 <li> </li>
84 </ul>
85 karl 1.1 <h4>Operation Context</h4>
86 <p>Introduce OperationContext which communicates context information to operation methods and allows implementation specific context information to be passed to providers.<br>
87 OperationContext encapsulates<br>
88 Locale information<br>
89 User credentials<br>
90 Implementation TBD</p>
91
92 <pre>CIMInstance MyProvider::getInstance(..., const OperationContext & context, ...)
93 {
94 // ...
95 // get locale from operation context
96 // ...
97 // get user credentials from operation context
98 // ...
99 return(CIMInstance(instance));
100 }</pre>
101
102 <h3>Boolean Parameters</h3>
103
104 Operations currently use multiple arguments to represent additional information (Boolean localOnly, Boolean includeQualifiers, Boolean includeClassOrigin, etc.)
105
106 karl 1.1 Replace optional request parameters with a 32 bit unsigned integer flags parameter.
107
108 <pre>struct OperationFlag
109 {
110 const static Uint32 localOnly = 0x00000001;
111 const static Uint32 includeQualifiers = 0x00000002;
112 const static Uint32 includeClassOrigin = 0x00000004;
113 const static Uint32 deepInheritance = 0x00000008;
114 };
115 The following is an example of the use of the compacted binary parameter.</pre>
116 <pre>CIMInstance MyProvider::getInstance(..., const Uint32 flags, ...)
117 {
118 // . . .
119 Boolean localOnly = false;
120 CIMInstance instance;
121 if(flags & OperationFlag::localOnly)
122 { // get only local properties
123 // . . .
124 }
125 return(CIMInstance(instance));
126 }
127 karl 1.1 </pre>
128
129 <h3>Simplify Object Identity Parameters</h3>
130
131 Operations currently use two arguments to identify objects.
132
133 <OL>
134 <LI> const String& namespace, String& className for class oriented operations (e.g., getClass() and enumerateInstances()).
135 <LI>const String& namespace, const CIMReference& instance in instance oriented operations (e.g., getInstance and enumInstances()).
136 </OL>
137
138 Use CIMReference which encapsulates namespace, class name, and key bindings (for instance references) and isolates operation methods
139 from changes in object identification (such as the addition of namespace type).
140
141 <pre>CIMInstance MyProvider::getInstance(const CIMReference & ref, …)
142 {
143 // get the namespace path (e.g., "root" or "root//sample"
144 String namespacePath = ref.getNamespace();
145
146 // get the class name
147 String className = ref.getModel().getClassName();
148 karl 1.1
149 // get the instance keys
150 Array<KeyBinding> keySet = ref.getKeyBindings();
151
152 if(keySet().getSize() == 0)
153 {
154 // throw exception
155 }
156 CIMInstance instance;
157
158 // ...
159
160 return(CIMInstance(instance));
161 }
162 Actually, this largely exists today. We are supplying the CIMReference including the namespacepath component normally
163 and the remainder of the CIMReference is part of the defined paths today. However, it requires changing the type for
164 the paths throughout the model Thus</pre>
165
166 <pre>
167 virtual CIMClass getClass(
168 const String& nameSpace,
169 karl 1.1 const String& className,
170 Boolean localOnly = true,
171 Boolean includeQualifiers = true,
172 Boolean includeClassOrigin = false,
173 const Array<String>& propertyList = EmptyStringArray());
174 </pre>
175
176 would become
177
178 <pre>
179 virtual CIMClass getClass(
180 const CIMReference& className,
181 Boolean localOnly = true,
182 Boolean includeQualifiers = true,
183 Boolean includeClassOrigin = false,
184 const Array<String>& propertyList = EmptyStringArray());
185 </pre>
186
187
188 To accomplish this:
189 <OL>
190 karl 1.1 <LI> All provider operations would change to drop the nameSpace parameter.
191
192 <LI>Those classes that provide className as a string would change to provide it
193 and the namespace as CIMReference (this is the following class operations.
194 <UL>
195 <LI>getClass
196 <LI>deleteClass
197 <LI>enumerateClassNames
198 <LI>enumerateClasses
199 </UL>
200 At the same time, it is not certain that we need the class interfaces for the provider. We have no plans to implement
201 a class provider at this point because we have not seen the requirement.
202
203 <LI>Most instance operations remaine the same except that the namespace parameter would be removed.
204
205 Thus, getInstance which today is:
206 <PRE>
207 virtual CIMInstance getInstance(
208 const String& nameSpace,
209 const CIMReference& instanceName,
210 Boolean localOnly = true,
211 karl 1.1 Boolean includeQualifiers = false,
212 Boolean includeClassOrigin = false,
213 const Array<String>& propertyList = EmptyStringArray());
214 </PRE>
215 Becomes:
216 <PRE>
217 virtual CIMInstance getInstance(
218
219 const CIMReference& instanceName,
220 Boolean localOnly = true,
221 Boolean includeQualifiers = false,
222 Boolean includeClassOrigin = false,
223 const Array<String>& propertyList = EmptyStringArray());
224 </PRE>
225
226 The following instance functions can be modified this way:
227 <UL>
228 <LI>getInstance
229 <LI>deleteInstance
230 <LI>enumerateInstances
231 <LI>getProperty
232 karl 1.1 <LI>setProperty
233 <LI>invokeMethod
234 </UL>
235
236 <LI>The qualifier functions probably do not need to be implemented in any case. It is not clear that we need class qualifier
237 modification tools in the provider.
238
239 <LI> The functions that will be different are those operations tha move entire clases or instances as part of the operation.
240 This includes
241 <UL>
242 <LI>createClass
243 <LI>createInstance
244 <LI>modifyClass
245 <LI>modifyInstance
246 </UL>
247 Today, for example, the modifyInstance is as follows:
248
249 <PRE>
250 virtual void modifyInstance(
251 const String& nameSpace,
252 CIMInstance& modifiedInstance);
253 karl 1.1 </PRE>
254 Could become:
255 <PRE>
256 TBD
257 </PRE>
258
259 <LI> Association operation - These functions represent minimal change since they use CIMReference today. For example:
260
261 <PRE>
262 virtual Array<CIMReference> referenceNames(
263 const String& nameSpace,
264 const CIMReference& objectName,
265 const String& resultClass = String::EMPTY,
266 const String& role = String::EMPTY);
267 </PRE>
268
269 Would be modified simply be modified by removing the nameSpace parameter.
270
271 <LI> Exec Query - The execQuery is a special case since the parameter set for this is unique.
272
273 <PRE>
274 karl 1.1 virtual Array<CIMInstance> execQuery(
275 const String& queryLanguage,
276 const String& query) ;
277 </PRE>
278
279 There is no reason to change this functional interface.
280
281 </OL>
282 <h3>Subdivide Provider Interface</h3>
283
284 TBD
285
286 <h3>Terminate Provider Operation</h3>
287
288 This one is simple. The method name is:
289 <pre>
290 Terminate();
291 </pre>
292
293 It will be issued by the Object Manager to all active providers in the process of Object Manager shutdown.
294 This means that ALL providers must implement this interface just as they must implement the <TT>Initialize()</TT> interface today.
295 karl 1.1 Normally the requirement on the provider would be to stop any continuous operations that are in process and then return a response.
296
297 At this point we have not proposed any special requirements such as timers for shutdown,etc.
298
299 <h3>Indication Interface</h3>
300
301 We will discuss this as part of another document on indication implementation.
302 </body>
303
304 </html>
|
Return to
provider_interface_proposal.htm
CVS log
Up to [Pegasus] / pegasus / doc / WorkPapers