orber

8/13/2019 orber

1/206

8/13/2019 orber

2/206

8/13/2019 orber

3/206

Contents

1 1

1.1 C ontent O verview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 B rief D e script ion of t he U sers G uid e . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2.1 O RB Kernel and IIO P Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2.2 Int erface Reposit ory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.3 ID L t o Erlang Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.4 C osN aming Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1. 2. 5 R eso lv in g In it ia l R ef eren ces f ro m J av a o r C + + . . . . . . . . . . . . . . . . . . . 2

1.2.6 O rber St ub/Skelet on . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.7 C O RBA Except ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.8 Int erceptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.9 O rberWeb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2.10 D ebugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Introduction to Orber and theIFR 3

2.1 Int roduction to O rber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.1.1 O verview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.2 The O rber Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.2.1 O RB Kernel and IIO P . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.2.2 Th e O b ject Req uest B roker (O R B) . . . . . . . . . . . . . . . . . . . . . . . . . 6

2. 2. 3 Int ernet Int er-O b ject P ro to co l (IIO P ) . . . . . . . . . . . . . . . . . . . . . . . . 7

2.3 Int erface Reposit ory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.3.1 Int erf ace Reposit ory (IFR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

iiiO rber Application

8/13/2019 orber

4/206

3 9

3.1 Installat ion P rocess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.1.1 P reparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.1.2 Jum p St art O rber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.1.3 Inst all Single N od e O rb er . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103. 1. 4 Inst all R AM B ased M ult i N od e O r ber . . . . . . . . . . . . . . . . . . . . . . . . 11

3. 1. 5 Inst all D i sk B ased M ult i N od e O r ber . . . . . . . . . . . . . . . . . . . . . . . . 11

3. 1. 6 R un nin g Ja va c lien ts a ga in st O r b er. . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.2 C onfi guration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.2.1 O rb er Environm ent Fla gs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.3 Firew all C onfi gurat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

3.4 Int erface C onfi gurat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4 23

4.1 O M G ID L t o Erla ng M apping - O v erview . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.2 O M G ID L Mapping Elem ent s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.3 G et ting Start ed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4.4 Basic O MG ID L Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

4. 5 Tem pla t e O M G I D L Ty pes a nd C o m plex D ec la ra t or s . . . . . . . . . . . . . . . . . . . 25

4.5.1 St ring/WSt ring D a ta Ty pes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

4.5.2 Seq uence D a ta Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.5.3 Array D a ta Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.5.4 Fixed D a ta Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

4.6 C onst ruct ed O MG ID L Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284.6.1 St ruct D a ta Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.6.2 Enum D a ta Ty pe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.6.3 U nion D a ta Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

4.7 Scoped N am es and G enerat ed Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

4.7.1 Scoped N ames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

4.7.2 G enerat ed Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

4. 8 Ty pec od e, I den tit y a nd N a me Ac cess Fu nc tio ns . . . . . . . . . . . . . . . . . . . . . . 34

4.9 References t o C onst ant s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

4. 10 R ef erences t o O b ject s D e fi ned in O M G ID L . . . . . . . . . . . . . . . . . . . . . . . . 35

4.11 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

4.12 Access t o At tribut es . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

4.13 Invoca tions of O p era tions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

4. 14 Im plem ent ing t he D B Ap plica tion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

4. 15 R eserv ed C o mp iler N am es a nd Key w ord s . . . . . . . . . . . . . . . . . . . . . . . . . . 42

4.16 Ty pe C o de Represent at ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

iv O rber Application

8/13/2019 orber

5/206

5 45

5.1 O v erview of t he C o sN am ing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

5. 2 Th e B asic U se-c ases o f t h e N a min g S erv ice . . . . . . . . . . . . . . . . . . . . . . . . . 47

5.2.1 Fe tch I nit ial R ef eren ce to th e Nam in g Service . . . . . . . . . . . . . . . . . . . 47

5.2.2 C rea ting a N am ing C o nt ex t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475. 2. 3 B ind ing a nd U nb ind ing N am es t o O b ject s . . . . . . . . . . . . . . . . . . . . . 48

5.2.4 Resolving a N am e t o an O b ject . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

5. 2. 5 L ist in g t h e B in din gs in a N a min gC o nt ex t . . . . . . . . . . . . . . . . . . . . . . 48

5.2.6 D e st roy ing a N am ing C o nt ext . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

5.3 Int eroperab le N am ing Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

5.3.1 IO R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

5.3.2 corbaloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

5.3.3 corbaname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

6 536.1 Security in O rber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

6.1.1 Int roduct ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

6. 1. 2 Ena ble U sa ge o f S ecure C o nnect io ns . . . . . . . . . . . . . . . . . . . . . . . . 53

6.1.3 C o n figu rat io ns w h e n Orber is U sed o n th e Server Side . . . . . . . . . . . . . . 53

6.1.4 C o n figu rat io ns w h e n Orber is U sed o n th e C l ie nt Side . . . . . . . . . . . . . . 54

7 Service Implementation 57

7.1 O rber Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

7. 1. 1 A Tu to ria l o n H o w to C r ea t e a S im ple S er vice . . . . . . . . . . . . . . . . . . . 57

7. 1. 2 A Tu to ria l o n H o w t o S t art O r ber a s L igh t w eigh t . . . . . . . . . . . . . . . . . 65

7.2 O rber St ubs/Skelet ons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

7. 2. 1 O r b er S tu bs a nd S kelet on s D esc rip tio n . . . . . . . . . . . . . . . . . . . . . . . 66

8 71

8.1 Syst em Except ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

8.1.1 Status Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

8.1.2 Minor Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

8. 1. 3 S up port ed S yst em Ex cep tio ns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

8.2 U ser D efi ned Except ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

8.3 Throw ing Except ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

8.4 C atching Except ions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

vO rber Application

8/13/2019 orber

6/206

9 75

9.1 U sing Interceptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

9. 1. 1 C o nfi gure O r ber t o U se Int ercep to rs . . . . . . . . . . . . . . . . . . . . . . . . 75

9.1.2 C rea ting Int ercept ors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

9.2 Int ercept or Exam ple . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

10 Tools, Debuggingand FAQ 81

10.1 O rberWeb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

10.1.1 Using O rberWeb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

10.1.2 St art ing O rb erWeb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

10.2 D ebugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

10.2.1 Tools and FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

11 Orber ReferenceManual 95

11.1 C osNaming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

11.2 C o sN am ing B ind ingIt era tor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

11.3 C o sN am ing N am ingC o nt ex t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

11.4 C o sN am ing N am ingC o nt ex tEx t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

11.5 Module Int erface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

11.6 any . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

11.7 corba . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

11.8 corba object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

11.9 fi xed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

11.10 int ercept ors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

11.11 lname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

11.12 lnam e component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

11.13 orber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

11.14 orber acl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

11.15 orb er d iagnost ics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

11.16 orber ifr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

11.17 orber tc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

List of Figures 185

List of Tables 187

Glossary 189

vi O rber Application

8/13/2019 orber

7/206

Chapter 1

1.1 Content Overview

The Orber documentation is divided into three sections:

PART O NE - The U sers G uide

D escription of th e O rber Applicat ion including ID L-to-Erlang language mapping, services and asmall tutorial demonstrating the development of a simple service.

PART TWO - Release Not es

A concise history of Orber.

PART TH REE - The R eference Manual

A quick reference guide, including a brief description, to all the functions available in Orber.

1.2 Brief Description of the Users Guide

The Users G uide contains the following parts:

ORB kernel and IIOP support

Interface Repository

IDL to Erlang mapping

C osNaming Service

Resolving initial reference from Java or C + +

Tut orial - creat ing a simple service

C O RBA Exceptions

Interceptors

O rberWeb

D ebugging

1.2.1 ORB Kernel and IIOP Support

The ORB kernel which has IIOP support will allow the creation of persistent server objects in Erlang.

These objects can also be accessed via Erlang and Java environments. For the moment a Java enabled

O RB is needed to generate Java from ID L t o use Java server objects (this has been tested using

OrbixWeb).

1O rber Application

8/13/2019 orber

8/206

Chapter 1:

1.2.2 Interface Repository

The IFR is a n interface repository used for some t ype-checking w hen cod ing/decoding IIO P. The IFR is

capable of storing all interfaces and declarations of O MG ID L.

1.2.3 IDL to Erlang Mapping

The O MG ID L ma pping for Erlang, w hich is necessary t o access the functionality of O rber, is

described, The mapping structure is included as the basic and the constructed O MG ID L t ypes

references, invocat ions and Erlang charact eristics. An exam ple is also provided.

1.2.4 CosNaming Service

Orber contains a CosNaming compliant service.

1.2.5 Resolving Initial References from J ava or C++

A couple of classes are added to Orber to simplify initial reference access from Java or C+ + .

Resolving ini ti al reference from JavaA class w ith only one method w hich returns an I O R on the external string format to t he INIT object

(see Interoperable Naming Service specification).

Resolving ini ti al reference from C+ +A class (and header file) w ith only one method w hich returns an IO R on t he external string format to

the IN IT object (see Interoperable Naming Service specifica tion).

1.2.6 Orber Stub/Skeleton

An example which describes the API and behavior of Orber stubs and skeletons.

1.2.7 CORBA Exceptions

A listing of all system exceptions supported by O rber and how one should ha ndle them. This chapter

also describe how to generate user defined exceptions.

1.2.8 Interceptors

D escibes how to implement and activate interceptors.

1.2.9 OrberWeb

Offers the possibility to administrate and supervise Orber via a G UI.

1.2.10 Debugging

D escribes how to u se different t ools wh en debugging and/or developing new applications using Orber.

Also includes a FAQ, w hich deal w ith t he most common mistakes when using Orber.

2 O rber Application

8/13/2019 orber

9/206

Chapter 2

Introduction to Orber and the IFR

This chapter contains an introduction to O rber and the IFR (Interface Repository).

2.1 Introduction to Orber

2.1.1 Overview

The O rber application is a C O RBA compliant O bject Req uest Brokers (O RB), w hich provides CO RBA

functionality in an Erlang environment. Essentially, the ORB channels communication or transactions

between nodes in a heterogeneous environment.

C O R B A (C ommon O bject Request Broker Architecture) provides an interface defi nition language

allow ing efficient system int egration and also supplies sta ndard specifi cat ions for some services.

The Orber application contains the following parts:

ORB kernel and IIOP support

Interface Repository

Interface D efinition Language Mapping for Erlang

C osNaming Service

Benefits

O rber provides CO RBA functionality in an Erlang environment tha t enables:

Platform i nteroperabi li ty and tra nsparency

Orber enables communication between OTP applications or Erlang environment applications and

oth er platform s; for examp le, Window s NT, Solaris etc, allow ing platform transparency. This isespecially helpful in situations where there are many users with different platforms. For example,

booking airline tickets w ould require the airline database a nd hundreds of travel agents (w ho m ay

not h ave the same platform) t o book seats on fl ights.

3O rber Application

8/13/2019 orber

10/206

Chapter 2: Introduction to Orber and the IFR

A pplication level int eroperabi li ty and tra nsparency

As O rber is a C O RBA compliant application, its purpose is to provide interoperability and

transparency on the application level. O rber simplifi es the distributed system softw are by defining

the environment as objects, which in effect, views everything as identical regardless of

programming languages.

Previously, time-consuming programming was required to facilitate communication between

different languages. H ow ever, w ith C O RBA compliant O rber the Application Programmer is

relieved of this task. This makes communication on an application level relatively transparent to

the user.

Purpose and Dependencies

The system architecture and OTP dependencies of Orber are illustrated in figure 1 below:

Figure 2.1: Figure 1: O rber D ependencies and Struct ure.

Orber is dependent on Mnesia (see the Mnesia documentation) - an Erlang database management

application used to store object information.

Note:Although Orber does not have a run-time application dependency to IC (an ID L compiler for

Erlang), it is necessary when building services and applications. See the IC documentation for further

details.


8/13/2019 orber

11/206

2.2: The Orber Application

Figure 2.2: Figure 2: ORB interface between Java and Erlang Environment Nodes.

This simplified illustration in figure 2 demonstrates how Orber can facilitate communication in a

heterogeneous environment. The Erlang Nodes running OTP and the other Node running applications

written in Java can communicate via an O RB (O bject Req uest B roker). Using Orber means that

C O RBA functions can be used to achive this communication.

For example, if one of the above nodes requests an ob ject, it does not need to know if that object is

located on the same, or different, Erlang or Java nodes. The O RB w ill channel the information creating

platform and application transparency for the user.

Prerequisites

To fully understand t he concepts presented in the docum entat ion, it is recommended t hat the user is

familiar w ith distributed programming and C O RBA (Com mon O bject Req uest B roker Architecture).

Recommended reading includesO pen Telecom Platform D ocumentati on Setan d Concurrent Programmingin Erlang.

2.2 The Orber Application

2.2.1 ORB Kernel and IIOP

This chapter gives a brief overview of the ORB and its relation to objects in a distributed environment

and t he usage of D omains in O rber. Also Internet-Inter O RB P rotocol ( IIOP) is discussed and how

this protocol facilitat es communication betw een O RBs to allow the accessory of persistent server

objects in Erlang.

5O rber Application

8/13/2019 orber

12/206


2.2.2 The Object Request Broker (ORB)

An ORB kernel can be best described as the middle-ware, which creates relationships between clients

and servers, but is defined by its interfaces. This allows transparency for the user, as they do not have to

be aw are of w here the requested object is located. Thus, t he programmer can w ork with a ny oth er

platform provided t hat an ID L mapping and interfaces exist.

The ID L m apping wh ich is described in a later chapter is the translator b etw een other platforms, and

languages. H ow ever, it is the O RB, w hich provides objects with a structure by w hich they can

communicate w ith oth er objects.

ORBs intercept and direct messages from one object, pass this message using IIOP to another ORB,

w hich then directs the message to the indicated object.

An O RB is the base on w hich interfaces, comm unication stubs and mapping can be built t o enable

communication betw een objects. O rber usesdomains to group objects of different nodes

H ow the O RB provides communication is shown very simply in fi gure 1 below:

Figure 2.3: Figure 1: How the Object Request Broker works.

The domain in Orber gives an extra aspect to the distributed object environment as each domain has

one ORB, but it is distributed over a number of object in different nodes. The domain binds objects on


8/13/2019 orber

13/206

2.2: The Orber Application

nodes more closely than distributed objects in different domains. The advantage of a domain is that a

faster communication exists betw een nodes and objects of the same domain. An internal

communication protocol (other than IIOP ) allows a more effi cient comm unication betw een these

objects.

Note:Unlike objects, domains can only have one name so that no communication ambiguities exist

betw een doma ins.

2.2.3 Internet Inter-Object Protocol (IIOP)

IIOP is a communication protocol developed by t he O MG to fa cilitate communication in a distributed

object-oriented environment.

Figure 2 below demonstrates how IIOP w orks betw een objects:

Figure 2.4: Figure 2: IIOP communication between domains and objects.

Note:Within th e O rber domains the objects communicate w ithout using the IIO P. H ow ever, the user is

unaware of the difference in protocols, as this difference is not visible.

7O rber Application

8/13/2019 orber

14/206


2.3 Interface Repository

2.3.1 Interface Repository(IFR)

The IFR is an interface repository built on the Mnesia application. Orber uses the IFR for some

ty pe-checking w hen coding/decoding IIO P. The IFR is capable of storing all interfaces and d eclarationso f OM G I DL.

The interface repository is mainly used for dynamical interfaces, and as none are currently supported

this function is only really used for retrieving information about interfaces.

Functions relating to the manipulation of the IFR including, initialization of the IFR, as well as, locating,

creating and destroying initial references are detailed further in the Manual Pages.


8/13/2019 orber

15/206

Chapter 3

3.1 Installation Process

This chapter describes how to install Orber in an Erlang Environment.

3.1.1 Preparation

To begin with, you must decide if you w ant t o run O rber as a:

Single node (non-distribut ed)- all communication w ith oth er O rber instances and O RBs suppliedby other vendors use the OMG G IOP protocol.

M ulti node (distributed)- all O rber nodes, w ithin the same domain, communicate via th e Erlangdistribution protocol. For all other Orber instances, i.e. not part of the same domain, and ORBs

supplied by other vendors, the O MG G IO P protocol is used.

Which approach to use is highly implementation specific, but a few things you should consider:

All nodes within an O rber domain should have the same security level.

If th e capacity is greater than load (volume of t raffic) a single-node O rber might be a good

solution.

In some cases the distributed system architecture requires a single-node O rber installation .

A multi-node Orber makes it possible to load balance and create a more fault tolerant system.

The Objects can also have a uniform view if you use distributed Mnesia tables.

Since t he G IO P protocol creates a larger overhead t han the Erlang distribution protocol, th e

performance will be better when communicating with Objects within the same Orber domain

compared with inter ORB communication (G IOP).

You also have to decide if you w ant O rber to store internal dat a usingdisc copiesand/or ram copies.

Which storage type you should depends if/how you intend t o use Mnesia in your application. If you

intend to use disc copiesyou must start w ith creating a Mnesia schema, w hich contain informationabout the location of the Erlang nodes where O rber is planned t o be run. For more background

information, see the Mnesia documentation.

In some cases it is absolutely necessary to change the default configuration of Orber. For example, if

tw o O rber-O RBs shall be able to comm unicate via G IOP, they m ust have a unique domaindomain.

Consult the configuration settings [page 12] section. If you encounter any problems; see the chapter

about D ebuggin gin t his U sers G uide.

9O rber Application

8/13/2019 orber

16/206

Chapter 3:

3.1.2 J ump Start Orber

The easiest w ay t o start O rber is to useorber:jump start(Port), w hich start a single-node O RB w ith

(most likely) a unique domain (i.e. IP-number:Port). This function may only be used during

development and testing. For any other situation, install and start Orber as described in the following

sections. The listen port, i.e. iiop port configuration parameter, is set to the supplied Port.

Warning:How Orber is configured when using orber:jump start(Port)may change at any time without

warning. Hence, this operation must not be used in systems delivered to a customer.

3.1.3 Install Single Node Orber

Since a single node Orber communicate via th e O MG G IO P protocol it is not necessary to start the

Erlang distribution (i.e. using -name/-sname).

If we use ram copiesthere is no need for creating a disk based schema. Simply use:

erl> mnesia:start().

erl> corba:orb_init([{domain, "MyRAMSingleNodeORB"}]).

erl> orber:install([node()], [{ifr_storage_type, ram_copies}]).

erl> orber:start().

If you installation requiresdisc copiesyou must begin with creating a Mnesia schema. O therwise, the

installation is similar to a RAM installation:

erl> mnesia:create_schema([node()]).

erl> mnesia:start().

erl> corba:orb_init([{domain, "MyDiskSingleNodeORB"}]).

erl> orber:install([node()], [{ifr_storage_type, disc_copies},

{nameservice_storage_type, disc_copies}]).

erl> orber:start().

You can still choose to store the IFR data as ram copies, but then the data must be re-installed (i.e.

invoke orber:install/2) if the node is restarted. Hence, since the IFR data is rather static you should

use disc copies. For more information see the orbersection in the reference manual.

If you do not need to change O rbers configuration you can skip orb init/1 [page 130]. But, you shouldat least set t he IIO P t imeout parameters.

Note:When starting O rber as lightw eight, mnesia and orber:install/* are not required. You must,

however, use the configuration [page 12] parameter lightweight.


8/13/2019 orber

17/206

3.1: Installation Process

3.1.4 Install RAM Based Multi Node Orber

Within a domain O rber uses the Erlang distribution protocol. H ence, you muststart it first by, forexample, using:

hostA> erl -sname nodeA

In this example, we assume that we want to use two nodes; nodeAa nd nodeB. Since Mnesia must know

w hich other nodes should a part of the distribution w e either need to ad d t he Mnesia configuration

parameterextra db nodes or usemnesia:change config/2. To begin w ith, M nesia must be start ed on

all nodes before w e can install O rber:

nodeA@hostA> mnesia:start().

nodeA@hostA> mnesia:change_config(extra_db_nodes,

[nodeA@hostA, nodeB@hostB]).

After that the above have been repeated on nodeBwe must first make sure that both nodes will use the

same domain name, then w e can install O rber:

nodeA@hostA> corba:orb_init([{domain, "MyRAMMultiNodeORB"}]).nodeA@hostA> orber:install([nodeA@hostA, nodeB@hostB],

[{ifr_storage_type, ram_copies}]).

nodeA@hostA> orber:start().

Note that you can only invoke orber:install/1/2 on one of the nodes. Now we can start Orber on

the ot her node:

nodeB@hostB> corba:orb_init([{domain, "MyRAMMultiNodeORB"}]).

nodeB@hostB> orber:start().

3.1.5 Install Disk Based Multi Node Orber

As for RAM based multi-node Orber installations, the Erlang distribution must be started (e.g. erl

-sname nodeA). The major difference is that w hen it is disk based a Mnesia schema must be created:

nodeA@hostA> mnesia:create_schema([nodeA@hostA, nodeB@hostB]).

nodeA@hostA> mnesia:start().

In this example, we assume that we want to use two nodes; nodeAa nd nodeB. Since it is not possible to

create a schema on more than one node. H ence, all w e have to do is to start Mnesia (i.e. invoke

mnesia:start()) o n nodeB.

After Mnesia have been started on all nodes, you must confi rm t hat all nodes have the same dom ain

name, then O rber is ready to be installed:

nodeA@hostA> corba:orb_init([{domain, "MyDiskMultiNodeORB"}]).

nodeA@hostA> orber:install([nodeA@hostA, nodeB@hostB],

[{ifr_storage_type, disc_copies}]).

nodeA@hostA> orber:start().

Note that you can only invoke orber:install/1/2 on one of the nodes. Now we can start Orber on

the other node:

nodeB@hostB> corba:orb_init([{domain, "MyDiskMultiNodeORB"}]).

nodeB@hostB> orber:start().

11O rber Application

8/13/2019 orber

18/206

8/13/2019 orber

19/206

8/13/2019 orber

20/206

Chapter 3:

N ote:O n a UN IX system it is preferable to have a IIO P port higher than 1023, since it is notrecommended to run Erlang as a root user.

nat i iop port The value is either a n integer or local, DefaultNATPort, [ Port, NATPort ] . See

also Firewall Configuration [page 18].

i iop out ports When set t o 0 any available port w ill be used. If a range is specifi ed, O rber will only use

the local ports within the interval when trying to connect to another ORB (Orber acts as a clientO RB). If all ports are in use communication w ill fail. H ence, it isabsolutely necessaryto setiiop connection timeoutas well. Otherwise, connections no longer in use will block further

communication. If one use, for example, erl -orber iiop out ports " 5000,5020 ", Orber

will only use port 5000 to 5020 when connecting. If communicating via SSL, make sure you use a

version that supports the local port, Port option. See also Firew all Confi guration [page 18].

i iop max fragments Limits the number of IIO P fragments allow ed per request.

i iop max in requestsLimits the number of concurrent incoming requests per incoming connection.

i iop max in connectionsLimits the number of concurrent incoming connections.

i iop backlog D efines the maximum length the queue of pending incoming connections may grow to.

iiop packet size D efines the max imum size of incoming requests. If th is limit is exceeded, the

connection is closed.

ip addressThis option is used if orber only should listen on a specific ip interface on a multi-interface

host or if exported IOR:s should contain multiple components. The value is the IPv4 or IPv6

address as a string or

multiple, IPList

. The latter requires that the object is available via the

all IP addresses found in the list.

ip address local This option defines the default local interface O rber will use when connecting to

another O RB via IIO P, i.e., O rber act a s the client side O RB. The value is a IPv4 or IPv6 address

as a string. It is possible to override ip address local by defining iiop aclor passing the O rber

genericinterfaceCont ext. If this option is not used, the underlying O S w ill choose w hich

interface to use. For more information, see the Interface Configuration [page 20] section.

nat ip addressThe value is the ip address as a string (IPv4 or IPv6), multiple, IPList or local,

DefaultNATIPAddress, [

IPAddress, NATIPAddress

]

. See also Firew all Confi guration [page18].

objectkeys gc timeThis option should be set if objects are started using the option persistent,

true . The value isinteger()second s.

giop version D efines the default G IOP protocol version.

iiop setup connection timeout The value is an integer (seconds) or the a tom infinit y. This option is

only valid for client-side connections. If this option is set, attempts to connect to other ORBs will

timeout aft er the given time limit. Note, if the t ime limit is large the TC P protocol may t imeout

before t he supplied value.

iiop connection timeoutThe value is an integer (timeout in seconds between 0 and 1000000) or the

atom infinity. This option is only valid for client object connections, i.e., will have no effect on

server connections. Setting this option will cause client connections to be terminated, if and only

if, there are no pending requests. If there are a client still waiting for a reply, Orber will try again

after the given seconds have passed. The main purpose for this option is to reduce the number of

open connections; it is, for example, not necessary to keep a connection, only used once a day,

open at all time.

iiop in connection timeoutThe same as for iiop connection timeout. The only difference is that this

option only affects incoming connections (i.e. Orber act as server-side ORB).

i iop out keepaliveEnables periodic transmission on a connected socket, when no other data is being

exchanged. If the other end does not respond, the connection is considered broken and will be

terminated. When enabled the SO KEEPALIVE socket level option is set.


8/13/2019 orber

21/206

8/13/2019 orber

22/206

8/13/2019 orber

23/206

8/13/2019 orber

24/206

Chapter 3:

Local Typechecking- If activated, parameters, replies and raised exceptions will be checked toensure that the da ta is correct. If an error occurs, t he error loggeris used t o generate report s.

O ne M A Y N O T use this option for delivered systems due to the extra overhead. Since this optionactivates typechecking for all objects generated on the target node, it is also possible to use the

option local typecheck, boolean() , when invoking oe create/2, oe create link/2,

corba:create/4 or corba:create link/4, to override the configuration parameter.

Use H ost N amein IO R- normally O rber inserts the IP-number in IO R:s when they are exported.In some cases, this will cause the clients to open two connections instead of one.

EnableNAT- if t his fla g is set, it is possible to use the N AT (Netw ork Address Translation)configuration parameters (nat iiop port, nat iiop ssl portand nat ip address).

Local Interceptors- use interceptors for local invocations.

Light IFR- if the IFR is not explicitly used and this flag is set, Orber will use a minimal IFR toreduce memory usage and installation time.

UseIPv6- w hen this option is activated, O rber w ill useIPv6 for inter-ORB communication.

EXIT Tolerance- servers w ill survive even though the call-back mod ule caused an EX IT.

EnableI ncoming AC L - activates access control for incoming connections.

Enable O utgoing AC L - activates access control for outgoing connections.

UseCurrent Interfacein IOR- when set, Orber will add the interface the request came via toexported local IOR:s.

Invoking th e operation o rber:info/1/2 [page 151] w ill display the current ly set fl ags in a read able w ay.

3.3 Firewall Configuration

Firewalls are used to protect objects from clients in other networks or sub-networks, but also to restrict

which hosts internal objects may connect to (i.e. inbound protectionand outbound protection). A

firewall can limit access based on:

Transport L evel- performs access control decisions based on address information in TCP headers.

A pplication L evel- understands G IOP messages and the specific transport level inter-ORBProtocol supported e.g. IIOP.

This section describes how to configure a Transport Levelfirew all. It must have prior know ledge of

the source to destination mappings, and conceptually has a configuration table conta ining tuples of th e

form: ( inhost:inport , outhost:outport ). If there are no port restrictions it is rather easy to

configure the fi rewall. O therw ise, w e must consider the following alternatives:

Incomi ng Requests- O rber only uses the port-numbers specifi ed b y the configuration parametersiiop portan d iiop ssl port. O ther O RBs may use several ports but it should be possible to changethis behavior. C onsult the other O RBs documentation.

O utgoin g Requests- Most ORBs, Orber included, ask the OS to supply a vacant local port whenconnecting to the server-side O RB. It is possible to change th is behavior w hen using Orb er (i.e. set

the confi guration parameteriiop out ports).


8/13/2019 orber

25/206

3.3: Firewall Configuration

Warning:Using the option iiop out portsmay result in th at O rber runs out of valid ports numbers. For

example, ot her applications may steal some of the ports or the numb er of concurrent outgoing

connections to oth er OR Bs may b e higher tha n expected. To reduce, but not eliminate, th e risk you

should use iiop connection timeout.

Firewall configuration example:

# "Plain" IIOP

To: Orber-IPNo:(iiop port) From: ORB-IPNo:X

To: ORB-IPNo:Z From: Orber-IPNo:(iiop out ports | Any Port)

# IIOP via SSL

To: Orber-IPNo:(iiop port) From: ORB-IPNo:X

To: Orber-IPNo:(iiop ssl port) From: ORB-IPNo:Y

To: ORB-IPNo:Z From: Orber-IPNo:(iiop out ports | Any Port)

If the communication take place via a TC P Firewall w ith NAT [page 19] (Netw ork Address

Translation), w e must act ivate t his behavior and d efine the ext ernal address and/or port s.

Figure 3.1: TCP Firewall With NAT

Using NAT makes it possible to use different host dat a for different netw ork domains. This way w e canshare Internet Prot ocol ad dress resources or ob scure resources. To enab le th is feature t he Enab le NAT

[page 17] fl ag must be set and nat iiop port, nat iiop ssl port a nd nat ip addressconfi gured,

w hich maps to iiop port, iiop ssl porta nd ip address respectively. Hence, the firewall must be

configured to translate t he external to the internal representation correctly. If t hese NAT parameters are

assigned a single port number or IP address, only those will be used when an IOR is exported to another

ORB. When ip addressis set to multiple, [IPAddress] ,nat ip address should be configured in

the same wa y, so that each NAT IP address can be translated t o a valid address by the fi rewall. If objects

are supposed to b e accessible via different interfaces and port , see also Interface C onfi guration [page

20], the opt ions local, DefaultNATIPAddress, [ IPAddress, NATIPAddress ] and/or local,


8/13/2019 orber

26/206

8/13/2019 orber

27/206

3.4: Interface Configuration

different local interfaces are used for different applications. Some times, it is even necessary to use a

specific interface for a single CORBA object. This section describe how one can alter this in different

ways.

The default behavior is that O rber lets the O S confi guration decide which interface will be added in

IOR:s exported to another ORB and the local interface used when connecting to another ORB (Orber

act as client side O RB). The latt er can b e overridden by setting the configuration parametersiiop ssl ip address localand/or ip address local, w hich w ill affect IIOP via SSL and IIOP

respectively. These parameters can b e overridden by using the O rber generic interfaceContext or

defining an ACL (Access Control List). The latter always takes precedence if a local interface is

included (e.g. [ tcp out, "10.0.0.0/8", ["10.0.0.1"] ]). If the interface is excluded (e.g.

[

tcp out, "10.0.0.0/8"

]), the interface chosen will, in the following order, be determined by

#IOP ServiceContext

,ip address local/iiop ssl ip address local or the configuration of

the underlying system.

Adding th e interface cont ext, for generated stubs/skeletons, is done in th e follow ing wa y:

Ctx = #IOP_ServiceContext{context_id = ?ORBER_GENERIC_CTX_ID,

context_data = {interface, "10.0.0.1"}},

CosNaming_NamingContext:resolve(NS, [{context, [Ctx]}], Name),

It is also possible to add the context to corba:string to object/2,

corba:resolve initial references/2, corba:resolve initial references remote/3,

corba:list initial services remote/2, corba object:not existent/2,

corba object:non existent/2and corba object:is a/3. The operations exported by corba object

are affected if the supplied IOR is external. The function corba:string to object/2 might require

the interface context if a corbalocor a corbalocstring is passed (See the INS [page 49] chapter),

while corba:resolve initial references remote/3and corba:list initial services remote/2

alway s connect t o another O RB and it might be necessary t o add the context. The remainingcorba

operations are affected if calls are re-directed by setting the orbInitRefand/or orbDefaultInitRef

configuration parameters. For more information, see the Reference Manual for each module.

Configuring which interface(s) that shall be used when exporting an IOR to another ORB, isdetermined by nat ip address, setting the fl ag 16#1000 [page 17] and ip address, in that order.

Orber listens for incoming connections either via all interfaces or the interface defined by ip address.

It is also possible to add and remove extra listen interfaces by using orber:add listen interface/2/3

an d orber:remove listen interface/1. In this case one should set the 16#1000 flag and, if necessary,

set the confi guration parameters

local, DefaultNATIPAddress, [

IPAddress, NATIPAddress

]

and/or

local, DefaultNATPort, [

Port, NATPort

]

.


8/13/2019 orber

28/206

Chapter 3:


8/13/2019 orber

29/206

Chapter 4

4.1 OMG IDL to Erlang Mapping - Overview

The purpose of OMG IDL, I nterface D efinit ion L anguage, mapping is to a ct as t ranslator betw eenplatform s and languages. An ID L specifi cation is supposed to describe data t ypes, object ty pes etc.

CORBA is independent of the programming language used to construct clients or implementations. Inorder to use the O RB, it is necessary for programmers to know h ow to access O RB functionality from

their programming languages. It t ranslates different ID L constructs to a specific p rogramming language.

This chapter describes the ma pping of O MG ID L constructs to the Erlang programming language.

4.2 OMG IDL Mapping Elements

A complete language mapping w ill allow the programmer to have access to all O RB f unctionality in a

way that is convenient for a specified programming language.

All mapping must define the following elements:

All OMG IDL basic and constructed types

References to constants defined in OMG IDL

References to objects defined in OM G ID L

Invocations of operations, including passing of parameters and receiving of results

Exceptions, including w hat happens when an operation raises an exception and how the

exception pa rameters are a ccessed

Access to attributes

Signatures for operations defined b y the O RB, such as dynamic invocation interface, t he object

adapters etc.

Scopes; O MG ID L has several levels of scopes, w hich are mapped t o Erlangs tw o scopes.

4.3 Getting Started

To begin wit h, w e should decide w hich ty pe of objects (i.e. servers) w e need and if tw o, or more,

should export the same functionality. Let us assume that w e wa nt to create a system for D B (dat abase)

access for different kind of users. For example, anyone with a valid password may extract data, but only

a few may update the DB. Usually, an application is defined within a module, and all global dataty pes

are defined on the top-level. To begin w ith w e create a m odule and t he interfaces w e need:


8/13/2019 orber

30/206

Chapter 4:

// DB IDL

#ifndef _DB_IDL_

#define _DB_IDL_

// A module is simply a container

module DB {

// An interface maps to a CORBA::Object.

interface CommonUser {

};

// Inherit the Consumer interface

interface Administrator : CommonUser {

};

interface Access {

};

};

#endif

Since th eAdministratorshould be able to do t he same things as theCommonUser, the previous inherits

from the latter. The Access interface will grant access to the DB. Now we are ready to define the

functionality and data types we need. But, this requires that we know a little bit more about the OMG

I DL.

Note:

The O MG defi nes a set of reserved case insensitive key-w ords, which m ay N O Tbe used as identifiers(e.g. module name). For more information, see Reserved Compiler Names and Keywords [page 42]

4.4 Basic OMG IDL Types

The O MG ID L mapping is strongly ty ped and, even if you have a good knowledge of CO RBA types, it

is essential to read carefully the following mapping to Erlang types.

The mapping of basic types is straightforward. Note that the OMG IDL double type is mapped to an

Erlang fl oat w hich does not support t he full double value range.

O MG ID L type Erlang type Note

fl oat Erlang fl oat

double Erlang fl oat value range not supported

short Erlang integer -2^15 .. 2^15-1

unsigned short Erlang integer 0 .. 2^16-1

long Erlang integer -2^31 .. 2^31-1

continued ...


8/13/2019 orber

31/206

8/13/2019 orber

32/206

Chapter 4:

// Null terminated

typedef string myString;

typedef wstring myWString;

// Maximum length 10

typedef string myString10;

typedef wstring myWString10;

If w e w ant to define a char/string or w char/w string constant, w e can use octal (\O OO - one, tw o or

three octal digits), hexadecimal (\xHH - one or two hexadecimal digits) and unicode (\uHH HH - one,

two, three or four hexadecimal digits.) representation as well. For example:

const string SwedensBestSoccerTeam = "\101" "\x49" "\u004B";

const wstring SwedensBestHockeyTeam = L"\101\x49\u004B";

const char aChar = \u004B;

const wchar aWchar = L\u004C;

Nat urally, w e can use"Erlang",L"Rocks", A a nd LAas w ell.

4.5.2 Sequence Data Type

A sequence can be defined to be of a maximum length or unbounded, and may contain Basic and

Template typ es and scoped names:

typedef sequence aShortSequence;

typedef sequence aLongSequence;

typedef sequence anEvenLongerSequence;

4.5.3 Array Data Type

Arrays are multidimensional, fi xed-size arrays. The indices is language mapping specifi c, w hich is w hyone should not pass them as arguments to another O RB.

typedef long myMatrix[2][3];

4.5.4 Fixed Data Type

A Fixed Point literal consists of an integer part (decimal digits), decimal point and a fraction part

(decimal digits), followed by a Do r d. Either the integer part or t he fraction part may be missing; th e

decimal point may be missing, but not d/D . The integer part m ust be a p ositive integer less than 32.

The Fraction part must be a positive integer less than or equal to the Integer part.

const fixed myFixed1 = 3.14D;

const fixed myFixed2 = .14D;

const fixed myFixed3 = 0.14D;

const fixed myFixed4 = 3.D;

const fixed myFixed5 = 3D;

It is also possible to u se unary ( + -) and binary (+ -*/) opera to rs:


