1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
\r
4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
\r
5 <meta name="GENERATOR" content="Mozilla/4.73 [en] (WinNT; I) [Netscape]">
\r
6 <title>Main Page</title>
\r
7 <link href="doxygen.css" rel="stylesheet" type="text/css">
\r
11 <center><table WIDTH="96%" >
\r
13 <td><a href="http://www.opencascade.com"><img SRC="sources/logocorp.gif" BORDER=0 height=46 width=122></a></td>
\r
16 <div align=right><a href="http://www.opencascade.org/SALOME/"><img SRC="sources/application.gif" BORDER=0 height=46 width=108></a></div>
\r
20 <a NAME="page1"></a>
\r
22 Mapping of IDL definitions to Python language.</h2>
\r
23 <a NAME="Intro"></a>
\r
26 SALOME is a distributed client/server application using the Common
\r
27 Object Request Broker Architecture (CORBA). CORBA architecture uses the
\r
28 Interface Definition Language (IDL), which specifies interfaces between
\r
29 CORBA objects. So with help of IDL CORBA's language independence is ensured
\r
30 . Because interfaces described in IDL can be mapped to the most of currently
\r
31 used programming languages, CORBA applications and components are thus
\r
32 independent of the language(s) used to implement them. In other words,
\r
33 a client written in C++ can communicate with a server written in Java,
\r
34 which in turn can communicate with another server written in COBOL, and
\r
36 <p>One important thing to remember about IDL is that it is not an implementation
\r
37 language. That is, applications can't be written in IDL. The sole purpose
\r
38 of IDL is to define interfaces; providing implementations for these interfaces
\r
39 is performed using some other language.
\r
40 <p>This page contains an abridged reference manual for mapping of IDL definitions
\r
41 to Python language. It will be useful for Python programmers who are not
\r
42 familiar with IDL language. All examples are taken from SALOME source
\r
43 files. The complete version of Python Language Mapping Specification can
\r
44 be found <a href="http://www.omg.org" target="top">here.</a>
\r
46 <p><a NAME="contents"></a><b>CONTENTS:</b>
\r
49 <a href="#subsection1">Using Scoped Names</a></li>
\r
52 <a href="#subsection2">Mapping for Template and Array Types</a></li>
\r
55 <a href="#subsection3">Mapping for Objects and Operations</a></li>
\r
58 <a href="#subsection4">Narrowing Object References</a></li>
\r
61 <a href="#subsection5">Mapping for Exceptions</a></li>
\r
64 <a href="#subsection6">Mapping for Enumeration Types</a></li>
\r
67 <a href="#subsection7">Mapping for Structured Types</a></li>
\r
70 <a NAME="subsection1"></a>
\r
72 Using Scoped Names</h3>
\r
73 Python implements a module concept that is similar to the IDL scoping mechanisms,
\r
74 except that it does not allow for nested modules. In addition, Python requires
\r
75 each object to be implemented in a module; globally visible objects are
\r
77 <p>Because of these constraints, scoped names are translated into Python
\r
78 using the following rules:
\r
79 <p>
\95 An IDL module mapped into a Python module. Modules containing modules
\r
80 are mapped to packages (i.e., directories with an <b>__init__</b> module
\r
81 containing all definitions excluding the nested modules). An implementation
\r
82 can chose to map toplevel definitions (including the module CORBA) to modules
\r
83 in an implementationdefined package, to allow concurrent installations
\r
84 of different CORBA runtime libraries. In that case, the implementation
\r
85 must provide additional modules so that toplevel modules can be used without
\r
86 importing them from a package.
\r
87 <p>
\95 For all other scopes, a Python class is introduced that contains all
\r
88 the definitions inside this scope.
\r
89 <p>
\95 Other global definitions (except modules) appear in a module whose
\r
90 name is implementation dependent. Implementations are encouraged to use
\r
91 the name of the IDL file when defining the name of that module.
\r
93 <div class="fragment">
\r
94 <pre>module SALOMEDS {
\r
95 interface StudyManager {
\r
96 void Close(in Study aStudy);
\r
100 would introduce a module SALOMEDS.py, which contains the following definitions:
\r
101 <div class="fragment">
\r
102 <pre># module SALOMEDS.py
\r
103 class StudyManager:
\r
104 def _Close(self,aStudy):
\r
105 pass #interfaces are discussed later</pre>
\r
107 To avoid conflicts, IDL names that are also Python identifiers are prefixed
\r
108 with an underscore (
\91_
\92).
\r
109 <p><b><i><a href="#contents">Back to the contents</a></i></b><b><i></i></b>
\r
110 <p><a NAME="subsection2"></a>
\r
112 Mapping for Template and Array Types</h3>
\r
113 Both the bounded and the unbounded string type of IDL are mapped to the
\r
114 Python string type. Wide strings are represented by an implementation-defined
\r
115 type with the following properties:
\r
116 <p>
\95 For the wide string X and the integer n, X[n] returns the nth character,
\r
117 which is a wide string of length 1.
\r
118 <p>
\95 len(X) returns the number of characters of wide string X.
\r
119 <p>
\95 CORBA.wstr(c) returns a wide character with the code point c in an
\r
120 implementation-defined encoding.
\r
121 <p>
\95 X+Y returns the concatenation of wide strings X and Y.
\r
122 <p>
\95 CORBA.word(CORBA.wstr(c)) == c
\r
123 <p>The sequence template is mapped to sequence objects (e.g., tuples or
\r
124 lists). Applications should not assume that values of a sequence type are
\r
125 mutable. Sequences and arrays of octets and characters are mapped to the
\r
126 string type for efficiency reasons.
\r
127 <p>For example, given the IDL definitions
\r
128 <div class="fragment">
\r
129 <pre>module SALOMEDS {
\r
130 typedef sequence <string> StringSeq;
\r
132 interface AttributeTableOfInteger : GenericAttribute {
\r
134 void SetRowTitles(in StringSeq theTitles) raises(IncorrectArgumentLength);
\r
138 a client could invoke the operation
\r
139 <div class="fragment">
\r
140 <pre>print My_AttributeTableOfInteger.SetRowTitles(["X","F"])</pre>
\r
142 Array types are mapped like sequence templates. The application in this
\r
143 example also expects an IncorrectArgumentLength exception if it passes
\r
144 sequences that violate the bounds constraint or arrays of wrong size.
\r
145 <p>Another example with arrays. The following IDL definition
\r
146 <div class="fragment">
\r
147 <pre>module SALOMEDS {
\r
148 typedef sequence<GenericAttribute> ListOfAttributes;
\r
149 interface SObject {
\r
150 ListOfAttributes GetAllAttributes();
\r
155 <div class="fragment">
\r
156 <pre>import SALOMEDS
\r
160 attributes = My_SObject.GetAllAttributes()
\r
162 length = len(attributes)
\r
164 print "Attributes number = ", length
\r
165 print attributes</pre>
\r
167 <b><i><a href="#contents">Back to the contents</a></i></b>
\r
168 <p><a NAME="subsection3"></a>
\r
170 Mapping for Objects and Operations</h3>
\r
171 A CORBA object reference is represented as a Python object at run-time.
\r
172 This object provides all the operations that are available on the interface
\r
173 of the object. Although this specification does not mandate the use of
\r
174 classes for stub objects, the following discussion uses classes to indicate
\r
176 <p>The nil object is represented by <b>None</b>.
\r
177 <p>If an operation expects parameters of the IDL Object type, any Python
\r
178 object representing an object reference might be passed as actual argument.
\r
179 <p>If an operation expects a parameter of an abstract interface, either
\r
180 an object implementing that interface, or a value supporting this interface
\r
181 may be passed as actual argument. The semantics of abstract values then
\r
182 define whether the argument is passed by value or by reference.
\r
183 <p>Operations of an interface map to methods available on the object references.
\r
184 Parameters with a parameter attribute of <b>in</b> or <b>inout</b> are
\r
185 passed from left to right tothe method, skipping <b>out</b> parameters.
\r
186 The return value of a method depends on the number of <b>out</b> parameters
\r
187 and the return type. If the operation returns a value, this value forms
\r
188 the first <i>result value</i>. All <b>inout</b> or <b>out</b> parameters
\r
189 form consecutive <i>result values</i>. The method result depends then on
\r
190 the number of <i>result values</i>:
\r
191 <p>
\95 If there is no <i>result value</i>, the method returns None.
\r
192 <p>
\95 If there is exactly one <i>result value</i>, it is returned as a single
\r
194 <p>
\95 If there is more than one <i>result value</i>, all of them are packed
\r
195 into a tuple, and this tuple is returned.
\r
196 <p>Assuming the IDL definition
\r
197 <div class="fragment">
\r
198 <pre>module SALOMEDS{
\r
199 interface StudyBuilder{
\r
200 boolean FindAttribute ( in SObject anObject,
\r
201 out GenericAttribute anAttribute,
\r
202 in string aTypeOfAttribute );
\r
206 a client could write
\r
207 <div class="fragment">
\r
208 <pre>from SALOMEDS import StudyBuilder;
\r
209 my_StudyBuilder=...
\r
211 res,A=my_StudyBuilder.FindAttribute(Sobj, "AttributeSequenceOfReal")</pre>
\r
213 In this example <b>A</b> corresponds to the return value <b>anAttribute</b>
\r
214 and <b>res</b> to the <b>boolean</b> return value.
\r
215 <p>If an interface defines an <b>attribute name</b>, for example, the attribute
\r
216 is mapped into an operation <b>_get_name</b>. If the attribute is not <b>readonly</b>,
\r
217 there is an additional operation <b>_set_name</b>.
\r
218 <p>The IDL definition
\r
219 <div class="fragment">
\r
220 <pre>module SALOMEDS{
\r
221 interface Study{
\r
222 attribute string Name;
\r
226 is equal to the following
\r
227 <div class="fragment">
\r
228 <pre>from SALOMEDS import Study
\r
230 Name=My_Study._get_name();
\r
231 Name=My_Study._set_name();</pre>
\r
233 <b><i><a href="#contents">Back to the contents</a></i></b><b><i><a href="#contents"></a></i></b>
\r
234 <p><a NAME="subsection4"></a>
\r
236 Narrowing Object References</h3>
\r
237 Python objects returned from CORBA operations or pseudo-operations (such
\r
238 as string_to_object) might have a dynamic type, which is more specific
\r
239 than the static type as defined in the operation signature.
\r
240 <p>Since there is no efficient and reliable way of automatically creating
\r
241 the most specific type, explicit narrowing is necessary. To narrow an object
\r
242 reference <b>A</b> to an interface class <b>AttributeSequenceOfReal</b>,
\r
243 the client can use the following operation
\r
244 <div class="fragment">
\r
245 <pre>A = A._narrow(SALOMEDS.AttributeSequenceOfReal)</pre>
\r
247 <b><i><a href="#contents">Back to the contents</a></i></b><b><i><a href="#contents"></a></i></b>
\r
248 <p><a NAME="subsection5"></a>
\r
250 Mapping for Exceptions</h3>
\r
251 An IDL exception is translated into a Python class derived from CORBA.UserException.
\r
252 System exceptions are derived from CORBA.SystemException. Both base classes
\r
253 are derived from CORBA.Exception. The parameters of the exception are mapped
\r
254 in the same way as the fields of a struct definition. When raising an exception,
\r
255 a new instance of the class is created; the constructor expects the exception
\r
256 parameters. For example, the definition
\r
257 <div class="fragment">
\r
258 <pre>module SALOMEDS{
\r
259 interface StudyBuilder{
\r
260 exception LockProtection {};
\r
261 void CommitCommand() raises(LockProtection);
\r
265 could be used caught as
\r
266 <div class="fragment">
\r
267 <pre>from SALOMEDS import StudyBuilder;
\r
268 my_StudyBuilder=...
\r
270 my_StudyBuilder.CommitCommand();
\r
271 except StudyBuilder.LockProtection,value:
\r
272 print "Error! Study is locked for modifications"</pre>
\r
275 <p><br><b><i><a href="#contents">Back to the contents</a></i></b><b><i><a href="#contents"></a></i></b>
\r
276 <p><a NAME="subsection6"></a>
\r
278 Mapping for Enumeration Types</h3>
\r
279 An enumeration is mapped into a number of constant objects in the name
\r
280 space where the enumeration is defined. An application may only test for
\r
281 equivalence of two enumeration values, and not assume that they behave
\r
282 like numbers. For example, the definition
\r
283 <div class="fragment">
\r
285 interface PrsObject{
\r
287 enum PrsObjType{ TCURVE, TTABLE, TMESH, TCONTAINER,
\r
288 TSCALARMAP, TISOSURFACE, TDEFORMEDSHAPE,
\r
289 TCUTPLANES, TVECTORS };
\r
293 introduces the objects
\r
294 <div class="fragment">
\r
295 <pre>from VISU import PrsObject
\r
296 VISU.PrsObjType.TCURVE,VISU.PrsObjType.TTABLE,VISU.PrsObjType.TMESH,VISU.PrsObjType.TCONTAINER,
\r
297 VISU.PrsObjType.TSCALARMAP,VISU.PrsObjType.TISOSURFACE,VISU.PrsObjType.TDEFORMEDSHAPE,VISU.PrsObjType.TCUTPLANES,
\r
298 VISU.PrsObjType.TVECTORS</pre>
\r
300 <b><i><a href="#contents">Back to the contents</a></i></b>
\r
301 <p><a NAME="subsection7"></a>
\r
303 Mapping for Structured Types</h3>
\r
304 An IDL struct definition is mapped into a Python class or type. For each
\r
305 field in the struct, there is a corresponding attribute in the class with
\r
306 the same name as the field. The constructor of the class expects the field
\r
307 values, from left to right. For example, the IDL definition
\r
308 <div class="fragment">
\r
309 <pre>struct SDate {
\r
310 short Second;
\r
311 short Minute;
\r
312 short Hour;
\r
313 short Day;
\r
314 short Month;
\r
315 short Year;
\r
316 };</pre>
\r
318 could be used in the Python statements
\r
319 <div class="fragment">
\r
320 <pre>Date=SDate(30, 12, 15, 26, 1, 79)
\r
321 print Date.Second,Date.Minute,Date.Hour,Date.Day,Date.Month,Date.Year</pre>
\r
325 <b><i><a href="#contents">Back to the contents</a></i></b></address>
\r
328 <!-- Generated by Doxygen 1.2.14 -->
\r
