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

Last change on this file since 257 was 255, checked in by cinc, 19 years ago

Parameter checking for object pointer working.
File size: 8.3 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
46/** \interface NOMObject
47
48 This is the root class of NOM. It provides methods common to all objects.
49
50 \remarks NOMObject can't be replaced.
51
52 */
53interface NOMObject
54{
55
56 NOMCLASSVERSION(1, 0 );
57
58 /**
59 This method is intended to be overriden by classes which need some initialization.
60
61 \remarks This method is called by the system during object creation. Don't call it
62 from your code or unexpected things may happen.
63
64 \par How to override:
65 The parent class must always be called first when overriden.
66
67 \sa impl_NOMObject_nomInit(), nomUnInit()
68 */
69 void nomInit();
70
71 /**
72 This method is intended to be overriden by classes which need some uninitialization.
73 Note that when overriding the method the garbage collector will add the object
74 to the list of objects with a finalizer. The finalizer will be run when the object is
75 collected and calls nomUnInit() to give the object a chance for cleanup.
76
77 \remarks It's not necessary to free memory in nomUnInit(). This is the job of the garbage collector.
78 Only system resources like file handles etc. must be explicitely freed.
79 This method is called by the system during object deletion. Don't call it
80 from your code or unexpected things may happen.
81
82 \par How to override:
83 The parent method must be called after doing the own processing.
84
85 \sa impl_NOMObject_nomUnInit(), nomInit();
86 */
87 void nomUnInit();
88
89 /**
90 Return the size of the object. That is sizeof(mTab*)+sizeof(all instance vars)
91
92 \par How to override:
93 This method is usually not overriden.
94
95 \sa impl_NOMObject_nomGetSize()
96 */
97 long nomGetSize();
98
99 /**
100 Delete an object. This method is useful if you have to control the point in time when
101 an object is actually destroyed. Normally the garbage collector destroys any object when
102 no longer in use but there is no way to control when this happens.
103
104 \remarks This method calls nomUnInit() to give the object a chance of freeing system resources.
105 Afterwards the memory occupied by the object is given back to the system and the
106 object is not accessible anymore.
107
108 \par HowTo override:
109 This method is usually not overriden. If you need some own processing during object
110 destruction override nomUnInit().
111
112 \sa impl_NOMObject_delete(), nomUnInit()
113 */
114 void delete();
115
116 /**
117 This method returns a pointer to the class object of this object.
118
119 \par How to override:
120 This method is usually not overriden.
121
122 \return Pointer to the class object
123
124 \sa impl_NOMObject_nomGetClass()
125 */
126 PNOMClass nomGetClass();
127
128 /**
129 Create a new class of the kind the caller is. This method ensures that subclasses
130 are properly handled without the need to override this method in every subclass.
131
132 When deriving from classes new methods are added to a class but the already present ones are
133 usually not changed. If one of these classes creates a new object of the class itself
134 is an instance of unexpected things may happen. Consider the
135 following class hierarchy:
136
137 \code
138 NOMObject->NOMString->NOMPath
139 \endcode
140
141 When a method introduced by \e NOMString tries to create a new \e NOMString object it may
142 use the \e NOMStringNew() macro to do so. Problems arise if the method is called from
143 within a \e NOMPath object. The caller probably doesn't want a \e NOMString but rather
144 a \e NOMPath object. So instead of having to override the method using the creation macro
145 which may mean to recreate the whole method implementation the macro should be replaced
146 by a call to new().
147
148 This method will get the class object of nomSelf and call nomNew() on it creating
149 a new object which has exactly the same class hierarchy of nomSelf.
150
151 \remarks Because a new object is created the whole object creation sequence will take
152 place which means a call to nomInit() will be made by the system.
153
154 \par How to override:
155 This method is usually not overriden.
156
157 \return Pointer to a new object of the same kind as nomSelf. Note that this won't
158 create an exact copy but a completely new objecct.
159
160 \sa impl_NOMObject_new()
161 */
162 PNOMObject new();
163
164 /**
165 This method checks if the object is an instance of the given class or some subclass. Using
166 this method one can make sure some feature is available if the introducing class is known.
167 Every subclass of a given class also supports the features of the introducing class.
168
169 \remarks This method checks the validity of \e nomClass using nomIsObj() and returns FALSE
170 in case it's not an object.
171
172 \param nomClass Pointer to a class object.
173
174 \returns TRUE if the object is an instance of the given class or one of its
175 subclasses.
176
177 \sa nomIsInstanceOf(), nomIsANoClsCheck()
178 */
179 boolean nomIsA(in PNOMClass nomClass);
180
181 /**
182 This method checks if the object is an instance of exactly the given class.
183
184
185 \remarks This method checks the validity of \e nomClass using nomIsObj() and returns FALSE
186 in case it's not an object.
187
188 \param nomClass Pointer to a class object.
189
190 \returns TRUE if the object is an instance of exactly the given class.
191
192 \sa nomIsA(), nomIsANoClsCheck()
193 */
194 boolean nomIsInstanceOf(in PNOMClass nomClass);
195 /**
196 This method returns the name of the class this object is an instance of.
197
198 \par How to override:
199 This method is usually not overriden.
200
201 \returns A null terminated C string. Note that this is not a copy. The string
202 is valid as long as the class object exists (not the instance).
203
204 \sa impl_NOMClass_nomGetClassName()
205 */
206 string nomGetClassName();
207
208 /**
209 This method checks if the object is an instance of the given class or some subclass. Using
210 this method one can make sure some feature is available if the introducing class is known.
211 Every subclass of a given class also supports the features of the introducing class.
212
213 \remarks This method does \e not check the validity of \e nomClass using nomIsObj(). So
214 make sure to have checked it beforehand. You may want to use nomIsA() instead;
215
216 \param nomClass Pointer to a class object.
217
218 \returns TRUE if the object is an instance of the given class or one of its
219 subclasses.
220
221 \sa nomIsInstanceOf(), nomIsA()
222 */
223 boolean nomIsANoClsCheck(in PNOMClass nomClass);
224
225};
226
227#endif /* NOMOBJ_IDL_INCLUDED */
228
229
Note: See TracBrowser for help on using the repository browser.