8/13/2019 orber

33/206

8/13/2019 orber

34/206

Chapter 4:

But what should, for example, the lookupoperation return? O ne option is to use the any data type.

But, depending on w hat kind of data it encapsulates, t his datatype can be rather expensive to use. We

might find a solution to our problems among the ConstructedIDL types.

4.6 Constructed OMG IDL Types

C onstructed ty pes all have native mappings as show n in the table below.

Type ID L code M aps to Erlang code

struct struct myStruct long a; short b;

; void op(in myStruct a);

E rla ng rec ord o k = o p(O b j, # m yS tru ct

a= 300,

b= 127

),

union union myUnion switch(long) case 1: long a;

; void op(in myU-

nion a);

E rla ng rec ord o k = o p(O b j, # m yU n io n

label= 1,

value= 66

),

enum enum myEnum one, two ; void

op(in myEnum a);

E rla ng a t om o k = o p( O b j, o ne) ,

Table 4.3: O MG ID L constructed types

4.6.1 Struct Data Type

A structmay h ave Basic, Template, Scoped N ames and C onstructed t ypes as members.

4.6.2 Enum Data Type

The max imum number of identifiers w hich may defined in an enumeration is 2. The order in w hich theidentifiers are named in the specification of an enumeration defines the relative order of t he identifiers.

