2 Overview
2.1 Interfaces
The interfaces of the Mnesia Session application are defined in IDL (Interface Definition Language). The IDL module
mnesia
consists of two interfaces:
- The connector (and possibly corba_connector) is started statically when starting the
Mnesia Session
application.
- The session (and corba_session) which is started dynamically at the request of a client.
When a
Mnesia Session
client needs to access the Mnesia DBMS it locates aconnector
on some Erlang node and starts asession
there by applying theconnect
function on the connector.Once the client has started a
session
it may use it to perform various Mnesia functions. The functions are performed locally on the Erlang node where thesession
resides. Most of Mnesia's functions have location transparent behavior, but some of them (e.g.start/0
) don't.The
Mnesia Session
interfaces makes it possible to access the administration and dirty functionality ofMnesia
. To use transactions and/orMnemosyne
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 oferlang::term
, which can sometimes be troublesome when using foreign languages, for bothmnesia_session
and themnesia_corba_session
.See the IDL specification for functions which are available. The specification resembles the
Mnesia
API as much as possible. Please, read theMnesia
documentation set regarding the semantics used in the interface.All the functions in the session ( and corba_session) API return
Status
which indicates if the operation was successful or not. Most of the functions have an out parameter with a stringreason
describing the error, if one occurs.
The return value
Status
should be checked after each call, and it should be matched against theStatus
enumok
. For some functions, theend_of_table
also means that the operation was successful.2.2 Communication protocols
The IDL specification of
Mnesia Session
has two alternatives when compiling. These can be found in themnesia_session/include
directory:
- mnesia_session.idl
- mnesia_corba_session.idl
The
mnesia_session.idl
file must be compiled withIC
(OTP's own IDL compiler). The generated stub files use the proprietary distribution protocol of Erlang (erl_interface) to carry out the communication between clients and servers of connectors and sessions. On the server sideMnesia Session
is implemented in Erlang usingMnesia
's public API. On the client side Erlang or C may be used.The
mnesia_corba_session.idl
file may be compiled with anyCorba
compliantIDL
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 sideMnesia Session
is implemented in Erlang usingMnesia
's public API. On the client side a wide range of programming languages are available: Java, Smalltalk, C++, Erlang etc.2.3 Sessions
When the
Mnesia Session
application is started, an Erlang process with the registered name mnesia_connector is created. The following example illustrates how asession
is started:% 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). okNote: In the example given, both the client and server reside (in Erlang) on the same node.
See the
Orber
andIC
documentation about the language mapping between Erlang, C and IDL.2.4 Corba Sessions
If the
Mnesia Session
application has been started with the configuration parameterenable_corba
set totrue
, 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 acorba_session
can be started:% 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).Note: In the example given, both the client and server reside (in Erlang) on the same node.
More information about
Corba
conventions and usage can be found in theOrber
andIC
documentation.Since Orber uses Mnesia internally, some of the functions in the Mnesia API are not available via IIOP. Examples of such functions are:
- start;
- stop;
- create_schema; and,
- delete_schema.
See the IDL specification for the exact specification.
Some other functions are not supported due to the problem of representing void objects of unknown types. The
dirty_[index_]match_object
functionality has been replaced with the simpler functiondirty_match_all
which returns all records in a table.2.5 User defined interfaces
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 inOrber
's InterFace Repository (IFR). The records are mapped to the typeany
inCorba
.We recommend that all records are defined as IDL structures. This also applies when the
erl_interface
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.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 theMnesia Session
interface.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.