1 karl  1.37 //%2003////////////////////////////////////////////////////////////////////////

  2 mike  1.17 //

  3 karl  1.37 // 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            // IBM Corp.; EMC Corporation, The Open Group.

  7 mike  1.17 //
  8            // Permission is hereby granted, free of charge, to any person obtaining a copy

  9 kumpf 1.25 // of this software and associated documentation files (the "Software"), to
 10            // deal in the Software without restriction, including without limitation the
 11            // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or

 12 mike  1.17 // sell copies of the Software, and to permit persons to whom the Software is
 13            // furnished to do so, subject to the following conditions:
 14            // 

 15 kumpf 1.25 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN

 16 mike  1.17 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 17            // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT

 18 kumpf 1.25 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 19            // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 20            // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN

 21 mike  1.17 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 22            // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 23            //
 24            //==============================================================================
 25            //
 26            // Author: Mike Brasher (mbrasher@bmc.com)
 27            //

 28 kumpf 1.20 // Modified By: Roger Kumpf, Hewlett-Packard Company (roger_kumpf@hp.com)

 29 kumpf 1.27 //              Carol Ann Krug Graves, Hewlett-Packard Company
 30            //                (carolann_graves@hp.com)

 31 mike  1.17 //
 32            //%/////////////////////////////////////////////////////////////////////////////
 33            
 34            #ifndef Pegasus_Method_h
 35            #define Pegasus_Method_h
 36            
 37            #include <Pegasus/Common/Config.h>

 38 kumpf 1.30 #include <Pegasus/Common/Linkage.h>

 39 kumpf 1.20 #include <Pegasus/Common/String.h>

 40 kumpf 1.30 #include <Pegasus/Common/CIMName.h>

 41 kumpf 1.20 #include <Pegasus/Common/CIMParameter.h>
 42            #include <Pegasus/Common/CIMQualifier.h>
 43            #include <Pegasus/Common/CIMType.h>

 44 mike  1.17 
 45            PEGASUS_NAMESPACE_BEGIN
 46            

 47 kumpf 1.28 class Resolver;

 48 mike  1.17 class CIMConstMethod;

 49 kumpf 1.20 class CIMMethodRep;

 50 mike  1.17 

 51 karl  1.38 /** The CIMMethod class is used to represent CIM methods in Pegasus. A CIMMethod
 52                consists of the following entities
 53                <ul>
 54                    <li>Name of the method, a CIMName
 55                    <li>CIMType of the method, a CIMType
 56                    <li>Optional Qualifiers for the method
 57                    <li>Optional Parameters for the method
 58                </ul>
 59                In addition, internally, there are the following additional attributes
 60                that are part of a CIMMethod.
 61                <ul>
 62                    <li>propagated - attributed defining whether this CIMMethod is 
 63                    propagated from a superclass.  Note that this is normally set
 64                    as part of resolving objects when they are placed in a repository
 65                    and is NOT automatically set when creating a local object.  It
 66                    can only logically be set in context of the superclass of which
 67                    this CIMMethod is defined.
 68                    <li>ClassOrigin - attribute defining the superclass in which this
 69                    CIMMethod was originally defined.  This is normally se as part
 70                    of resolving Class and instances.  It is available from objects
 71                    retrieved from the repository.
 72 karl  1.38     </ul>
 73                CIMMethod is a shared class and uses a representation object and reference
 74                counting to control the lifecycle of the objects.
 75                @see CIMConstMethod

 76 mike  1.17 */
 77            class PEGASUS_COMMON_LINKAGE CIMMethod
 78            {
 79            public:
 80            

 81 karl  1.38     /** Creates a new default CIMMethod object. The object created is
 82                    empty.  Other methods such as setName() or assign must be
 83                    used to provide attributes for the object
 84                    @see CIMConstMethod()
 85                */

 86 kumpf 1.20     CIMMethod();

 87 mike  1.17 

 88 karl  1.38     /** Creates a new CIMMethod object from another method instance. This method
 89                    assigns the new object to the representation in the parameter and increments the
 90                    representation count.  It does NOT create a new independent object.
 91                    @param x - CIMMethod object from which to create CIMMethod object.
 92                    <pre>
 93                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
 94                        const CIMMethod cm1(m1);
 95                    </pre>

 96 mike  1.17     */

 97 kumpf 1.20     CIMMethod(const CIMMethod& x);

 98 mike  1.17 

 99 karl  1.38     /** Creates a CIMMethod object with the specified name and other input parameters.
100                    @param name CIMName defining the name for the method.
101                    @param type CIMType defining data type of method to create. See 
102                        
103                    @param classOrigin (optional) CIMName representing the class origin. Note
104                        that this should normally not be used.  If not provided set to
105                        CIMName() (Null name).
106                    @param propagated Optional flag indicating whether the definition of the 
107                        CIM Method is local to the CIM Class (respectively, Instance) in which 
108                        it appears, or was propagated without modification from the underlying 
109                        Subclass (respectively, Class). Default is false.
110                    <pre>
111                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING)
112                    </pre>

113 mike  1.17     */
114                CIMMethod(

115 karl  1.38         const CIMName& name,
116                    CIMType type,
117                    const CIMName& classOrigin = CIMName(),
118                    Boolean propagated = false);
119            
120                /** Destructor for the CIMMethod. Since this is a shared class, the destructor
121                    is automatically executed when the representation reference count becomes
122                    zero
123                */

124 kumpf 1.20     ~CIMMethod();
125            

126 karl  1.38     /** Assignment operator. Assigns one CIM method to another.  This method performs
127                    the assignment by incrementing the reference count for the representation of
128                    the CIMMethod, not by creating a deep copy of the object
129                */

130 kumpf 1.20     CIMMethod& operator=(const CIMMethod& x);

131 mike  1.17 

132 kumpf 1.36     /** Gets the name of the method.

133 karl  1.38         @return CIMName with the name of the method.
134                    <pre>
135                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING)
136                        assert(m1.getName() == CIMName ("getHostName"));
137                    </pre>

138 mike  1.17     */

139 kumpf 1.30     const CIMName& getName() const;

140 mike  1.17 

141 kumpf 1.36     /** Sets the method name.

142 karl  1.38         @param name - CIMName for the method name. Replaces any
143                        previously defined name for this method object.
144                    <pre>
145                        CIMMethod m2(CIMName ("test"), CIMTYPE_STRING);
146                        m2.setName(CIMName ("getVersion"));
147                    </pre>

148 mike  1.17     */

149 kumpf 1.30     void setName(const CIMName& name);

150 mike  1.17 

151 kumpf 1.36     /** Gets the method type.

152 karl  1.38         @return The CIMType containing the method type for this method.
153                    <pre>
154                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING)
155                        assert(m1.getType() == CIMTYPE_STRING);
156                    </pre>

157 mike  1.17     */

158 kumpf 1.20     CIMType getType() const;

159 mike  1.17 

160 kumpf 1.36     /** Sets the method type to the specified CIM method type 
161                    as defined in CIMType.

162 karl  1.38         @param type CIMType to be set into the method object.
163                    <pre>
164                        CIMMethod m1();
165                        m1.setName(CIMName ("getVersion"));
166                        assert(m1.setType(CIMTYPE_STRING));
167                    </pre>

168 mike  1.17     */

169 kumpf 1.20     void setType(CIMType type);

170 mike  1.17 

171 karl  1.38     /** Gets the class in which this method was defined. This information
172                    is available after the class containing the method has been
173                    resolved and is part of the class repository.
174                    @return CIMName containing the classOrigin field. 

175 mike  1.17     */

176 kumpf 1.30     const CIMName& getClassOrigin() const;

177 mike  1.17 

178 kumpf 1.36     /** Sets the ClassOrigin attribute with the classname defined on 

179 karl  1.38         the input parameter. Normally this function is used internally
180                    as part of resolving the objects containing methods (classes
181                    and instances). 
182                @param classOrigin - CIMName parameter defining the name
183                of the class origin.

184 kumpf 1.20     */

185 kumpf 1.30     void setClassOrigin(const CIMName& classOrigin);

186 mike  1.17 

187 karl  1.38     /** Tests the propagated qualifier.  The propagated attribute
188                    indicates if this method was propagated from a higher level
189                    class.  Normally this attribute is set as part of putting
190                    classes into the repository (resolving the class).  It is 
191                    available on methods in classes read from the repository and
192                    on instances that are read from the instance repository.

193 kumpf 1.36         @return true if method is propagated, false otherwise.

194 kumpf 1.20     */
195                Boolean getPropagated() const;

196 mike  1.17 

197 karl  1.38     /** Sets the Propagaged Qualifier. Normally this is used by the functions
198                    that resolve classes and instances as part of the installation into
199                    a repository.
200                    @param propagated Flag indicating propagation. True means that
201                    the method was propagated from a superclass.

202 kumpf 1.36     */

203 kumpf 1.20     void setPropagated(Boolean propagated);

204 mike  1.17 

205 kumpf 1.36     /** Adds the specified qualifier to the method and increments the
206                    qualifier count. 
207                    @param x - CIMQualifier object representing the qualifier
208                    to be added.
209                    @return the CIMMethod object after adding the specified qualifier.
210                    @exception AlreadyExistsException if the qualifier already exists.

211 karl  1.38         <pre>
212                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
213                        m1.addQualifier(CIMQualifier(CIMName ("stuff"), true));
214                    </pre>

215 mike  1.17     */

216 kumpf 1.20     CIMMethod& addQualifier(const CIMQualifier& x);

217 mike  1.17 

218 kumpf 1.36     /** Searches for a qualifier with the specified input name.
219                    @param name - CIMName of the qualifier to be found.
220                    @return Index of the qualifier found or PEG_NOT_FOUND
221                    if not found.

222 karl  1.38         <pre>
223                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
224                        m1.addQualifier(CIMQualifier(CIMName ("stuff"), true));
225                        assert(m1.findQualifier(CIMName ("stuff")) != PEG_NOT_FOUND);
226                    </pre>

227 mike  1.17     */

228 kumpf 1.30     Uint32 findQualifier(const CIMName& name) const;

229 mike  1.17 

230 kumpf 1.36     /** Gets the CIMQualifier defined by the input parameter.

231 karl  1.38         @param index - Index of the qualifier requested.
232                    @return CIMQualifier object representing the qualifier found.
233                    @exception IndexOutOfBoundsException exception if the index is

234 kumpf 1.34         outside the range of parameters available from the CIMMethod.

235 karl  1.38         <pre>
236                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
237                        m1.addQualifier(CIMQualifier(CIMName ("stuff"), true));
238                        Uint32 posQualifier;
239                        posQualifier = m1.findQualifier(CIMName ("stuff"));
240                        CIMQualifier q = m1.getQualifier(posQualifier);
241                    </pre>

242 mike  1.17     */

243 kumpf 1.35     CIMQualifier getQualifier(Uint32 index);

244 kumpf 1.20 

245 kumpf 1.36     /** Gets the CIMQualifier defined by the input parameter.

246 karl  1.38         @param index - Index of the qualifier requested.
247                    @return CIMConstQualifier object representing the qualifier found.
248                    @exception IndexOutOfBoundsException exception if the index is

249 kumpf 1.36         outside the range of parameters available from the CIMMethod.

250 karl  1.38         <pre>
251                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
252                        m1.addQualifier(CIMQualifier(CIMName ("stuff"), true));
253                        
254                        Uint32 posQualifier;
255                        posQualifier = m1.findQualifier(CIMName ("stuff"));
256                        CIMQualifier q = m1.getQualifier(posQualifier);
257                    </pre>

258 kumpf 1.36     */

259 kumpf 1.35     CIMConstQualifier getQualifier(Uint32 index) const;

260 mike  1.17 

261 kumpf 1.36     /** Removes the specified CIMQualifier from this method.

262 karl  1.38         @param index - Index of the qualifier to remove.
263                    @exception IndexOutOfBoundsException exception if the index is
264                        outside the range of parameters available from the CIMMethod.

265 mike  1.17     */

266 kumpf 1.35     void removeQualifier(Uint32 index);

267 mike  1.17 

268 kumpf 1.36     /** Returns the number of Qualifiers attached to this CIMMethod object.
269                    @return the number of qualifiers in the CIM Method.

270 karl  1.38         <pre>
271                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
272                        m1.addQualifier(CIMQualifier(CIMName ("stuff"), true));
273                        m1.addQualifier(CIMQualifier(CIMName ("stuff2"), true));
274                        assert(m1.getQualifierCount() == 2);
275                    </pre>

276 mike  1.17     */

277 kumpf 1.20     Uint32 getQualifierCount() const;

278 mike  1.17 

279 kumpf 1.36     /** Adds the parameter defined by the input to the CIMMethod.
280                    @param x - CIMParameter to be added to the CIM Method.
281                    @return CIMMethod object after the specified parameter is added.

282 karl  1.38         <pre>
283                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
284                        m1.addParameter(CIMParameter(CIMName ("ipaddress"), CIMTYPE_STRING));
285                    </pre>

286 mike  1.17     */

287 kumpf 1.20     CIMMethod& addParameter(const CIMParameter& x);

288 mike  1.17 

289 kumpf 1.36     /** Finds the parameter with the specified name.

290 karl  1.38         @param name - Name of parameter to be found.

291 kumpf 1.36         @return Index of the parameter object found or PEG_NOT_FOUND 
292                    if the property is not found.

293 karl  1.38         <pre>
294                        Uint32 posParameter;
295                        posParameter = m1.findParameter(CIMName ("ipaddress"));
296                        if (posParameter != PEG_NOT_FOUND)
297                            ...
298                    </pre>

299 mike  1.17     */

300 kumpf 1.30     Uint32 findParameter(const CIMName& name) const;

301 mike  1.17 

302 kumpf 1.36     /** Gets the parameter defined by the specified index.

303 karl  1.38         @param index - Index for the parameter to be returned.
304                    @return CIMParameter object requested.
305                    @exception IndexOutOfBoundsException if the index is outside 
306                        the range of available parameters.
307                    <pre>
308                        CIMParameter cp = m1.getParameter(m1.findParameter(CIMName ("ipaddress")));
309                    </pre>

310 mike  1.17     */

311 kumpf 1.35     CIMParameter getParameter(Uint32 index);

312 kumpf 1.26 

313 kumpf 1.36     /** Gets the parameter defined for the specified index.

314 karl  1.38         @param index - Index for the parameter to be returned.
315                    @return CIMConstParameter object requested.
316                    @exception IndexOutOfBoundsException if the index is outside 
317                        the range of available parameters

318 kumpf 1.36     */

319 kumpf 1.35     CIMConstParameter getParameter(Uint32 index) const;

320 kumpf 1.33 

321 kumpf 1.36     /** Removes the CIMParameter defined by the specified index.

322 karl  1.38         @param index - Index of the parameter to be removed.
323                    @exception IndexOutOfBoundsException if the index is outside the
324                        range of parameters available from the CIMMethod.

325 kumpf 1.33     */

326 kumpf 1.35     void removeParameter (Uint32 index);

327 mike  1.17 

328 kumpf 1.36     /** Gets the count of Parameters defined in the CIMMethod.

329 karl  1.38         @return - count of the number of parameters attached to the CIMMethod.

330 mike  1.17     */

331 kumpf 1.20     Uint32 getParameterCount() const;

332 mike  1.17 

333 kumpf 1.36     /** Determines if the object has not been initialized.
334                    @return  true if the object has not been initialized,

335 karl  1.38                  false otherwise false.

336 kumpf 1.32      */
337                Boolean isUninitialized() const;

338 mike  1.17 

339 kumpf 1.36     /** Compares with another CIMConstMethod.
340                    @param x - CIMConstMethod object for the method to be compared.
341                    @return true if this method is identical to the one specified.

342 karl  1.38         <pre>
343                        CIMMethod m1(CIMName ("getHostName"), CIMTYPE_STRING);
344                        CIMMethod m2(CIMName ("test"), CIMTYPE_STRING);
345                        assert(!m1.identical(m2));
346                    </pre>

347 mike  1.17     */
348                Boolean identical(const CIMConstMethod& x) const;
349            

350 kumpf 1.36     /** Makes a deep copy (clone) of this method.
351                    @return copy of the CIMMethod object.
352                */

353 kumpf 1.20     CIMMethod clone() const;

354 mike  1.17 
355            private:
356            

357 kumpf 1.20     CIMMethod(CIMMethodRep* rep);

358 mike  1.17 
359                PEGASUS_EXPLICIT CIMMethod(const CIMConstMethod& x);
360            

361 kumpf 1.20     void _checkRep() const;

362 mike  1.17 
363                CIMMethodRep* _rep;
364                friend class CIMConstMethod;

365 kumpf 1.28     friend class Resolver;

366 kumpf 1.22     friend class XmlWriter;

367 kumpf 1.23     friend class MofWriter;

368 mike  1.17 };
369            