4.6.3 Union Data Type

A unionmay consist of:

Identifier

Switch - may be an integer, char, boolean, enum or scoped name.

Body - with or without a defaultcase; may appear at most once.

A case label must mat ch th e defined t ype of t he discriminator, and may only contain a default case if

the values given in the non-default labels do not cover the entire range of the unions discriminant type.For exa mple:

// Illegal default; all cases covered by

// non-default cases.

union BooleanUnion switch(boolean) {

case TRUE: long TrueValue;

case FALSE: long FalseValue;

default: long DefaultValue;

};


8/13/2019 orber

35/206

4.6: Constructed OMG IDL Types

// OK

union BooleanUnion2 switch(boolean) {

case TRUE: long TrueValue;

default: long DefaultValue;

};

It is not necessary to list all possible values of the union discriminator in the body. Hence, the value of a

union is the value of the discriminator and, in given order, one of the following:

1. If the d iscriminator mat ch a label, explicitly listed in a case statement, th e value must be of th e

same type.

2. If the union contains a default label, the value must m atch t he type of th e default label.

3. No value. O rber then inserts the Erlang atom undefined in the value field when receiving a union

from an external ORB.

The above can be summed up t o:

// If the discriminator equals 1 or 2 the value

// is a long. Otherwise, the atom undefined.

