58 karl 1.1
59 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.
60
61 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.
62 <p>This document is a proposal to make these changes.</p>
63
64 <h2>Objectives </h2>
65
66 <OL>
67 <LI>Extend for the next set of functionality primarily indications.
68 <LI>Provide more information to the provider
69 <LI>Enable providers to perform varying levels of operation (dump and smart providers).
70 <LI>Support implementation specific objects.
71 <LI>Isolate the API from changes to the CIM standard and implementation specific objects.
72 <LI>Prepare for the implementation of standardized provider registration
73 </OL>
74
75 <h2>Summary of Proposed Changes</h2>
76
77 We propose the following changes:
78 <OL>
79 karl 1.1 <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.
80
81 <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
82
83 <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.
84
85 WHY?
86
87 <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.
88
89 <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.
90
91 <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>
92 </OL>
93 <h2>Definition of the Proposed Changes</h2>
94
95 This section defines the proposed implementation for each of these changes.
96
97 <h3>Context for each Provider and for each Operation</h3>
98
99 Operations do not currently support parameters to describe context information (such as security or localization parameters).
100 karl 1.1 In addition, there will be additional requirements for the provider to request
101 information for things like system parameters, system state information, etc.
102 <p>As part of this we also want to create a handle so that CIM Operations can be
103 effecitively passed from the provider back to the Object Manager.</p>
104 <p>We propose modifying both the provider context and adding an operational
105 context parameter. </p>
106 <h4>Provider Context</h4>
107 <p>Today - one parameter, the CIM Repository handle provided with the initialize
108 as follows:</p>
109 <pre>virtual void initialize(CIMRepository& repository);</pre>
110 The provider saves the repository handle for later access using the CIMRepository interface. We don't want providers to have access to the repository
111 but we do want them to have easy access back to the Object Manager with CIM
112 Operations.
113 <p>We could provide access to the Object Manager delegator except that this
114 would bypass any security features that we would want to implement. We
115 propose adding a new interface which will provide:</p>
116 <ul>
117 <li>A way to put CIM Operations (getClass, etc.) back into the Object
118 Manager</li>
119 <li>Additional specific operations required by the provider -</li>
120 <li> </li>
121 karl 1.1 </ul>
122 <h4>Operation Context</h4>
123 <p>Introduce OperationContext which communicates context information to operation methods and allows implementation specific context information to be passed to providers.<br>
124 OperationContext encapsulates<br>
125 Locale information<br>
126 User credentials<br>
127 Implementation TBD</p>
128
129 <pre>CIMInstance MyProvider::getInstance(..., const OperationContext & context, ...)
130 {
131 // ...
132 // get locale from operation context
133 // ...
134 // get user credentials from operation context
135 // ...
136 return(CIMInstance(instance));
137 }</pre>
138
139 <h3>Boolean Parameters</h3>
140
141 Operations currently use multiple arguments to represent additional information (Boolean localOnly, Boolean includeQualifiers, Boolean includeClassOrigin, etc.)
142 karl 1.1
143 Replace optional request parameters with a 32 bit unsigned integer flags parameter.
144
145 <pre>struct OperationFlag
146 {
147 const static Uint32 localOnly = 0x00000001;
148 const static Uint32 includeQualifiers = 0x00000002;
149 const static Uint32 includeClassOrigin = 0x00000004;
150 const static Uint32 deepInheritance = 0x00000008;
151 };
152 The following is an example of the use of the compacted binary parameter.</pre>
153 <pre>CIMInstance MyProvider::getInstance(..., const Uint32 flags, ...)
154 {
155 // . . .
156 Boolean localOnly = false;
157 CIMInstance instance;
158 if(flags & OperationFlag::localOnly)
159 { // get only local properties
160 // . . .
161 }
162 return(CIMInstance(instance));
163 karl 1.1 }
164 </pre>
165
166 <h3>Simplify Object Identity Parameters</h3>
167
168 Operations currently use two arguments to identify objects.
169
170 <OL>
171 <LI> const String& namespace, String& className for class oriented operations (e.g., getClass() and enumerateInstances()).
172 <LI>const String& namespace, const CIMReference& instance in instance oriented operations (e.g., getInstance and enumInstances()).
173 </OL>
174
175 Use CIMReference which encapsulates namespace, class name, and key bindings (for instance references) and isolates operation methods
176 from changes in object identification (such as the addition of namespace type).
177
178 <pre>CIMInstance MyProvider::getInstance(const CIMReference & ref, …)
179 {
180 // get the namespace path (e.g., "root" or "root//sample"
181 String namespacePath = ref.getNamespace();
182
183 // get the class name
184 karl 1.1 String className = ref.getModel().getClassName();
185
186 // get the instance keys
187 Array<KeyBinding> keySet = ref.getKeyBindings();
188
189 if(keySet().getSize() == 0)
190 {
191 // throw exception
192 }
193 CIMInstance instance;
194
195 // ...
196
197 return(CIMInstance(instance));
198 }
199 Actually, this largely exists today. We are supplying the CIMReference including the namespacepath component normally
200 and the remainder of the CIMReference is part of the defined paths today. However, it requires changing the type for
201 the paths throughout the model Thus</pre>
202
203 <pre>
204 virtual CIMClass getClass(
205 karl 1.1 const String& nameSpace,
206 const String& className,
207 Boolean localOnly = true,
208 Boolean includeQualifiers = true,
209 Boolean includeClassOrigin = false,
210 const Array<String>& propertyList = EmptyStringArray());
211 </pre>
212
213 would become
214
215 <pre>
216 virtual CIMClass getClass(
217 const CIMReference& className,
218 Boolean localOnly = true,
219 Boolean includeQualifiers = true,
220 Boolean includeClassOrigin = false,
221 const Array<String>& propertyList = EmptyStringArray());
222 </pre>
223
224
225 To accomplish this:
226 karl 1.1 <OL>
227 <LI> All provider operations would change to drop the nameSpace parameter.
228
229 <LI>Those classes that provide className as a string would change to provide it
230 and the namespace as CIMReference (this is the following class operations.
231 <UL>
232 <LI>getClass
233 <LI>deleteClass
234 <LI>enumerateClassNames
235 <LI>enumerateClasses
236 </UL>
237 At the same time, it is not certain that we need the class interfaces for the provider. We have no plans to implement
238 a class provider at this point because we have not seen the requirement.
239
240 <LI>Most instance operations remaine the same except that the namespace parameter would be removed.
241
242 Thus, getInstance which today is:
243 <PRE>
244 virtual CIMInstance getInstance(
245 const String& nameSpace,
246 const CIMReference& instanceName,
247 karl 1.1 Boolean localOnly = true,
248 Boolean includeQualifiers = false,
249 Boolean includeClassOrigin = false,
250 const Array<String>& propertyList = EmptyStringArray());
251 </PRE>
252 Becomes:
253 <PRE>
254 virtual CIMInstance getInstance(
255
256 const CIMReference& instanceName,
257 Boolean localOnly = true,
258 Boolean includeQualifiers = false,
259 Boolean includeClassOrigin = false,
260 const Array<String>& propertyList = EmptyStringArray());
261 </PRE>
262
263 The following instance functions can be modified this way:
264 <UL>
265 <LI>getInstance
266 <LI>deleteInstance
267 <LI>enumerateInstances
268 karl 1.1 <LI>getProperty
269 <LI>setProperty
270 <LI>invokeMethod
271 </UL>
272
273 <LI>The qualifier functions probably do not need to be implemented in any case. It is not clear that we need class qualifier
274 modification tools in the provider.
275
276 <LI> The functions that will be different are those operations tha move entire clases or instances as part of the operation.
277 This includes
278 <UL>
279 <LI>createClass
280 <LI>createInstance
281 <LI>modifyClass
282 <LI>modifyInstance
283 </UL>
284 Today, for example, the modifyInstance is as follows:
285
286 <PRE>
287 virtual void modifyInstance(
288 const String& nameSpace,
289 karl 1.1 CIMInstance& modifiedInstance);
290 </PRE>
291 Could become:
292 <PRE>
293 TBD
294 </PRE>
295
296 <LI> Association operation - These functions represent minimal change since they use CIMReference today. For example:
297
298 <PRE>
299 virtual Array<CIMReference> referenceNames(
300 const String& nameSpace,
301 const CIMReference& objectName,
302 const String& resultClass = String::EMPTY,
303 const String& role = String::EMPTY);
304 </PRE>
305
306 Would be modified simply be modified by removing the nameSpace parameter.
307
308 <LI> Exec Query - The execQuery is a special case since the parameter set for this is unique.
309
310 karl 1.1 <PRE>
311 virtual Array<CIMInstance> execQuery(
312 const String& queryLanguage,
313 const String& query) ;
314 </PRE>
315
316 There is no reason to change this functional interface.
317
318 </OL>
319 <h3>Subdivide Provider Interface</h3>
320
|
Return to
provider_interface_proposal.htm
CVS log
Up to [Pegasus] / pegasus / doc / WorkPapers