1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
<TITLE>Overview</TITLE>
<SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
ALINK="#FF0000">
<CENTER>
<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif"></A>
</CENTER>
<A NAME="2"><!-- Empty --></A>
<H2>2 Overview</H2>
<A NAME="2.1"><!-- Empty --></A>
<H3>2.1 Interfaces</H3>
<P>The interfaces of the <STRONG>Mnesia_Session</STRONG> application are
defined in IDL (Interface Definition Language). The IDL module
<CODE>mnesia</CODE> consists of two interfaces:
<P>
<UL>
<LI>
The <STRONG>connector</STRONG> (and possibly corba_connector)
is started statically when starting the Mnesia_Session
application.<BR>
</LI>
<LI>
The <STRONG>session</STRONG> (and corba_session) which is
started dynamically at the request of a
client.<BR>
</LI>
</UL>
<P>When a Mnesia_Session client needs to access the Mnesia
DBMS it locates a <CODE>connector</CODE> on some Erlang node and
starts a <CODE>session</CODE> there by applying the <CODE>connect</CODE>
function on the connector.
<P>Once the client has started a <CODE>session</CODE> it may use it to
perform various Mnesia functions. The functions are performed
locally on the Erlang node where the <CODE>session</CODE>
resides. Most of Mnesia's functions have location transparent
behavior, but some of them (e.g. <CODE>start/0</CODE>) do not.
<P>The Mnesia_Session interfaces makes it possible to
access the administration and dirty functionality of
Mnesia. To use transactions and/or Mnemosyne
queries it is up to the user to define the needed interface in
IDL. Implementing a user specified interface allows an
opportunity to skip the general handling of <CODE>erlang::term</CODE>,
which can sometimes be troublesome when using foreign languages,
for both <CODE>mnesia_session</CODE> and the <CODE>mnesia_corba_session</CODE>.
<P>See the <A HREF="MnesiaSessionIdl.html">IDL specification</A>
for functions which are available. The specification
resembles the Mnesia API as much as possible. Please,
read the Mnesia documentation set regarding the semantics used in
the interface.
<P> All the functions in the session ( and corba_session) API return
<CODE>Status</CODE> which indicates if the operation was successful or
not. Most of the functions have an out parameter with a
string <CODE>reason</CODE> describing the error, if one occurs.
<P>
<TABLE CELLPADDING=4>
<TR>
<TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
<TD>
<P> The return value <CODE>Status</CODE> should be checked after each
call, and it should be matched against the <CODE>Status</CODE> enum
<CODE>ok</CODE>. For some functions, the <CODE>end_of_table</CODE> also
means that the operation was successful.
</TD>
</TR>
</TABLE>
<A NAME="2.2"><!-- Empty --></A>
<H3>2.2 Communication protocols</H3>
<P>The IDL specification of Mnesia_Session has two
alternatives when compiling. These can be found in the
<CODE>mnesia_session/include</CODE> directory:
<P>
<UL>
<LI>
mnesia_session.idl<BR>
</LI>
<LI>
mnesia_corba_session.idl<BR>
</LI>
</UL>
<P>The <CODE>mnesia_session.idl</CODE> file must be compiled with
<CODE>IC</CODE> (OTP's own IDL compiler). The generated stub files
use the proprietary distribution protocol of Erlang
(erl_interface/jinterface) to carry out the communication between clients
and servers of connectors and sessions. On the server side
Mnesia_Session is implemented in Erlang using
<CODE>Mnesia</CODE>'s public API. On the client side Erlang, Java or C may
be used.
<P>The <CODE>mnesia_corba_session.idl</CODE> file may be compiled with
any Corba compliant IDL compiler (e.g. Orbix,
JacORB, TelORB, IC, ...) . The generated stub files uses IIOP (a
protocol standardized by OMG) to carry out the communication
between clients and servers of connectors and sessions. On the
server side Mnesia_Session is implemented in Erlang using
Mnesia's public API. On the client side a wide range of
programming languages are available: Java, Smalltalk, C++,
Erlang etc.
<A NAME="2.3"><!-- Empty --></A>
<H3>2.3 Sessions</H3>
<P>When the Mnesia_Session application is started, an
Erlang process with the registered name
<STRONG>mnesia_connector</STRONG> is created. The following example
illustrates how a <CODE>session</CODE> is started:
<PRE>
% erl
1> application:start(mnesia_session).
ok
2> Name = mnesia_connector,
mnesia_connector
3> Connector = erlang:whereis(Name).
<0.34.0>
4> Session = mnesia_connector:connect(Connector).
<0.35.0>
5> ok = mnesia_connector:disconnect(Connector, Session).
ok
</PRE>
<P>
<TABLE CELLPADDING=4>
<TR>
<TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
<TD>
<P>In the example given, both the client and server reside (in Erlang) on the
same node.
</TD>
</TR>
</TABLE>
<P>See the Orber and IC documentation about
the language mapping between Erlang, Java, C and IDL.
<A NAME="2.4"><!-- Empty --></A>
<H3>2.4 CORBA Sessions</H3>
<P>If the Mnesia_Session application has been started with
the configuration parameter <CODE>enable_corba</CODE> set to
<CODE>true</CODE>, a mnesia_corba_connector object is also created (in
addition to the mandatory mnesia_connector process), and
registered in Orber. The following simplified example illustrates how
a <CODE>corba_session</CODE> can be started:
<PRE>
% erl -mnesia_session enable_corba true
1> application:start(mnesia_session).
2> NS = corba:resolve_initial_references("NameService").
3> NC = lname_component:set_id(lname_component:create(),
"mnesia_corba_connector").
4> Name = lname:insert_component(lname:create(), 1, NC).
5> Connector = 'CosNaming_NamingContext':resolve(NS, Name).
6> Session = mnesia_corba_connector:connect(Connector).
7> mnesia_corba_connector:disconnect(Connector, Session).
</PRE>
<P>
<TABLE CELLPADDING=4>
<TR>
<TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
<TD>
<P> In the example given, both the client and server reside
(in Erlang) on the
same node.
</TD>
</TR>
</TABLE>
<P>More information about CORBA conventions and usage can be found in the
Orber and IC documentation.
<P>Since Orber uses Mnesia internally, some of the functions in
the Mnesia API are not available via IIOP. Examples of such
functions are:
<P>
<UL>
<LI>
start;
<BR>
</LI>
<LI>
stop;
<BR>
</LI>
<LI>
create_schema; and,
<BR>
</LI>
<LI>
delete_schema. <BR>
</LI>
</UL>
<P>See the <A HREF="MnesiaSessionIdl.html">IDL
specification</A> for the exact specification.
<P>Some other functions are not supported due to the problem of
representing void objects of unknown types. The
<CODE>dirty_[index_]match_object</CODE> functionality has been
replaced with the simpler function <CODE>dirty_match_all</CODE> which
returns all records in a table.
<A NAME="2.5"><!-- Empty --></A>
<H3>2.5 Erlang, C and Java Sessions</H3>
<P> These sessions are faster and more flexible variants than
the CORBA session. The protocol implemented by the generated stubs
is Erlang native external communication protocol, there is no ORB and IIOP engaged.
Due to these facts the clients will run 10 to 20 times faster
than in CORBA session case, depending on the amount of data stored
and the mnesia record seeking times.
<A NAME="2.6"><!-- Empty --></A>
<H3>2.6 User-defined Interfaces</H3>
<P>To be able to send records over the IIOP protocol, the records
must be defined as structures in an IDL specification, and
compiled with IC in order to enable registering of the
types in Orber's InterFace Repository (IFR). The records
are mapped to the type <CODE>any</CODE> in Corba.
<P>We recommend that all records are defined as IDL structures. This
also applies when the <CODE>erl_interface</CODE> protocol is used (even though it may
work without it). By including the header files produced in the
code generation, several useful type definitions are made
available for the application.
<P>The generic dirty access functions in the API of Mnesia_Session
is merely included for the convenience of
application developers and it may be tempting to organize the
application code around these functions. The application
interface between its clients and servers, should however be
carefully designed according to the needs of the application,
regardless of the Mnesia_Session interface.
<P>Instead of sending records back and forth between the server and client
nodes as in the generic get-/put-oriented interface of Mnesia_Session,
it may (in many cases) be a better application
design, to perform the application logic on the same (Erlang)
node as the residing data. Besides the obvious performance
advantage, it makes the applications more independent of future
changes in the data model of the application.
<CENTER>
<HR>
<SMALL>
Copyright © 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>
|