union LongUnion switch(long) {

case 1:

case 2: long TrueValue;

};

// If the discriminator equals 1 or 2 the value

// is a long. Otherwise, a boolean.

union LongUnion2 switch(long) {

case 1:

case 2: long TrueValue;

default: boolean DefaultValue;

};

Warning:Every fi eld in, for example, a struct must be initiated. O therw ise it w ill be set to the at om

undefined, w hich O rber cannot encode when communicating via IIO P. In the exam ple above,

invoking the opertion w ith #my Struct

a= 300

w ill fail (equal to #myStruct

a= 300,

b= undefined

)

Now w e can continue to w ork on our ID L specification. To begin w ith, w e should determine the return

value of the lookupoperation. Since th eany type can be rather expensive we can use astructo r a

unioninstead. If w e intend t o return the same information about a employee every t ime w e can use astruct. Let us assume that the D B contains the name, address, employee number and department.

// DB IDL

#ifndef _DB_IDL_

#define _DB_IDL_

module DB {

typedef unsigned long EmployeeNo;


8/13/2019 orber

36/206

Chapter 4:

enum Department {Department1, Department2};

struct employee {

EmployeeNo No;

string Name;

string Address;

Department Dpt;

};

typedef employee EmployeeData;

interface CommonUser {

EmployeeData lookup(in EmployeeNo ENo);

};

interface Administrator : CommonUser {

void delete(in EmployeeNo ENo);

};

interface Access {

typedef string UserID;

typedef string Password;

// Since Administrator inherits from CommonUser

// the returned Object can be of either type.

CommonUser logon(in UserID ID, in Password PW);

};

};