370 karl  1.38 /** The CIMConstMethod class is used to represent CIM methods in the
371                same manner as the CIMMethod class except that the const attribute
372                is applied to the objects created. This class includes equivalents
373                to the methods from CIMMethod that are usable in a const object including
374                constructors, (i.e. getter methods) and the destructor.
375                The const form of the object is used TBD
376                ATTN: Complete the explanation of why.
377                @see CIMMethod
378            */

379 mike  1.17 class PEGASUS_COMMON_LINKAGE CIMConstMethod
380            {
381            public:
382            

383 karl  1.38     /**  Creates a new default CIMConstMethod object.
384                    @see  CIMMethod()
385                */

386 kumpf 1.20     CIMConstMethod();

387 mike  1.17 

388 karl  1.38     /// @see CIMMethod()

389 kumpf 1.20     CIMConstMethod(const CIMConstMethod& x);

390 mike  1.17 

391 karl  1.38     /** Creates a new CIMConstMethod object from an
392                    existing CIMMethod object.  Creates a pointer
393                    to the existing representation.
394                    @return CIMConstMethod object reference.
395                    @see CIMMethod()
396                */

397 kumpf 1.20     CIMConstMethod(const CIMMethod& x);

398 mike  1.17 

399 kumpf 1.36     ///

400 mike  1.17     CIMConstMethod(

401 karl  1.38     const CIMName& name,
402                CIMType type,
403                const CIMName& classOrigin = CIMName(),
404                Boolean propagated = false);

405 kumpf 1.20 

406 karl  1.38     /// destructor.

407 kumpf 1.20     ~CIMConstMethod();
408            

409 karl  1.38     /// assignment operator. 

410 kumpf 1.20     CIMConstMethod& operator=(const CIMConstMethod& x);
411            

412 karl  1.38     /// assignment operator.

413 kumpf 1.20     CIMConstMethod& operator=(const CIMMethod& x);
414            

415 karl  1.38     /** gets CIMMethod name. Operation is the same as
416                    CIMMethod getName().
417                    @see CIMMethod
418                    
419                */

420 kumpf 1.30     const CIMName& getName() const;

421 kumpf 1.20 

422 karl  1.38     /** gets CIMMethod CIMType. Functions the same as
423                    CIMMethod getType();
424                    @see CIMMethod
425                    
426                */

427 kumpf 1.20     CIMType getType() const;
428            

429 karl  1.38     /**  gets ClassOrigin attribute. Functions the same
430                     as CIMMethod getClassOrigin()
431                     @see CIMMethod
432                    
433                */

434 kumpf 1.30     const CIMName& getClassOrigin() const;

435 kumpf 1.20 

436 karl  1.38     /**  gets Propagated attribute. Functions the same
437                     as CIMMethod getPropagated()
438                     @see CIMMethod
439                */

440 kumpf 1.20     Boolean getPropagated() const;
441            

442 karl  1.38     /** finds qualifier based on name. Functions the
443                    same as the CIMMethod findQualifier() method.
444                    
445                    @see CIMMethod
446                */

447 kumpf 1.30     Uint32 findQualifier(const CIMName& name) const;

448 kumpf 1.20 

449 karl  1.38     /** gets qualifier based on index. Functions the
450                    same as the CIMMethod getQualifier() method.
451                    @see CIMMethod
452                */

453 kumpf 1.35     CIMConstQualifier getQualifier(Uint32 index) const;

454 kumpf 1.20 

455 karl  1.38     /** gets qualifier count based on name. Functions the
456                    same as the CIMMethod getQualifierCount() method.
457                    @see CIMMethod
458                */

459 kumpf 1.20     Uint32 getQualifierCount() const;
460            

461 karl  1.38     /** finds method parameter based on name. Functions the
462                    same as the CIMMethod findParameter() method.
463                    @see CIMMethod
464                */

465 kumpf 1.30     Uint32 findParameter(const CIMName& name) const;

466 kumpf 1.20 

467 karl  1.38     /** gets method parameter based on index. Functions the
468                    same as the CIMMethod getParameter() method.
469                    @see CIMMethod
470                */

471 kumpf 1.35     CIMConstParameter getParameter(Uint32 index) const;

472 kumpf 1.20 

473 karl  1.38     /** finds method parameter count based on name. Functions the
474                    same as the CIMMethod getParameterCount() method.
475                    @see CIMMethod
476                */

477 kumpf 1.20     Uint32 getParameterCount() const;
478            

479 karl  1.38     /** Determines if CIMMethod is unitinitialized. Functions the
480                    same as corresponding funtion in CIMMethod class.
481                    @see CIMMethod
482                */

483 kumpf 1.32     Boolean isUninitialized() const;

484 kumpf 1.20 

485 karl  1.38     /** Determines if CIMMethod is identical to object define in parameter.
486                    Functions the same as corresponding funtion in CIMMethod class.
487                    @see CIMMethod
488                */

489 kumpf 1.20     Boolean identical(const CIMConstMethod& x) const;
490            

491 karl  1.38     /** clones a CIMMethod object by making a deep copy. Functions the
492                    same as corresponding funtion in CIMMethod class.
493                    @see CIMMethod
494                */

495 kumpf 1.20     CIMMethod clone() const;

496 mike  1.17 
497            private:
498            

499 kumpf 1.20     void _checkRep() const;

500 mike  1.17 
501                CIMMethodRep* _rep;
502            
503                friend class CIMMethod;
504                friend class CIMMethodRep;

505 kumpf 1.22     friend class XmlWriter;

506 kumpf 1.23     friend class MofWriter;

507 mike  1.17 };
508            
509            #define PEGASUS_ARRAY_T CIMMethod

510 kumpf 1.24 # include <Pegasus/Common/ArrayInter.h>

511 mike  1.17 #undef PEGASUS_ARRAY_T
512            
513            PEGASUS_NAMESPACE_END
514            
515            #endif /* Pegasus_Method_h */