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

Last change on this file since 346 was 281, checked in by cinc, 19 years ago

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