source: trunk/nom/idl/nomobj.idl@ 357

Last change on this file since 357 was 357, checked in by cinc, 17 years ago

Renamed nomGetClassName() to nomQueryClassName()
File size: 8.5 KB
Line 
1/* ***** BEGIN LICENSE BLOCK *****
2* Version: CDDL 1.0/LGPL 2.1
3*
4* The contents of this file are subject to the COMMON DEVELOPMENT AND
5* DISTRIBUTION LICENSE (CDDL) Version 1.0 (the "License"); you may not use
6* this file except in compliance with the License. You may obtain a copy of
7* the License at http://www.sun.com/cddl/
8*
9* Software distributed under the License is distributed on an "AS IS" basis,
10* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
11* for the specific language governing rights and limitations under the
12* License.
13*
14* The Original Code is "NOM" Netlabs Object Model
15*
16* The Initial Developer of the Original Code is
17* netlabs.org: Chris Wohlgemuth <cinc-ml@netlabs.org>.
18* Portions created by the Initial Developer are Copyright (C) 2005-2007
19* the Initial Developer. All Rights Reserved.
20*
21* Contributor(s):
22*
23* Alternatively, the contents of this file may be used under the terms of
24* the GNU Lesser General Public License Version 2.1 (the "LGPL"), in which
25* case the provisions of the LGPL are applicable instead of those above. If
26* you wish to allow use of your version of this file only under the terms of
27* the LGPL, and not to allow others to use your version of this file under
28* the terms of the CDDL, indicate your decision by deleting the provisions
29* above and replace them with the notice and other provisions required by the
30* LGPL. If you do not delete the provisions above, a recipient may use your
31* version of this file under the terms of any one of the CDDL or the LGPL.
32*
33* ***** END LICENSE BLOCK ***** */
34/** \file nomobj.idl
35
36Class definition file for the NOM class NOMObject.
37*/
38
39#ifndef NOMOBJ_IDL_INCLUDED
40#define NOMOBJ_IDL_INCLUDED
41
42#include "nombase.idl"
43
44//NOMCLASSNAME(NOMObject);
45
46interface NOMArray;
47
48/** \interface NOMObject
49
50 This is the root class of NOM. It provides methods common to all objects.
51
52 \remarks NOMObject can't be replaced.
53
54 */
55interface NOMObject
56{
57#ifdef __NOM_IDL_COMPILER__
58 filestem=nomobj;
59#endif
60
61 NOMCLASSVERSION(1, 0 );
62
63 /**
64 This method is intended to be overriden by classes which need some initialization.
65
66 \remarks This method is called by the system during object creation. Don't call it
67 from your code or unexpected things may happen.
68
69 \par How to override:
70 The parent class must always be called first when overriden.
71
72 \sa impl_NOMObject_nomInit(), nomUnInit()
73 */
74 void nomInit();
75
76 /**
77 This method is intended to be overriden by classes which need some uninitialization.
78 Note that when overriding the method the garbage collector will add the object
79 to the list of objects with a finalizer. The finalizer will be run when the object is
80 collected and calls nomUnInit() to give the object a chance for cleanup.
81
82 \remarks It's not necessary to free memory in nomUnInit(). This is the job of the garbage collector.
83 Only system resources like file handles etc. must be explicitely freed.
84 This method is called by the system during object deletion. Don't call it
85 from your code or unexpected things may happen.
86
87 \par How to override:
88 The parent method must be called after doing the own processing.
89
90 \sa impl_NOMObject_nomUnInit(), nomInit();
91 */
92 void nomUnInit();
93
94 /**
95 Return the size of the object. That is sizeof(mTab*)+sizeof(all instance vars)
96
97 \par How to override:
98 This method is usually not overriden.
99
100 \sa impl_NOMObject_nomGetSize()
101 */
102 long nomGetSize();
103
104 /**
105 Delete an object. This method is useful if you have to control the point in time when
106 an object is actually destroyed. Normally the garbage collector destroys any object when
107 no longer in use but there is no way to control when this happens.
108
109 \remarks This method calls nomUnInit() to give the object a chance of freeing system resources.
110 Afterwards the memory occupied by the object is given back to the system and the
111 object is not accessible anymore.
112
113 \par HowTo override:
114 This method is usually not overriden. If you need some own processing during object
115 destruction override nomUnInit().
116
117 \sa impl_NOMObject_delete(), nomUnInit()
118 */
119 void delete();
120
121 /**
122 This method returns a pointer to the class object of this object.
123
124 \par How to override:
125 This method is usually not overriden.
126
127 \return Pointer to the class object
128
129 \sa impl_NOMObject_nomQueryClass()
130 */
131 PNOMClass nomQueryClass();
132
133 /**
134 Create a new class of the kind the caller is. This method ensures that subclasses
135 are properly handled without the need to override this method in every subclass.
136
137 When deriving from classes new methods are added to a class but the already present ones are
138 usually not changed. If one of these classes creates a new object of the class itself
139 is an instance of unexpected things may happen. Consider the
140 following class hierarchy:
141
142 \code
143 NOMObject->NOMString->NOMPath
144 \endcode
145
146 When a method introduced by \e NOMString tries to create a new \e NOMString object it may
147 use the \e NOMStringNew() macro to do so. Problems arise if the method is called from
148 within a \e NOMPath object. The caller probably doesn't want a \e NOMString but rather
149 a \e NOMPath object. So instead of having to override the method using the creation macro
150 which may mean to recreate the whole method implementation the macro should be replaced
151 by a call to new().
152
153 This method will get the class object of nomSelf and call nomNew() on it creating
154 a new object which has exactly the same class hierarchy of nomSelf.
155
156 \remarks Because a new object is created the whole object creation sequence will take
157 place which means a call to nomInit() will be made by the system.
158
159 \par How to override:
160 This method is usually not overriden.
161
162 \return Pointer to a new object of the same kind as nomSelf. Note that this won't
163 create an exact copy but a completely new objecct.
164
165 \sa impl_NOMObject_new()
166 */
167 PNOMObject new();
168
169 /**
170 This method checks if the object is an instance of the given class or some subclass. Using
171 this method one can make sure some feature is available if the introducing class is known.
172 Every subclass of a given class also supports the features of the introducing class.
173
174 \remarks This method checks the validity of \e nomClass using nomIsObj() and returns FALSE
175 in case it's not an object.
176
177 \param nomClass Pointer to a class object.
178
179 \returns TRUE if the object is an instance of the given class or one of its
180 subclasses.
181
182 \sa nomIsInstanceOf(), nomIsANoClsCheck()
183 */
184 boolean nomIsA(in PNOMClass nomClass);
185
186 /**
187 This method checks if the object is an instance of exactly the given class.
188
189
190 \remarks This method checks the validity of \e nomClass using nomIsObj() and returns FALSE
191 in case it's not an object.
192
193 \param nomClass Pointer to a class object.
194
195 \returns TRUE if the object is an instance of exactly the given class.
196
197 \sa nomIsA(), nomIsANoClsCheck()
198 */
199 boolean nomIsInstanceOf(in PNOMClass nomClass);
200
201 /**
202 This method returns the name of the class this object is an instance of.
203
204 \par How to override:
205 This method is usually not overriden.
206
207 \returns A null terminated C string. Note that this is not a copy. The string
208 is valid as long as the class object exists (not the instance).
209
210 \sa impl_NOMClass_nomQueryClassName()
211 */
212 string nomQueryClassName();
213
214 /**
215 This method checks if the object is an instance of the given class or some subclass. Using
216 this method one can make sure some feature is available if the introducing class is known.
217 Every subclass of a given class also supports the features of the introducing class.
218
219 \remarks This method does \e not check the validity of \e nomClass using nomIsObj(). So
220 make sure to have checked it beforehand. You may want to use nomIsA() instead;
221
222 \param nomClass Pointer to a class object.
223
224 \returns TRUE if the object is an instance of the given class or one of its
225 subclasses.
226
227 \sa nomIsInstanceOf(), nomIsA()
228 */
229 boolean nomIsANoClsCheck(in PNOMClass nomClass);
230
231 NOMObject* nomGetMethodList(in boolean bIncludingParents);
232};
233
234#endif /* NOMOBJ_IDL_INCLUDED */
235
236
Note: See TracBrowser for help on using the repository browser.