UNIX only
This chapter is a tutorial for how a CORBA application might be created by using SDL. It refers to The CORBA Integration, where for example the mapping rules between IDL and SDL are discussed in great detail.
This UNIX tutorial focuses on an imaginary bank system, and the application is created by applying relevant parts of the SOMT method.
Each section is self contained; it is possible to jump to a specific section and start working from there. As a result, the modifications that are performed on the system during one activity are disregarded in the next activity, where a new system structure is given, providing a possible solution for the previous activity.
This tutorial will present how to use ORCA1, SDT and CORBA in a design process. The purpose is to show how to create an SDL application, or object implementation, that can be used by clients in a CORBA environment. It will also be shown how other servers in the CORBA environment can be accessed from that SDL application.
|
Note: UNIX only Since CORBA support is not available in Windows, this tutorial can only be followed on UNIX! |
The design process has been incorporated with SOMT to create a homogeneous development environment; not all steps of the process are shown in this tutorial, which is specifically aimed at demonstrating the usage of CORBA with ORCA and SDT, but several references to SOMT are nevertheless made to put things into perspective.
The main parts of the development process that will be examined are shown in Figure 257.
Figure 257 : The design process
|
|
In order to fully understand the tutorial, a basic knowledge about SDL is assumed. Some acquaintance with SOMT and CORBA is also advantageous.
The SOMT method is described in the volume SOMT Methodology Guidelines, and also contains a very brief description of CORBA and the Interface Definition Language (IDL). The The CORBA Integration, also contains information about CORBA, and in particular the mapping rules that are used when mapping IDL to SDL.
Knowledge about specific ORCA and SDT concepts, like implementation links, is also recommended, and can be obtained by for example working through the SOMT Tutorial in SOMT Tutorial.
The examples used in this tutorial can be found in the directory $telelogic/sdt/examples/corbatutorial. Before going through the tutorial, the following steps should be performed:
corbatutorial (this is the directory name that will be used as root name throughout this tutorial). ORBIX_HOME according to the instructions in the Orbix installation guide. If this variable is not set, the linking with Orbix libraries will not work. As long as a the directory is copied, errors made while following the tutorial can always be remedied by starting over again. Each section of this tutorial is a self-contained unit, which can be studied by itself.
The distributed system that is used in this tutorial is relatively simple, and contains three different parts, as is depicted in Figure 258.
Figure 258 : The distributed system
|
|
The system that is used is a very simple one, where customers are allowed to create accounts in a bank, from which they may insert and withdraw money.
The tutorial provides a guide through the activities required to create a CORBA object implementation, starting with system analysis, and ending with an application that can be accessed by CORBA clients.
In this section, the initial part of the SDL system to be used in the tutorial will be examined. The system is not very big initially, but more details will be added later.
It is possible to start anew for each new section by opening the appropriate SDL system, but it is also possible to use the results that arrived at when following the different exercises.
To begin with, a brief description is given of the system that is going to be used in the tutorial.
The directory corbatutorial in the Telelogic Tau installation should now have been copied to a working directory with the same name.
sdtThis will cause the Organizer to appear on the screen.
1_analysis/application.sdt. This could also have been done by issuing the command:sdt 1_analysis/application.sdt
Note that the file application.sdt is present in all directories of corbatutorial, so it is important to open the one in the directory 1_analysis.
An analysis object model of the system to be used in this tutorial has already been provided. During the course of this tutorial, more chapters will be added to the Organizer. At this moment, however, it only contains one chapter, System Analysis. Usually, there would also be a set of use cases in the form of MSCs in this chapter, but these have been omitted for clarity. Instead, as is depicted in Figure 259, only an object model describing the bank system is present.
Figure 259 : Organizer view containing the analysis object model
|
|
By double clicking on the bank icon, the Object Model Editor is started, and the bank system displayed. The model is very simple (as is shown in Figure 260) but sufficient for the purposes of this tutorial.
Figure 260 : The object model of the system
|
|
The object model shows how an actor -- a customer -- is able to perform transactions with a bank, either through an ATM machine, or through a cashier employed by the bank.
Through the cashier, the customer is able to create new accounts, where each new account is associated with a number that has to be used when accessing the account.
The only way to access this account is then through an ATM machine, where it is possible to insert and withdraw money from an account, but also to examine the current balance of the account.
All operations that are performed are logged by the bank.
This model shows the logical architecture of the system, but fails to convey how it should be decomposed. Part of the work in going from analysis to design is to determine just this.
A small hollow triangle is present in the upper left corner of each class in the bank model, as was shown in Figure 260.
These triangles represent endpoints where links can be attached. If a class has a link, the triangle would be filled, and the absence of filled triangles leads to the conclusion that there are currently no links in the object model.
New links can be created for example by using the paste as concept that is defined by the SOMT method, or by using the Link Manager directly. It is possible to find out more about links and endpoints in for example SOMT Tutorial.
In this tutorial, it is assumed that the steps up to and including system analysis have already been performed. After the initial look at the system, it is now time to examine the step from analysis to design, and in particular the way an object model is transformed into IDL, describing the interfaces between the objects in the system.
In section The Tutorial System, it is stated that the system will contain three different parts. This is usually not known from the beginning; the decomposition of the system is determined when going from analysis to design.
The different parts that will make up the distributed system are:
It would have been possible to decompose the system differently; this is merely one of several possible solutions.
From the above, it can be deduced that two sets of IDL descriptions are needed for this small distributed system, one to represent the accounts database, and one to represent the bank.
Looking at this from a SOMT perspective, the current task is depicted in Figure 261.
Figure 261 : Creating an interface definition
|
|
As mapping an object model to an interface description is a design activity, a new chapter is added in the Organizer:
System Design.A new chapter is then added to the Organizer. Move the chapter to the bottom of the Organizer by using the up and down quick buttons in the Organizer.
The System Design chapter ordinarily contains lots of information, such as an SDL system, use cases and IDL descriptions. In this case a module is created where all IDL descriptions will be stored:
Interfaces.It is then time to add the two IDL descriptions that are required. This is done by:
account.idl.application.idl instead for the new document.Both of these interface files are still empty, but this will be remedied in the following sections.
The Organizer now looks like in Figure 262.
Figure 262 : IDL files appended to the Organizer
|
|
There are several ways to create an interface definition, the most obvious being to write it manually. A better way is of course to make use of the copy/paste as concept in Telelogic Tau (together with implinks), since most interface objects are already present in the analysis object model.
A class which is copied in the OM Editor can be pasted as an IDL entity in the Text Editor as either a module or an interface. Both of these mappings will be elaborated below.
The account interface description is very simple: basically there is only one interface to be defined, and that is the account itself.
A very straightforward mapping is used when mapping from an object model to IDL: attributes and operations of the class become attributes and operations of the interface.
The way to actually perform the mapping is as follows:
bank object model in the OM Editor.account, and copy it.account.idl in the Text Editor.// interface account
interface account {
attribute balance;
oneway void add(amount);
oneway void subtract(amount);
};
account.idl. At the same time that this operation is performed, a link is created between the class account and the interface account. In the OM Editor, this is shown by the filled triangle in the upper left corner of the class account.
In the Text Editor, however, the link is shown as underlined words. When dealing with programming languages with a syntax, such as IDL, links are always placed in comments to avoid disturbing that syntax.
Note that the syntax that was used in the object model is slightly changed in the IDL description. A transformation from UML notation to IDL notation has taken place. It is not possible to deduce all information from the object model that is wanted in the IDL description, but more will be said about this in Completing the Interface Description.
The application interface is slightly more complex than the account interface. The bank itself contains two kinds of objects: ATMs and cashiers, and when an aggregation object is mapped it is often mapped as an IDL module, while its parts are either IDL modules or interfaces.
The class bank is therefore mapped to an IDL module:
bank object model in the OM Editor.bank, and copy it.application.idl in the OM Editor.// module bank
module bank {
};
application.idl. Note that the operation that was present in the class bank has not been mapped. When a class is mapped to a module, the module will always be empty (as it cannot have any operations). In some cases, it is necessary to also map the same class to an interface within the module, but here the operation should not be part of the customer interface, so it is simply omitted. It will, however, be part of the SDL design.
The same procedure should then be repeated for the classes atm and cashier, but these should be mapped to IDL interfaces instead. It should be noted that when these classes are pasted to the Text Editor, the cursor should be positioned at the place where the pasted interface should appear (also taking indentation into account). The resulting IDL description (application.idl) is:
// module bank
module bank {
// interface atm
interface atm {
amount balance(number);
oneway void insert(number, amount);
message withdraw(number, amount);
};
// interface cashier
interface cashier {
number create();
};
};
Links will now have been created between the newly copied classes and their corresponding interfaces. Using the Traverse Link command, it is possible to follow a link in either direction.
Examining the IDL descriptions that have been created by copy/paste as, it is noted that they are not complete. In fact, they contain several syntax errors. The reason for this is that the object model does not contain all the information that is needed by the IDL description, and this information must be added manually.
Typical features that must be provided are:
in, inout, and out.Additional things that might have to be considered are for example: synchronous and asynchronous operations, inherited interfaces, and arguments that have not been mentioned in the object model.
The additions that should be manually performed in the file account.idl are highlighted in the below description:
// interface account
interface account {
readonly attribute double balance;
oneway void add(in double amount);
oneway void subtract(in double amount);
};
interface handler {
long create();
account lookup(long);
};
In this case, the attribute balance should be readonly, because otherwise it would be possible to set it through the attribute when the only way to alter it ought to be through the interface operations. Furthermore, parameter kinds and types are also added.
Note that a new interface is also added. This interface is used to create new accounts, and to find the object reference if an account number is known.
Now this is the interface that is going to be used by the SDL system (remember that it describes the database containing all the accounts; this is where all the information is actually stored).
The file application.idl is slightly larger, and require some additional information:
typedef string message;
// module bank
module bank {
// interface atm
interface atm {
double balance(in long number);
oneway void insert(in long number,
in double amount);
message withdraw(in long number,
inout double amount);
};
// interface cashier
interface cashier {
long create();
};
}
A few types are added, and some parameter kinds and types. The operation balance, however, has been altered somewhat. In the class atm, it is stated that this operation should return amount. This is not a type, however, but a concept. The actual type returned is double, and so the amount returned is changed to double. There is also a similar problem with the create operation in the class cashier, which should return a long instead of a number.
This is the interface description that should be implemented by the SDL system. A customer can never access the accounts directly, but has to go through the bank interfaces.
A class operation can be defined as either synchronous or asynchronous according to the following table:
| class operation | synchronous | IDL operation |
|---|---|---|
op |
no |
oneway void op(); |
op {async} |
no |
oneway void op(); |
op {sync} |
yes |
void op(); |
op: return |
yes |
return op(); |
op: return {async} |
error |
oneway return op(); |
Note that the last one is intentionally incorrect due to conflicting information in the object model; an operation cannot be both asynchronous and synchronous at the same time.
When defining an operation in the object model it might not be considered whether it is synchronous or not, but in the interface description this issue must be resolved.
At this point, the interface descriptions of the system are finished, and it is time to consider the architecture definition of the system.
In SOMT, the system design chapter is fairly large (see Performing the System Design), but when using CORBA it becomes somewhat smaller since most of the work goes into defining the interface descriptions.
The architecture definition, however, is created in basically the same way as is described in Creating the Architecture Definition, as will be shown in this section.
The creation of the architecture definition can be split into two parts:
Both of these parts will be examined below.
2_design/application.sdt.If SDT is not running, the current version of the tutorial example can be opened by issuing the command (in the copied corbatutorial directory):
sdt 2_design/application.sdt
When the external SDL interface definitions are created, they are simply generated from the IDL description that describes just this, as is shown in Figure 263.
Figure 263 : Generating the external SDL interface definitions
|
|
The architecture definition is defined using SDL, which is to say that the IDL descriptions that have been defined should be transformed to SDL so that it is possible to implement them.
Technically, this is still the system design, but since the SDL system will be used primarily in the object design (where behavior is added) the SDL system is created with that in mind, and therefore a new Organizer chapter is added. How this is done was described earlier (see Creating a System Design Chapter). Name the chapter Object Design, and place it last in the Organizer by using the up and down quick buttons.
The next step is to create a module within this chapter which will hold the SDL system. This step has also been described earlier, but this time the name of this module should be SDLsystem.
Starting with an IDL description, this can be converted to an SDL system stub (or skeleton) containing signals, remote procedures, process and block types, and types in general. The mapping rules that are used are given in The CORBA Integration, and the IDL compiler sdtidl is used to perform the actual conversion.
In SDT, the transformation of an IDL description to an SDL skeleton is performed as follows:
application.idl. server should be chosen; the generated SDL should implement the IDL description.global should be used.This will result in the interface definition being converted to a corresponding SDL definition according to the aforementioned mapping rules. The resulting SDL definition consists of a set of GR files that are stored in the target directory (which was also specified in the dialog).
The created GR files should then be imported into the Organizer.
SDLsystem that was created earlier. This will control where the imported SDL system is placed in the Organizer.application.ssy (by using the browse button). Press Details, and make sure that the option Close the current system first is not checked. If it is on, turn it off, and then press Set. The SDL system skeleton that was generated above is now included in the Organizer, and what this looks like is shown in Figure 264.
Figure 264
: The SDL system as viewed in the Organizer
The order of the diagram files may differ from your Organizer view.
|
|
Note that two different packages have been defined:
This is according to the mapping rules that are defined for IDL to SDL.
The other IDL description that has been defined, account.idl, should be used by the implemented SDL bank system.
First, a new module should be created to hold all the servers that are used by the bank system, and this module should be named UsedServers. Place this module first in the Object Design chapter.
Secondly, the IDL file account.idl should also be converted to SDL:
account.idl. client should be chosen; the generated SDL should implement the IDL description.global should be used.This will result in the interface definition being converted to a corresponding SDL definition according to the aforementioned mapping rules. The resulting SDL definition consists of a set of GR files that are stored in the target directory (which was also specified in the dialog).
The created GR files should then be imported into the Organizer.
UsedServers that was created earlier. This will control where the imported SDL system is placed in the Organizer.account_inteface.sun (by using the browse button). Press Details, and make sure that the option Close the current system first is not checked. If it is on, turn it off, and then press Set. The interface package is then included in the Organizer. Note the difference here between used and implemented IDL descriptions: for an implemented IDL description, both an interface package and a definition package is generated, while for a used IDL description, only the interface package is generated.
In the SDL system, it is important to remember to add a use clause for each interface package that should be used:
application_definition to open the SDL Editor on the appropriate page.use account_interface;The interface package for the system itself is always automatically used, and the resulting text symbol is shown in Figure 265.
Figure 265 : A use clause must always be present for used IDL descriptions
|
|
Note that a package called idltypes is also included. This package contains SDL versions of IDL types, and must be used by all SDL systems that are going to be CORBA applications.
This concludes the creation of the external SDL interfaces.
|
Note: There are no links between the IDL file and the generated SDL system. If such links are needed, they have to be added manually using the link manager. |
The structure of the SDL system has been defined based on the IDL description of the system. However, it is possible that there remains information about internal structures in the object model that should be part of the SDL system, and in that case these should be pasted from the object model to the SDL system as is shown in the SOMT method (and depicted in Figure 266).
Figure 266 : Mapping object models to SDL concepts
|
|
There are several examples of object models that are mapped to SDL in SOMT Tutorial, so this will not be covered to a large extent in this chapter. Besides, the object model used here is very simple and does not allow a very elaborate example.
However, a small example is the operation log in the class bank. This signal was not part of the external interface, but it should be an internal operation which logs the actions performed in the bank.
bank in the object model bank.application_definition by double-clicking on it in the Organizer.application_definition to transform the copied class to an SDL entity; this will cause a dialog to pop up.The operation in the class bank is asynchronous according to the rules that were presented in A Closer Look at the Mapping of Operations. This means that in SDL it will be mapped to a signal, which is always defined within a text symbol. The result of the previous operation is shown in Figure 267.
Figure 267 : The mapping of an operation to SDL
|
|
Along with the signal, a signallist name is also defined, which can be used when referring to signals defined in this class (in this case, there is only one, but if there had been more operations there would be as many signals or remote procedures in the signallist).
A link is also created between the class and the text symbol containing the signal.
When the SDL system was generated from the IDL description, process and block types were created, and as a final step in specifying the architecture definition, block and process instances should be created from these types and connected to each other.
In this small system, there are only two levels to think about: the block level and the process level.
There is only one block type defined in the system, and this should be instantiated:
application_system.bank with the name office.atm and cashier as possible inputs to the instance.This should result in something close to what is shown in Figure 268.
Figure 268
: Instantiation of the block type bank
|
|
The block type bank itself contains the process types that are defined in the system, and these should also be instantiated and connected:
bank.atm and cashier. Both of these should be instantiated (using the names downtown and employee, respectively). atm and cashier as possible inputs to their respective instances.An example of what this might look like is given in Figure 269.
Figure 269
: Instantiations of the process types atm and cashier
|
|
With this, the architecture definition is completed, and it is time to provide the behavior of the system.
The behavior of the system can be provided in many ways as long as the outward interface remains unchanged. The architecture of the system was defined in the previous section, and in this section its behavior will be added.
This section is mostly a repetition of what should already be known about creating an SDL system, and for that reason it is kept very brief.
3_architect/application.sdt.If SDT is not running, the current version of the tutorial example can be opened by issuing the command (in the copied corbatutorial directory):
sdt 3_architect/application.sdt
The Organizer should contain three different chapters: System Analysis, System Design, and Object Design.
The object design model defines the behavior of the SDL system, and is not particularly CORBA related. A few design notes are given below, but otherwise the SDL system provides its own documentation.
The signal log should be used to log all actions in the bank. For this purpose, a logging process type is defined and instantiated in the block type bank. This is not externally visible, but only stored within the bank itself.
For each action that occurs in the bank, either at the atm or at the cashier, a log signal should be sent to the logger, which stores them in a sequential list.
Figure 270 : The logger process type
|
|
Attributes do not need to have be implemented since the behavior of these operations is well known and can be automatically generated. In this example, there are no attributes, and so this is not an issue.
There are four different operations to be implemented in the SDL system, three of which are remote procedures and one of which is a signal (and therefore asynchronous).
Beginning with the signal, bank_atm_insert, it is associated with a procedure. This procedure is not mandatory, and may be removed if it is not wanted. The purpose of the procedure is to contain the behavior of the transition to be executed when the signal is received. This might just as well be represented using a transition directly in the process type.
The behavior of this particular transition is very simple:
handler_lookup.account_add to that PId value.Note that the procedure heading is already defined. This must not be changed unless the corresponding IDL description is also changed at the same time.
The synchronous operations are more complex than the asynchronous one.
Starting with the bank_atm_withdraw operation, this is the opposite of the insert operation that was implemented before. In this case, money should be withdrawn from an account only if the balance of the account allows this.
The behavior should therefore be something like:
account_get_balance. Balance is an attribute of accounts.The next operation, bank_atm_balance, is much simpler. In this case the customer only wants to know the current balance of an account:
account_get_balance, and return this value.The last operation to be considered in the SDL system is bank_cashier_create, which is used to create new accounts:
handler_create to create a new account. This operation does not have to be addressed to a specific receiver as the ORB will locate a suitable receiver.Once the behavior has been added to the SDL system, it should be analyzed and simulated. The Analyzer will find errors in the SDL specification of the system, while the Simulator is able to find errors in the behavior of the system. The Validator can also be used to locate errors.
All of this is however outside the scope of this tutorial.
The entire SDL system has been created and tested in the previous sections, and it is time to generate the final application that will be used in the CORBA environment.
4_implement/application.sdt.If SDT is not running, the current version of the tutorial example can be opened by issuing the command (in the copied corbatutorial directory):
sdt 4_implement/application.sdt
Creating the SDL application is simply a matter of making the system. However, there are some things that have to be performed first in order to handle this, such as preparing the make template file.
As was mentioned in Preparations, the environment variable $ORBIX_HOME should also be set.
A make template file called application.tpm was generated together with the SDL system skeleton when the IDL description was converted to SDL. When an SDL application should only work as a server, this make template file is complete, and no further changes are needed. However, when the SDL application should be able to function as a client and request services from other CORBA servers, some manual additions have to be made:
application.tpm in a text editor.account.idl, which means that on the line starting with serverOBJECTS =, the following two files should be added: accountC.o account_c.o.The contents of this file is shown below, and the new additions have been highlighted.
#--------------------------------------------------
# object files for this server (do not alter)
objectimplOBJECTS = applicationS.o application_i.o
# object files for other servers (please add here)
# use pairs like: <name>C.o <name>_c.o
serverOBJECTS = accountC.o account_c.o
# hooks into the make file (do not alter)
USERTARGET = $(objectimplOBJECTS) $(serverOBJECTS)
USERLIBRARIES =
#--------------------------------------------------
You must also manually set the correct application name in the header file related to the external server described by account.idl, i.e. account_c.hh:
account_c.hh in a text editor. .ifc file to specify the name "application" instead of "Untitled".The initial part of the file is shown below, and the change has been highlighted:
#define EXCEPTIONS #include "account.hh" #include "orb.hh" #include "application.ifc"
When creating the final application, the menu command Make should be issued, and in the resulting dialog several options have to be set.
|
|
The make dialog is divided into three main areas, each of which will be described below.
CadvancedFullNoAs definedapplication.tpmSCTCORBA$sdtdir directory..sct. In this section, it will be shown how the created application can be registered with the ORB, and also executed in a CORBA environment.
5_complete/application.sdt.If SDT is not running, the current version of the tutorial example can be opened by issuing the command (in the copied corbatutorial directory):
sdt 5_complete/application.sdt
It is still necessary to Make the system, however, as was described in the previous section.
The command line interface to Orbix is described in the Orbix' Programming Guide, but the commands that might be useful in this tutorial are summarized here:
putit, register an application,lsit, list the registered applications,catit, list information about a registered application,psit, list running processes, and killit, kill running processes. $ORBIX_HOME/bin/orbixd &
Before a CORBA application can be used it must be registered with the ORB. In Orbix, this is done by using the putit command.
putit -hhostname application \ corbatutorial/5_complete/application_acx.sct
The server name should always be the same as the name of the IDL description, which is why application was chosen.
An additional server application has been created implementing the account database in C++. How this is done is not described further in this tutorial; suffice it to say that its interface is described in account.idl.
putit -hhostname account \ corbatutorial/server/account
Details about how a C++ server is created can be found in Orbix' Programming Guide.
Once the two CORBA applications has been registered, clients are able to utilize their services. In the directory corbatutorial/client, a C++ client has been implemented that makes use of the services offered by the SDL system.
Details about how a C++ client is created can be found in Orbix' Programming Guide.
corbatutorial/client/client hostname