1 karl 1.4 //%2005////////////////////////////////////////////////////////////////////////
|
2 chuck 1.2 //
|
3 karl 1.4 // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
4 // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
5 // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
|
6 chuck 1.2 // IBM Corp.; EMC Corporation, The Open Group.
|
7 karl 1.4 // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
8 // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
9 // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
10 // EMC Corporation; VERITAS Software Corporation; The Open Group.
|
11 chuck 1.2 //
12 // Permission is hereby granted, free of charge, to any person obtaining a copy
13 // of this software and associated documentation files (the "Software"), to
14 // deal in the Software without restriction, including without limitation the
15 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
16 // sell copies of the Software, and to permit persons to whom the Software is
17 // furnished to do so, subject to the following conditions:
18 //
19 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
20 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
21 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
22 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
23 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
24 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
25 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
26 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
27 //
28 //==============================================================================
29 //
30 // Authors: David Rosckes (rosckes@us.ibm.com)
31 // Bert Rivero (hurivero@us.ibm.com)
32 chuck 1.2 // Chuck Carmack (carmack@us.ibm.com)
33 // Brian Lucier (lucier@us.ibm.com)
34 //
35 // Modified By:
36 //
37 //%/////////////////////////////////////////////////////////////////////////////
38
39 #ifndef Pegasus_CQLSelectStatement_h
40 #define Pegasus_CQLSelectStatement_h
41
42 #include <Pegasus/Common/Config.h>
43 #include <Pegasus/Common/AutoPtr.h>
44 #include <Pegasus/Query/QueryCommon/SelectStatement.h>
45 #include <Pegasus/CQL/CQLChainedIdentifier.h>
46 #include <Pegasus/CQL/CQLPredicate.h>
47 #include <Pegasus/CQL/CQLIdentifier.h>
48 #include <Pegasus/CQL/Linkage.h>
49
50
51 #ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
52
53 chuck 1.2 PEGASUS_NAMESPACE_BEGIN
54
55 class PEGASUS_CQL_LINKAGE CQLSelectStatementRep;
56
57 /**
58 This class is derived from the SelectStatement base class.
59 The purpose of this class is to perform the select statement operations for
60 CIM Query Language (CQL).
|
61 chuck 1.3 */
|
62 chuck 1.2 class PEGASUS_CQL_LINKAGE CQLSelectStatement : public SelectStatement
63 {
64 public:
|
65 chuck 1.3
66 /**
67 Constructs a CQLSelectStatement default object.
68
69 @param - None.
70 @return - None.
71 @throw - None.
72
73 <I><B>Experimental Interface</B></I><BR>
74 */
|
75 chuck 1.2 CQLSelectStatement();
76
|
77 chuck 1.3 /**
78 Constructs a CQLSelectStatement object.
79
80 @param inQlang - String containing the language of the query.
81 @param inQuery - String containing the query.
82 @param inCtx - Context in which the select statement is running.
83 @return - None.
84 @throw - None.
85
86 <I><B>Experimental Interface</B></I><BR>
87 */
88 CQLSelectStatement(String& inQlang,
89 String& inQuery,
90 QueryContext& inCtx);
91
92 /**
93 Constructs a CQLSelectStatement object.
94
95 @param inQlang - String containing the language of the query.
96 @param inQuery - String containing the query.
97 @return - None.
98 chuck 1.3 @throw - None.
|
99 chuck 1.2
|
100 chuck 1.3 <I><B>Experimental Interface</B></I><BR>
101 */
|
102 chuck 1.2 CQLSelectStatement(String& inQLang, String& inQuery);
103
|
104 chuck 1.3 /**
105 Copy constructs a CQLSelectStatement object.
106
107 @param statement - CQLSelectStatement to be copied.
108 @return - None.
109 @throw - None.
110
111 <I><B>Experimental Interface</B></I><BR>
112 */
|
113 chuck 1.2 CQLSelectStatement(const CQLSelectStatement& statement);
114
|
115 chuck 1.3 /**
116 Destructs a CQLSelectStatement object.
117
118 @param - None.
119 @return - None.
120 @throw - None.
121
122 <I><B>Experimental Interface</B></I><BR>
123 */
|
124 chuck 1.2 ~CQLSelectStatement();
125
|
126 chuck 1.3 /**
127 Assigns a CQLSelectStatement to this object.
128
129 @param rhs - CQLSelectStatement to be assigned to this object.
130 @return - Updated this object.
131 @throw - None.
132
133 <I><B>Experimental Interface</B></I><BR>
134 */
|
135 chuck 1.2 CQLSelectStatement& operator=(const CQLSelectStatement& rhs);
136
|
137 chuck 1.3 /**
138 Applies the class contexts from the FROM list to the
139 chained identifiers in the statement. This will transform
140 each chained identifier into a normalized form. The FROM
141 classname is prepended if needed, and all class aliases are resolved.
142
143 Note: there are cases where the FROM classname is not prepended.
144 This can occur for the classname on the right side of ISA,
145 or the classname at the beginning of a symbolic constant chained
146 identifier. Neither of these classnames need to be the FROM class.
147
148 This function also validates that each chained identifier
149 is well-formed. It is possible for a chained identifier
150 to be syntactically correct in the CQL language, but
151 cannot be processed by the CQL engine.
152
153 Pre-condition: QueryContext has been set into this object.
154 Post-condition: Chained identifiers have been normalized.
155
156 @param None.
157 @return None
158 chuck 1.3 @throw CQLRuntimeException if the QueryContext had not been set.
159 @throw CQLValidationException if a chained identifier is not well formed.
160 @throw CQLSyntaxErrorException if a chained identifier is not well formed.
161
162 <I><B>Experimental Interface</B></I><BR>
163 */
164 void applyContext();
|
165 chuck 1.2
|
166 chuck 1.3 /**
167 Evaluates the WHERE clause of the select statement using
168 a CIM instance as the source of properties.
169
170 Pre-condition: QueryContext has been set into this object.
171 Post-condition: Chained identifiers have been normalized
172 ie.applyContext has been called. See the applyContext function.
|
173 chuck 1.2
|
174 chuck 1.3 @param inCI - The instance to be evaluated.
175 @return True, if the WHERE clause evaluates to true based on
176 the type of the instance and its properties.
177 @throw CQLRuntimeException if the instance cannot be evaluated
178 @throw CQLValidationException for applyContext error.
179 @throw CQLSyntaxErrorException for applyContext error.
180
181 <I><B>Experimental Interface</B></I><BR>
182 */
183 Boolean evaluate(const CIMInstance& inCI);
184
185 /**
186 Projects the properties in the SELECT list of the select
187 statement onto the instance. This involves checking that
188 all required properties exist on the instance passed in,
189 and removing any unneeded properties from that instance.
190
191 Pre-condition: QueryContext has been set into this object.
192 Post-condition: Chained identifiers have been normalized
193 ie.applyContext has been called. See the applyContext function.
194
195 chuck 1.3 @param inCI - The instance to be projected.
196 @return None
197 @throw CQLRuntimeException if the instance cannot be projected
198 @throw CQLValidationException for applyContext error.
199 @throw CQLSyntaxErrorException for applyContext error.
200
201 <I><B>Experimental Interface</B></I><BR>
202 */
203 void applyProjection(CIMInstance& inCI) throw(Exception);
204
205 /**
206 Validates the classes and properties used in the select statement
207 against the class schema. The existence of classes and properties
208 are checked, along with class relationships defined in the CQL
209 specification.
210
211 Pre-condition: QueryContext has been set into this object.
212 Post-condition: Chained identifiers have been normalized
213 ie.applyContext has been called. See the applyContext function.
214
215 @param None
216 chuck 1.3 @return None
217 @throw CQLValidationException for applyContext error, the select
218 statement is invalid against the schema, or the QueryContext has
219 not been set.
220 @throw CQLSyntaxErrorException for applyContext error.
221
222 <I><B>Experimental Interface</B></I><BR>
223 */
|
224 chuck 1.2 void validate() throw(Exception);
225
|
226 chuck 1.3 /**
227 Normalizes the predicates in the WHERE clause to a
228 disjunction of conjunctions.
|
229 chuck 1.2
|
230 chuck 1.3 Post-condition: Chained identifiers have been normalized
231 ie.applyContext has been called. See the applyContext function.
|
232 chuck 1.2
|
233 chuck 1.3 @param None
234 @return None
235 @throw None
|
236 chuck 1.2
|
237 chuck 1.3 <I><B>Experimental Interface</B></I><BR>
238 */
239 void normalizeToDOC();
|
240 chuck 1.2
|
241 chuck 1.3 /**
242 Returns an array of CIMObjectPath objects that are the
243 class paths in the FROM list of the select statement.
|
244 chuck 1.2
|
245 chuck 1.3 Note: Currently CQL only supports one class path in the
246 FROM list. This class path does not support WBEM-URI, so that
247 only the namespace and classname parts are filled in.
|
248 chuck 1.2
|
249 chuck 1.3 Pre-condition: QueryContext has been set into this object.
|
250 chuck 1.2
|
251 chuck 1.3 @param None
252 @return Array of FROM list class paths.
253 @throw CQLRuntimeException if the QueryContext had not been set.
|
254 chuck 1.2
|
255 chuck 1.3 <I><B>Experimental Interface</B></I><BR>
256 */
257 Array<CIMObjectPath> getClassPathList();
|
258 chuck 1.2
|
259 chuck 1.3 /**
260 Returns the required properties from the combined SELECT and WHERE
261 clauses for the classname passed in. The classname parameter is
262 needed in case scoping operators are used in the select statement.
263 This function does not return properties for the classname if they
264 are required on embedded objects. This function does not return
265 required array indices.
266
267 Pre-condition: QueryContext has been set into this object.
268 Post-condition: Chained identifiers have been normalized
269 ie.applyContext has been called. See the applyContext function.
270
271 @param inClassName - class to determine the required properties. Defaults
272 to the FROM class.
273 @return CIMPropertyList containing the required properties for the class.
274 If all the properties are required, a null CIMPropertyList is returned.
275 If no properties are required, an empty CIMPropertyList is returned.
276 @throw CQLRuntimeException if the QueryContext had not been set.
277 @throw CQLValidationException for applyContext error.
278 @throw CQLSyntaxErrorException for applyContext error.
279
280 chuck 1.3 <I><B>Experimental Interface</B></I><BR>
281 */
282 CIMPropertyList getPropertyList(const CIMObjectPath& inClassName = CIMObjectPath());
283
284 /**
285 Returns the required properties from the SELECT clause for the
286 classname passed in. The classname parameter is needed in case
287 scoping operators are used in the select statement. This function
288 does not return properties for the classname if they are required
289 on embedded objects. This function does not return required array indices.
290
291 Pre-condition: QueryContext has been set into this object.
292 Post-condition: Chained identifiers have been normalized
293 ie.applyContext has been called. See the applyContext function.
294
295 @param inClassName - class to determine the required properties. Defaults
296 to the FROM class.
297 @return CIMPropertyList containing the required properties for the class.
298 If all the properties are required, a null CIMPropertyList is returned.
299 If no properties are required, an empty CIMPropertyList is returned.
300 @throw CQLRuntimeException if the QueryContext had not been set.
301 chuck 1.3 @throw CQLValidationException for applyContext error.
302 @throw CQLSyntaxErrorException for applyContext error.
303
304 <I><B>Experimental Interface</B></I><BR>
305 */
306 CIMPropertyList getSelectPropertyList(const CIMObjectPath& inClassName = CIMObjectPath());
307
308 /**
309 Returns the required properties from the WHERE clause for the
310 classname passed in. The classname parameter is needed in case
311 scoping operators are used in the select statement. This function
312 does not return properties for the classname if they are required
313 on embedded objects. This function does not return required array indices.
314
315 Pre-condition: QueryContext has been set into this object.
316 Post-condition: Chained identifiers have been normalized
317 ie.applyContext has been called. See the applyContext function.
318
319 @param inClassName - class to determine the required properties. Defaults
320 to the FROM class.
321 @return CIMPropertyList containing the required properties for the class.
322 chuck 1.3 If all the properties are required, a null CIMPropertyList is returned.
323 If no properties are required, an empty CIMPropertyList is returned.
324 @throw CQLRuntimeException if the QueryContext had not been set.
325 @throw CQLValidationException for applyContext error.
326 @throw CQLSyntaxErrorException for applyContext error.
327
328 <I><B>Experimental Interface</B></I><BR>
329 */
330 CIMPropertyList getWherePropertyList(const CIMObjectPath& inClassName = CIMObjectPath());
|
331 chuck 1.2
332 /**
|
333 chuck 1.3 Returns the chained identifiers from the SELECT clause. These chained
334 identifiers contain the fully qualified property names, including embedded
335 objects, array indices, scoping operators, and symbolic constants.
336
337 Post-condition: Chained identifiers have been normalized
338 ie.applyContext has been called. See the applyContext function.
339
340 @param None
341 @return Array of chained identifiers.
342 @throw CQLValidationException for applyContext error.
343 @throw CQLSyntaxErrorException for applyContext error.
344
345 <I><B>Experimental Interface</B></I><BR>
|
346 chuck 1.2 */
|
347 chuck 1.3 Array<CQLChainedIdentifier> getSelectChainedIdentifiers();
|
348 chuck 1.2
349 /**
|
350 chuck 1.3 Returns the chained identifiers from the WHERE clause. These chained
351 identifiers contain the fully qualified property names, including embedded
352 objects, array indices, scoping operators, and symbolic constants.
353
354 Pre-condition: QueryContext has been set into this object.
355 Post-condition: Chained identifiers have been normalized
356 ie.applyContext has been called. See the applyContext function.
357
358 @param None
359 @return Array of chained identifiers.
360 @throw CQLRuntimeException if the QueryContext had not been set.
361 @throw CQLValidationException for applyContext error.
362 @throw CQLSyntaxErrorException for applyContext error.
363
364 <I><B>Experimental Interface</B></I><BR>
|
365 chuck 1.2 */
|
366 chuck 1.3 Array<CQLChainedIdentifier> getWhereChainedIdentifiers();
367
368 /**
369 Gets the top-level CQLPredicate of this object.
370 This is the predicate that contains the top-level
371 of any nested boolean operations in the WHERE clause.
372
373 @param None.
374 @return Top-level predicate
375 @throw None.
376
377 <I><B>Experimental Interface</B></I><BR>
378 */
379 CQLPredicate getPredicate() const;
380
381 /**
382 Determines whether the select statement has a WHERE clause.
|
383 chuck 1.2
|
384 chuck 1.3 @param None
385 @return True if there is a WHERE clause.
386 @throw None
|
387 chuck 1.2
|
388 chuck 1.3 <I><B>Experimental Interface</B></I><BR>
389 */
|
390 chuck 1.2 Boolean hasWhereClause();
391
|
392 chuck 1.3 /**
393 Returns the select statement in string form.
394 Note that this can be different than the original
395 statement after it has been parsed, and applyContext
396 has been called.
397
398 Pre-condition: QueryContext has been set into this object.
399
400 @param None
401 @return String containing the select statement.
402 @throw
403
404 <I><B>Experimental Interface</B></I><BR>
405 */
|
406 chuck 1.2 String toString();
407
|
408 chuck 1.3 /*
409 ATTN - the following methods should only be set by CQLParser.
410 These should be made private, and CQLParser made a friend.
411 */
412
413 /**
414 Appends a CQLIdentifier/alias combination into the FROM list of the
415 statement. This method should only be called by the CQL parser.
416
417 @param inIdentifier - CQLIdentifier to append.
418 @param inAlias - Alias of the identifier.
419 @return None
420 @throw QueryException if the identifier/alias cannot be appended.
421
422 <I><B>Experimental Interface</B></I><BR>
423 */
424 void insertClassPathAlias(const CQLIdentifier& inIdentifier,
425 String inAlias);
426
427 /**
428 Appends a CQLIdentifier into the FROM list of the statement.
429 chuck 1.3 This method should only be called by the CQL parser.
430
431 @param inIdentifier - CQLIdentifier to append.
432 @return None
433 @throw QueryException if the identifier cannot be appended.
434
435 <I><B>Experimental Interface</B></I><BR>
436 */
437 void appendClassPath(const CQLIdentifier& inIdentifier);
438
439 /**
440 Appends a CQLChainedIdentifier to the select list.
441 This method should only be called by the CQL parser.
442
443 @param x - CQLChainedIdentifier to append.
444 @return None
445 @throw None
446
447 <I><B>Experimental Interface</B></I><BR>
448 */
449 void appendSelectIdentifier(const CQLChainedIdentifier& x);
450 chuck 1.3
451 /** Sets a predicate into this object. This method should only
452 be called by Bison.
453 */
454 /**
455 Sets the top-level CQLPredicate into this object.
456 This method should only be called by the CQL parser.
457
458 @param Predicate to set into this object.
459 @return None
460 @throw None.
461
462 <I><B>Experimental Interface</B></I><BR>
463 */
464 void setPredicate(const CQLPredicate& inPredicate);
465
466 /**
467 Sets the select statement to have a WHERE clause.
468 This method should only be called by the CQL parser.
469
470 @param None
471 chuck 1.3 @return None
472 @throw None
473
474 <I><B>Experimental Interface</B></I><BR>
475 */
476 void setHasWhereClause();
477
478 /**
479 Clears the internal data structures.
480 This method should only be called by the CQL parser.
481
482 Pre-condition: QueryContext has been set into this object.
483
484 @param None
485 @return None.
486 @throw CQLRuntimeException if the QueryContext had not been set.
487
488 <I><B>Experimental Interface</B></I><BR>
489 */
|
490 chuck 1.2 void clear();
491
492 private:
493 CQLSelectStatementRep* _rep;
494
495 };
496
497 PEGASUS_NAMESPACE_END
498 #endif
499 #endif
|