#endif

We can also define exceptions (i.e. not system exception) thrown by each interface. Since exceptions

are thoroughly described in t he chapter System a nd U ser D efined Exceptions [page 71], w e choose not

to. H ence, w e are now ready to compile our ID L-fi le by invoking:

$ erlc DB.idl

or:

$ erl

Erlang (BEAM) emulator version 5.1.1 [threads:0]

Eshell V5.1.1 (abort with ^G)

1

ic:gen(DB).

ok


8/13/2019 orber

37/206

4.7: Scoped Names and Generated Files

2 halt().

The next step is to implement our servers. B ut, t o be able to d o that , w e need to know how w e can

access data type definitions. For example, since a struct is mapped to an Erlang record we must include

an hrl-file in our callback module.

4.7 Scoped Names and Generated Files

4.7.1 Scoped Names

Within a scope all identifiers must be unique. The following kinds of definitions form scopes in the

O M G I D L :

module

interface

operation

valuetype

struct

union

exception

For example, since enumerants do not form a scope, the follow ing ID L code is not valid:

module MyModule {

// two is not unique

enum MyEnum {one, two};

enum MyOtherEnum {two, three};};

But, since Erlang only has two levels of scope, modulean d function, the O MG ID L scope is mapped asfollows:

Function Scope- used for constants, operations and attributes.

