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

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

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