Erlang M odule Scope- the Erlang module scope handles the remaining OM G ID L scopes.

An Erlang module, corresponding to a n ID L global name, is derived by converting occurencies of :: to

underscore, and eliminating the leading ::. Hence, accessing MyEnum from another module, one use

MyModule::MyEnum

For example, an operation foo defined in interface I , which is defined in module M, w ould be w ritten in

I DL asM::I::fooand asM I:fooin Erlang -foo is the function name and M Iis the name of the

Erlang module. Applying th is know ledge to a stripped version of th e D B.idl gives:


8/13/2019 orber

38/206

Chapter 4:

// DB IDL

#ifndef _DB_IDL_

#define _DB_IDL_

// ++ topmost scope ++

// IC generates oe_XX.erl and oe_XX.hrl.

// XX is equal to the name of the IDL-file.

// Tips: create one IDL-file for each top module

// and give the file the same name (DB.idl).

// The oe_XX.erl module is used to register data

// in the IFR.

module DB {

// ++ Module scope ++

// To access EmployeeNo from another scope, use:

// DB::EmployeeNo, DB::Access etc.

typedef unsigned long EmployeeNo;

enum Department {Department1, Department2};

// Definitions of this struct is contained in:

// DB.hrl

// Access functions exported by:

// DB_employee.erl

struct employee {

... CUT ...

};

typedef employee EmployeeData;

... CUT ...

// If this interface should inherit an interface

// in another module (e.g. OtherModule) use:

// interface Access : OtherModule::OtherInterface

interface Access {

// ++ interface scope ++

// Types within this scope is accessible via:

// DB::Access::UserID

// The Stub/Skeleton for this interface is

// placed in the module:

// DB_Access.erl

typedef string UserID;

typedef string Password;

// Since Administrator inherits from CommonUser

// the returned Object can be of either type.

// This operation is exported from:

// DB_Access.erl

CommonUser logon(in UserID ID, in Password PW);

};


8/13/2019 orber

39/206

4.7: Scoped Names and Generated Files

};

#endif

U sing underscores in ID L names can lead t o amb iguities due to th e name ma pping described above. It

is advisable to avoid the use of underscores in identifiers. For example, the following definition would

generate tw o structures namnedx y z.

module x {

struct y_z {

...

};

interface y {

struct z {

...

};

};};

4.7.2 Generated Files

Several files can be generated for each scope.

An Erlang source code file (.erl) is generated for top level scope as well as the Erlang header file.

An Erlang header fi le (.hrl) will be generated for each scope. The header file will contain record

definitions for all struct, uniona nd exceptiontypes in that scope.

Modules that contain at least one constant defi nition, w ill produce Erlang source code fi les (.erl).

That Erlang fi le will contain constant functions for that scope. Modules that contain no constantdefinitions are considered empty and no code w ill be produced for them, but only for their

included mod ules/interf aces.

Interfaces will produce Erlang source code files ( .erl), this code w ill contain all operation stub

code and implementation functions.

In addition to the scope-related files, an Erlang source file will be generated for each definition of

the typesstruct, unionand exception(these are t he ty pes that w ill be represented in Erlang as

records). This file will contain special access functions for that record.

The top level scope will produce two files, one header file ( .hrl) and one Erlang source file

(.erl). These fi les are named as the ID L fi le, prefixed w ithoe .

After compiling D B.idl, t he following fi les have been generated:

oe DB.hrland oe DB.erlfor the top scope level.

DB.hrlfor the module DB .

DB Access.hrland DB Access.erlfor the interface DB Access.

DB CommonUser.hrl an d DB CommonUser.erl for th e interfaceDB CommonUser.

DB Administrator.hrl an d DB Administrator.erl for the interface DB Administrator.

DB employee.erlfor th e structureemployeein module DB .


8/13/2019 orber

40/206

Chapter 4:

Since th eemployeestruct is defined in the top level scope, the Erlang record definition is found in

DB.hrl. IC also generat es stu bs/skeleton s (e.g. DB CommonUser.erl) and access functions for some

datatypes (e.g. DB employee.erl). H ow the stubs/skeletons are used is th oroughly described in

Stub s/Skeletons [page 66] and Module Interface [pa ge 122].

4.8 Typecode, Identity and Name Access Functions

As mentioned in a previous section, struct, uniona nd exception types yield record definitions and

access code for that record. For struct, union, exception,arraya nd sequencetypes, a special file is

generated that holds access functions for TypeCode,Identityand Name. These functions are put in the

fi le corresponding to the scope w here they are defined. For example, t he module DB employee.erl,

representing t he employeestruct, exports the follow ing functions:

tc/0 - returns the typ e code for t he struct.

id/0 - returns th e IFR identity of the struct. In th is case the ret urned value is

"IDL:DB/employee:1.0", but if the struct was defined in the scope of CommonUser, th e result

would be"IDL:DB/CommonUser/employee:1.0". However, the user usually do not need to know

the Id, just w hich Erlang module contains the correct Id.

name/0 - returns the scoped name of the struct. The employeestruct name is"DB employee".

Type C odes are, for example, used in Any [page 128] values. Hence, we can encapsulate the employee

struct in an any type by:

%% Erlang code

....

AnEmployee = #DB_employee{No = 1,

Name = "Adam Ivan Kendall",

Address = "Rasunda, Solna",

Dpt = Department1},

EmployeeTC = DB_employee:tc(),EmployeeAny = any:create(EmployeeTC, AnEmployee),

....

For mo re informat ion, see the Type C ode listing [page 43].

4.9 References to Constants

Constants are generated as Erlang functions, and are accessed by a single function call. The functions

are put in the fi le corresponding to the scope w here they are defined. There is no need for an object t o

be started t o access a constant.

Example:

// m.idl

module m {

const float pi = 3.14;

interface i {

const float pi = 3.1415;

};

};


8/13/2019 orber

41/206

4.10: References to Objects Defined in OMG IDL

Since t he tw o constants are defi ned in different scopes, t he ID L code above is valid, but not necessarily

a good approach. After compilingm.idl, the constant definitions can be extracted b y invoking:

$ erlc m.idl

$ erlc m.erl

$ erl

Erlang (BEAM) emulator version 5.1.1 [threads:0]

Eshell V5.1.1 (abort with ^G)

1 m:pi().

3.14

2 m i:pi().

3.1415

3 halt().

4.10 References to Objects Defined in OMG IDL

Objects are accessed by object references. An object reference is an opaque Erlang term created and

maintained by the ORB.

O bjects are implemented by providing implementations for all operations and att ributes of the O bject,

see operation implementation [page 36].

4.11 Exceptions

Exceptions are handled as Erlang catch and throw s. Exceptions are translated to messages over an IIOP

bridge but converted back to a t hrow on th e receiving side. O bject implementations that invoke

operations on other objects must be aware of the possibility of a non-local return. This includesinvocation of ORB and IFR services. See also the Exceptions [page 71] section.

Exception parameters are mapped as an Erlang record and accessed as such.

An object implementation that raises an exception will use the corba:raise/1function, passing the

exception record as parameter.

4.12 Access to Attributes

Attributes are accessed through their access functions. An attribute implicitly defines the geta nd set

operations. These operations are handled in the same way as normal operations. The getoperation is

defined as a readonlyat tribute.

readonly attribute long RAttribute;

attribute long RWAttribute;

The RAttributerequires that you implement, in your call-back module, get RAttribute. For the

RWAttributeit is necessary to implement get RWAttributeand set RWAttribute.


8/13/2019 orber

42/206

Chapter 4:

4.13 Invocations of Operations

A standard Erlang gen serverbehavior is used for object implementation. The gen server state is

then used as th e object internal state. Implementation of the object function is achieved by

implementing its methods and attribute operations. These functions will usually have the internal state

as their first parameter, followed b y a ny ina nd inoutpa rameters.

D o not conf use the object internal stat e w ith its object reference. The object internal state is an Erlang

term which has a format defined by the user.

Note:It is is not alw ays the case that the internal state w ill be the fi rst parameter, as stubs can use their ow n

object reference as the fi rst parameter (see the IC documentation).

A function call w ill invoke an operation. The fi rst parameter of t he function should be t he object

reference and then allin a nd inoutparameters follow in the same order as specified in t he ID L

specification. The result will be a return value unless the function has inouto rout parametersspecified; in w hich case, a tuple of t he return value, followed b y t he parameters will be returned.

Example:

// IDL

module m {

interface i {

readonly attribute long RAttribute;

attribute long RWAttribute;

long foo(in short a);

long bar(in char c, inout string s, out long count);

void baz(out long Id);

};};

Is used in Erlang as :

%% Erlang code

....

Obj = ... %% get object reference

RAttr = m_i:_get_RAttribute(Obj),

RWAttr = m_i:_get_RWAttribute(Obj),

ok = m_i:_set_RWAttribute(Obj, Long),

R1 = m_i:foo(Obj, 55),

{R2, S, Count} = m_i:bar(Obj, $a, "hello"),....

Note how the inoutparam eter is passedandreturned. There is no way to use a single occurrence of avariable for this in Erlang. Also note, that ok, O rbers representation of t he ID L-type void, must be

returned by baza nd set RWAttribute. These operations can be implemented in the call-back

module as:


8/13/2019 orber

43/206

4.14: Implementing the DB Application

_set_RWAttribute(State, Long) ->

{reply, ok, State}.

_get_RWAttribute(State) ->

{reply, Long, State}.

_get_RAttribute(State) ->

{reply, Long, State}.

foo(State, AShort) ->

{reply, ALong, State}.

bar(State, AShort, AString) ->

{reply, {ALong, "MyString", ALong}, State}.

baz(State) ->

{reply, {ok, AId}, State}.

The operations may require more arguments (depends on IC options used). For more information, seeStub s/Skeletons [page 66] and Module Interface [page 122].

Warning:A function can also be defined to be oneway, i.e. asynchronous. But, since the behavior of a oneway

operation is not defined in th e O MG specifications (i.e. the behavior can differ depending on w hich

other O RB O rber is communicating w ith), one should avoid using it.

4.14 Implementing the DB ApplicationNow w e are ready to implement t he call-back modules. There are three modules we must create:

D B Access impl.erl

D B C ommonUser impl.erl

D B Administrator impl.erl

An easy w ay to accomplish that, is to use the IC backend erl template, w hich w ill generate a

complete call-back module. One should also add the same compile options, for example thiso rfrom,

used w hen generating t he stub /skeleton m odules:

$> erlc +"{be,erl_template}" DB.idl

We begin with implementing the DB Access impl.erl module, w hich, if w e used erl template, will

look like the follow ing. All we need to d o is to add the logic to the logonoperation.


8/13/2019 orber

44/206

Chapter 4:

%%----------------------------------------------------------------------

%%

%%

%% $Id$

%%

%%----------------------------------------------------------------------

%% Module : DB_Access_impl.erl

%%

%% Source : /home/user/example/DB.idl

%%

%% Description :

%%

%% Creation date: 2005-05-20

%%

%%----------------------------------------------------------------------

-module(DB_Access_impl).

-export([logon/3]).

%%----------------------------------------------------------------------

%% Internal Exports

%%----------------------------------------------------------------------

-export([init/1,

terminate/2,

code_change/3,

handle_info/2]).

%%----------------------------------------------------------------------

%% Include Files

%%----------------------------------------------------------------------

%%----------------------------------------------------------------------

%% Macros

%%----------------------------------------------------------------------

%%----------------------------------------------------------------------

%% Records

%%----------------------------------------------------------------------

-record(state, {}).

%%======================================================================

%% API Functions%%======================================================================

%%----------------------------------------------------------------------

%% Function : logon/3

%% Arguments : State - term()

%% ID = String()

%% PW = String()

%% Returns : ReturnValue = OE_Reply

%% OE_Reply = Object_Ref()

%% Raises :


8/13/2019 orber

45/206


%% Description:

%%----------------------------------------------------------------------

logon(State, ID, PW) ->

%% Check if the ID/PW is valid and what

%% type of user it is (Common or Administrator).

OE_Reply

= case check_user(ID, PW) of

{ok, administrator} ->

DB_Administrator:oe_create();

{ok, common} ->

DB_CommonUser:oe_create();

error ->

%% Here we should throw an exception

corba:raise(....)

end,

{reply, OE_Reply, State}.

%%======================================================================

%% Internal Functions%%======================================================================

%%----------------------------------------------------------------------

%% Function : init/1

%% Arguments : Env = term()

%% Returns : {ok, State} |

%% {ok, State, Timeout} |

%% ignore |

%% {stop, Reason}

%% Raises : -

%% Description: Initiates the server

%%----------------------------------------------------------------------

init(_Env) ->

{ok, #state{}}.

%%----------------------------------------------------------------------

%% Function : terminate/2

%% Arguments : Reason = normal | shutdown | term()

%% State = term()

%% Returns : ok

%% Raises : -

%% Description: Invoked when the object is terminating.

%%----------------------------------------------------------------------

terminate(_Reason, _State) ->

ok.

%%----------------------------------------------------------------------

%% Function : code_change/3

%% Arguments : OldVsn = undefined | term()

%% State = NewState = term()

%% Extra = term()

%% Returns : {ok, NewState}

%% Raises : -


8/13/2019 orber

46/206

Chapter 4:

%% Description: Invoked when the object should update its internal state

%% due to code replacement.

%%----------------------------------------------------------------------

code_change(_OldVsn, State, _Extra) ->

{ok, State}.

%%----------------------------------------------------------------------

%% Function : handle_info/2

%% Arguments : Info = normal | shutdown | term()

%% State = NewState = term()

%% Returns : {noreply, NewState} |

%% {noreply, NewState, Timeout} |

%% {stop, Reason, NewState}

%% Raises : -

%% Description: Invoked when, for example, the server traps exits.

%%----------------------------------------------------------------------

handle_info(_Info, State) ->

{noreply, State}.

SinceDB Administrator inherits from DB CommonUser, w e must implement deletein the

DB Administrator impl.erlmodule, and lookupin

DB Administrator impl.erlandDB CommonUser impl.erl. But wait, is that really necessary? Actually,it is not. We simple use the IC compile option impl:

$ erlc +

impl, "DB::CommonUser"

, "DBUser impl"

+

impl, "DB::Administrator"

, "DBUser impl"

DB.

$ erlc *.erl

Instead of creating, a nd not the least, maintaining tw o call-back modules, w e only have to deal w ith

DBUser impl.erl. If w e generated t he templates, w e simply renameDB Administrator impl.erlt oDBUser impl.erl. See also the Exceptions [page 71] chapter. In the following example, only the

implementation of the API functios are shown:

%%======================================================================

%% API Functions

%%======================================================================

%%----------------------------------------------------------------------

%% Function : delete/2


%% ENo = unsigned_Long()

%% Returns : ReturnValue = ok

%% Raises :%% Description:

%%----------------------------------------------------------------------

delete(State, ENo) ->

%% How we access the DB, for example mnesia, is not shown here.

case delete_employee(No) of

ok ->

{reply, ok, State};

error ->

%% Here we should throw an exception if


8/13/2019 orber

47/206


%% there is no match.

corba:raise(....)

end.

%%----------------------------------------------------------------------

%% Function : lookup/2


%% ENo = unsigned_Long()

%% Returns : ReturnValue = OE_Reply

%% OE_Reply = #DB_employee{No,Name,Address,Dpt}

%% No = unsigned_Long()

%% Name = String()

%% Address = String()

%% Dpt = Department

%% Department = Department1 | Department2

%% Raises :

%% Description:

%%----------------------------------------------------------------------

lookup(State, ENo) ->%% How we access the DB, for example mnesia, is not shown here.

case lookup_employee(ENo) of

%% We assume that we receive a DB_employee struct

{ok, Employee} ->

OE_Reply = Employee,

{reply, OE_Reply, State};

error ->

%% Here we should throw an exception if

%% there is no match.

corba:raise(....)

end.

After you have compiled both call-back modules, and implemented the missing functionality (e.g.

lookup employee/1), w e can test our a pplication:

%% Erlang code

....

%% Create an Access object

Acc = DB_Access:oe_create(),

%% Login is Common user and Administrator

Adm = DB_Access:logon(A, "admin", "pw"),

Com = DB_Access:logon(A, "comm", "pw"),

%% Lookup existing employee

Employee = DB_Administrator:lookup(Adm, 1),

Employee = DB_CommonUser:lookup(Adm, 1),

%% If we try the same using the DB_CommonUser interface

%% it result in an exit since that operation is not exported.

{EXIT, _} = (catch DB_CommonUser:delete(Adm, 1)),

%% Try to delete the employee via the CommonUser Object

{EXCEPTION, _} = (catch DB_Administrator:delete(Com, 1)),


8/13/2019 orber

48/206

8/13/2019 orber

49/206

8/13/2019 orber

50/206

Chapter 4:

... continued

tk sequence, ElemTC, Length

tk sequence, tk long, 4

tk array, ElemTC, Length

tk array, tk char, 9

tk alias, IFRId, N ame, TC

tk alias, ID L:T1:1.0, T1, tk short

tk except, IFRId, Name, [

ElemName, El-

emTC ]

tk except, IDL:Exc1:1.0, Exc1, [

a, tk long

,

b, tk string, 0 ]

Table 4.5: Type C ode t uples


8/13/2019 orber

51/206

Chapter 5

5.1 Overview of the CosNaming Service

The CosNaming Service is a service developed to help users and programmers identify objects by

human readable names rather than by a reference. By binding a name t o a naming context (another

object), a contextual reference is formed. This is helpful when navigating in the object space. In

addit ion, identifying objects by name allow s you to evolve and/or relocate objects with out client code

modification.

The CosNaming service has some concepts that are important:

namebinding- a name to object association.

nami ng context- is an object that contains a set of name bindings in w hich each name is unique.D ifferent names can be bound to t he same object.

to bind a name- is to create a name binding in a given context.

to resolve a nam e- is to d etermine the ob ject associated w ith t he name in a given context.

A name is always resolved in a context, there no absolute names exist. Because a context is like any

other object, it can also be bound t o a name in a naming context. This will result in a naming graph (adirected graph with notes and labeled edges). The graph allows more complex names to refer to an

object. G iven a context, you can use a sequence to reference an object. This sequence is henceforth

referred to asnameand the individual elements in the sequence asname components. All but the lastname component are bound to naming contexts.

The diagram in figure 1 illustrates how the Naming Service provides a contextual relationship between

objects, NamingContexts and NameBindings to create an object locality, as the object itself, has no

name.


8/13/2019 orber

52/206

Chapter 5:

Figure 5.1: Figure 1: C ontext ual object relat ionships using the N aming Service.

The naming contexts provide a directory of contextual reference and naming for objects (an object can

appear to have more th an one name).

In fi gure 1 the object to the right can either be calledalphafrom one context or gamma from another.


8/13/2019 orber

53/206

5.2: The Basic Use-cases of the Naming Service

The N aming Service has an initial naming context, w hich is show n in th e diagram as t he t op-most

object in the naming graph. It has two names betaand epsilon, which are bound to other naming

contexts. The initial naming context is a w ell known location used to share a common nam e space

between multiple programs. You can traverse the naming graph until you reach a name, which is bound

to an object, which is not a naming context.

We recommend readingchapter 12 , C O RBA Fundamentals and Programmi ng, for detailed informationregarding the Naming Service.

5.2 The Basic Use-cases of the Naming Service

The b asic use-cases of t he N aming S ervice are:

Fetch initial reference to the naming service.

Creating a naming context.

Binding and unbinding names to objects.

Resolving a name to an object.

Listing the bindings of a naming context.

D estroying a naming context.

5.2.1 Fetch Initial Reference to the Naming Service

In order to use the naming service you have to fetch an initial reference to it. This is done with:

NS = corba:resolve_initial_references("NameService").

Note:NS in th e ot her use-cases refers to this initial reference.

5.2.2 Creating a Naming Context

There are tw o functions for creating a naming context. The fi rst function, w hich only creates a nam ing

context object is:

NC = CosNaming_NamingContext:new_context(NS).

The other function creates a naming context and binds it t o a name in an already existing namingcontext (t he initial context in this example):

NC = CosNaming_NamingContext:bind_new_context(NS, lname:new(["new"])).


8/13/2019 orber

54/206

Chapter 5:

5.2.3 Binding and Unbinding Names to Objects

The follow ing steps illustrate how to bind/unbind a n object reference to/from a name. For the exam ple

below, assume that the NamingContexts in the path are already bound to the name

/workgroup/services, and that reference to the services context are in the variable Sc.

1. Use the naming library functions to create a name

Name = lname:new(["object"]).

2. Use CosNaming::NamingContext::bind() to bind a name to an object

CosNaming_NamingContext:bind(Sc, Name, Object).

3. Use CosNaming::NamingContext::unbind() to remove the NameBinding from an object

CosNaming_NamingContext:unbind(Sc, Name).

Note:

O bjects can have more than one name, t o indicate different paths to the same object.

5.2.4 Resolving a Name to an Object

The following steps show how to retrieve the object reference to the service context above

(/w orkgro up/services).

1. Use the naming library functions to create a name pat h:

Name = lname:new(["workgroup", "services"]).

2. Use C osNaming::Nam ingC ontext::resolve() to t o resolve the name to an object

Sc = CosNaming_NamingContext:resolve(NS, Name).

An alternative is to use:

Sc = corba:string_to_object("corbaname:rir:/NameService#workgroup/services/").

The corbanameschema is described further in the Interoperable Naming Service section.

5.2.5 Listing the Bindings in a NamingContext

1. Use C osNaming::NamingCont ext::list() to list a ll the bindings in a context

The following code retrieves and lists up to 10 bindings from a context.

{BList, BIterator} = CosNaming_NamingContext:list(Sc, 10).

lists:foreach(fun({{Id, Kind},BindingType}) -> case BindingType of

nobject ->

io:format("id: %s, kind: %s, type: object~n", [Id, Kind]);

_ ->

io:format("id: %s, kind: %s, type: ncontext~n", [Id, Kind])

end end,

Blist).


8/13/2019 orber

55/206

5.3: Interoperable Nami

Documents

orber