ISIS technical report series, Vol. 24, April, 2000Practical tutorial for using CorbaA step-by-step introduction to the Common Object Request Broker ArchitectureJan van GemertIntelligent Sensory Information SystemsDepartment of Computer ScienceUniversity of AmsterdamThe NetherlandsA compact step-by-step tutorial for creating a CORBA objectto get some hands-on experience with the Common Object Request Broker Architecture. Corba enables platform, language andnetwork transparency. How to use a C object created on aWindows NT, in a Java program running on Unix.

Practical tutorial for using CorbaContents1 Introduction1.1 Description of files used . . . . . . . . . . . . . . . . . . . . . . . . .1.2 Applications used . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1222 Install Orbacus 4.0 beta 22.1 Installing Orbacus for the C server . . . . . . . . . . . . . . . . .2.2 Installing Orbacus for the Java client . . . . . . . . . . . . . . . . . .3343 Environmental Changes3.1 Variable settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3.2 MS visual C settings . . . . . . . . . . . . . . . . . . . . . . . . .3.3 Orbacus configuration files . . . . . . . . . . . . . . . . . . . . . . . .55674 Specify the object in IDL95 Setting up the C Server5.1 Compile IDL file . . . . . . . .5.2 Implement the servant object .5.2.1 Example of Count i.h .5.2.2 Example of Count i.cpp5.3 Implement the server . . . . . .5.3.1 Server.cpp code . . . . .101010111213146 Setting up the Java Client6.1 Compile IDL file . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6.2 Implement the client . . . . . . . . . . . . . . . . . . . . . . . . . . .6.2.1 code . . . . . . . . . . . . . . . . . . . . . . . . . .151515167 Running the example17.Intelligent Sensory Information SystemsDepartment of Computer ScienceUniversity of AmsterdamKruislaan 4031098 SJ AmsterdamThe Netherlandstel: 31 20 525 7463fax: 31 20 525 ponding author:Jan van Gemerttel: 31(20)525 [email protected]/ jvgemert

Section 1 Introduction11IntroductionThis small practical tutorial is a doorway to the world of the Common Object Request Broker Architecture. Yes young Java Knight, this will give you the powersto use transparent inter-language client-server relationships between objects. Thisdocument provides a framework for implementing a simple count object, containinga number that can be set, read and incremented by 1. The idea of this simple objectwas found in [1]. The choice for such an object, is based on its simplicity as itsdisplay of client-server interaction.What you have here, is no theoretical work, nor does it explain in detail howCORBA uses its magic. It’s just a step by step practical tutorial for creating aCORBA C server with a Java client. Its small steps are backed up with somechunks of fast-food files, just waiting to be compiled and executed.For further information about CORBA, check the included file.Additionally, I recommend these sites: of CORBA) of this CORBA From now on, the CORBA fundamentals are presumed as known. You do nothave to master the details of it, just a grasp of the basics is enough. Do you knowwhat an IOR is? What is IDL used for? Skeletons? Stubs? Etc. Furthermore, someunderstanding of Java, C and Microsoft Visual C (MSVC) is required. Forinformation about them, I recommend these ion.aspHere also, no expertise is really required. Just know how to create and compilea new Visual C project, compile and run Java code, and know how to write asimple C class.Exception handling is mainly not done in this tutorial, in order to focus on themain goal of implementing a CORBA object. This document will allow you to createa working implementation of the CORBA architecture, in a small amount of time.The University of Amsterdam disclaims any warranty and takes no responsibilityfor damages of any kind for the software based upon this tutorial.Section 1 will guide you through the installation and compilation of Orbacus4.0 beta 2. Where section 2 will let you adapt the environmental conditions to letOrbacus flourish. section 3 specifies the Count object in the Interface DefinitionLanguage. Where the IDL definition is compiled to C in order to set up theserver in section 4. The client is implemented in section 5. Whereas the executionof the example is described in section 6.

2Jan van Gemert1.1Description of files usedFile:LearnCorba.docLicence.docOB-4 0b2.zipJOB-4 0b2 jars.zipOB-4.0b3.pdf.zipCount.idlCount i[.cpp .h]Server[.cpp us.propertiesorbacusClient.bat1.2Description:This tutorial document;License agreement for free use of Orbacus;Orbacus source code for C ;Orbacus precompiled .Jar files for Java;Documentation file for Orbacus ;Language independent definition of the object;C Implementation of the count-object;Code of the C Server;MS visual C project and workspace files;System Properties for Orbacus for C ;Batch file for Sever Variable settings;Code of the Java Client;System Properties for Orbacus for Java;Batch file for Client variable settings.Applications used MS Windows NT MS Word Acrobat reader WinZip Microsoft visual C JDK1.2.2.

Section 2 Install Orbacus 4.0 beta 223Install Orbacus 4.0 beta 2The first thing to do, is to install Orbacus. Without it, not much corbaing can bedone. The Orbacus files were downloaded from the Object Oriented Concepts site,the implementers of Orbacus. The URL of their site: ThisORB, (Object Request Broker, a Corba implementation) is free for non-commercialuse, like in this tutorial. For more details about this, take a look at the filelicence.doc.2.1Installing Orbacus for the C serverSupplemented with this package is a .zip file called OB-4 This file contains the C source code of the Orbacus 4.0 for C . To properly install Orbacus,we have to unzip, configure and compile the source code. 1To Do:1Unzip the file OB-4 to a directory of your choice (e.g.D:\OrbacusSrc). A sub-directory is created, called OB-4.0b2;2Edit the file config\Make.rules.mak according to the instructions in the comments in that file and make the appropriatechanges. At least set the installation directory. For example set itto prefix D:\OOCb4;3Open a DOS box, and run the batch file vcvars32.bat (includedin MSVC) to set compilation environmental variables;4In DOS, Go to the Orbacus source directory (OB-4.0b2) Compile Orbacus, using ’nmake /f Makefile.mak install’ (thiswill take some time, for me about 50 minutes, but you shouldbe able to continue with this tutorial until IDL-file compilation).This will install Orbacus in the prefix directory (e.g. D:\OOCb4);5Recommended, use ’nmake /f Makefile.mak clean’ to deletefiles used during compilation which are no longer needed (willcreate some space on your drive).If all goes well, you should now have a compiled pile of about 75 MB of freshOrbacus in your installation directory. The source code is no longer necessary, so ifyouŕe lacking hard drive space you can delete at will.For more information about installing Orbacus, see the files INSTALL.WINDOWS,OB\README.WINDOWS and the file Makefile.mak.1According to the OOC help file, you need approximately 150 MB of free disk space (250 MBto be sure), and Windows NT (not win95/win98).

42.2Jan van GemertInstalling Orbacus for the Java clientThe file JOB-4 0b2 contains all the pre-compiled .jar files needed to useOrbacus for Java. So, all we need to do is to unzip the Jars and adapt the Classpathvariable used by Java to locate .jar files.To Do:1Unzip the file JOB-4 0b2 to a directory of your choice Client.bat)whichaddsthe OB.jar and the OBNaming.jar to the Classpath variable, and for example contains this line:SET CLASSPATH aming.jar;3Add to this bath file a line which inserts the executable directory in thesearch path (e.g. PATH %PATH%;D:\OOCb4\BIN). For easy access to theexecutables in this directory.

Section 3 Environmental Changes35Environmental ChangesThe working environment has to be adapted, in order to let Orbacus and Microsoftvisual C work together. Some variables need to be set, some MSVC settings gotto change and a configuration file has to be created.3.1Variable settingsIn order to let MSVC find Orbacus-libraries and includes, some variables have to beset. For this, the batch file OrbacusVars.bat is included in this package. This file: Sets a helpful MS-DOS variable OBC ROOT, not needed for Orbacus but makeslife easier in MSVC. This variable should contain the path to the installationdirectory of Orbacus (e.g. D:\OOCb4). This, so we can easy reference the pathto Orbacus in MSVC; Sets MSVC environment variables, (calls vcvars32.bat, which is included inthe bin directory of MSVC); Adds the Orbacus executables (OBC ROOT\bin) in the search path; Sets the ORBACUS CONFIG variable, which points to a configuration file usedby Orbacus. (this configuration file isnt́ standard included with Orbacus, sowe have to create it ourselves, more about this in section 3.3).OrbacusVars.bat:@echo offif not defined INCLUDE call vcvars32echo Setting environment for using ORBacus 4.0 beta2 for C rem if not already done, set MS-visual C vars,if not defined INCLUDE call vcvars32rem set root directory to 1e parameter, or to the defaultset OBC ROOT %1if not defined OBC ROOT set OBC ROOT D:\OOCb4rem add Orbacus binaries to search-pathset PATH %PATH%;%OBC ROOT%\binrem set location of configuration file.set ORBACUS CONFIG %OBC ROOT%\etc\orbacus.cfgTo Do:123Open a DOS box;Call OrbacusVars.bat. Make sure vcvars32.bat is in your path;Start MS Visual C (type msdev at the DOS prompt, so the dos-boxenvironment settings (variable values) sustain within MSVC).

6Jan van Gemert3.2MS visual C settingsMicrosoft Visual C also has to be configured, in order to work with Orbacus: The OBC ROOT variable has to be added to the include-path; The corresponding libraries have to be added to the project; Multithreading DLL has to be set; Run Time Type checking has to be enabled.To Do:12345678Start an empty workspace and a new win32 console project (e.g.server)Open the menu project settings;Set settings for: to all configurations (both debug and release);In tab C/C , category: Pre processor Set additional include Directoryto: ’., (OBC ROOT)\include’ (Yes, include the current directory (’.’ ) );In tab C/C , category code generation change the settinguse runtime library set to Multithreaded DLL;In tab C/C , category C language change the settingEnable Run-time Type Information (RTTI) to yes;Orbacus uses wsock32.lib so, add this library to tab Link, category Input add to the setting object/library modules the librarywsock32.lib;Add to the project, for example in the folder Resource files theneeded libraries ob.lib and CosNaming.lib. You can find these files inOBC ROOT\lib.Details:The reason for including the current directory in the include directory path, isthat Orbacus will generate files, which use the statement: #include count.h instead of #include "count.h". This does mean that the source files have to be in asystem directory of MSVC. By including the current directory, it is added to the system directories. The source files can now be in the same directory as the project files.Because we compiled Orbacus with the default settings, the compiler settingMultithreading DLL was used. We have to keep doing this in our project. Tochange this default compilation option, change the file config\Make.rules.makand re-compile Orbacus. For more details about multithreading options, refer tothe MSVC documentation and the file: OB\README.WINDOWS.Orbacus makes use of the wsock32.lib and uses Run Time Type checking Information.

Section 3 Environmental Changes3.37Orbacus configuration filesIn order to let Orbacus work with the naming service, which allows human objectnaming, instead of IOR strings, we have to specify some more settings.The naming service converts an object name to an IOR. In order to let Orbacusfind this naming service in its initial references, the IOR of the naming service hasto be known. Also, the IP-port on which the naming service will listen has to beset. This can be any free IP-port (e.g. 8001). For an example of an Orbacusconfiguration file, see below. Remember that the exact IOR of your naming serverwill differ from the example specified below.In the \BIN directory you can find the executable Nameserv.exe correspondingwith the naming service. By typing Nameserv -h you can see the options. Furthermore, the program nsadmin.exe lets you manage the naming service from thecommandline. Also, by typing nsadmin -h the options of the naming service administration program appear on the screen.To Do:1Print the IOR of the name service listening on port 8001 by typingNameserv -i -OAport 8001 (this will automatically start the namingservice, use ctrl-c to abort);2For the Server: Create a textfile with a filename specified asin the variable ORBACUS CONFIG in the variable settings (e.g.OBC ROOT\etc\orbacus.cfg );3Specify the ooc.service.NameService to the IOR just read of thenaming service in step 1;4Save the file, and make sure it has the same name and path as in thevariable ORBACUS CONFIG, and be sure not to break up the IOR, butleave it as a whole string;5For the Client: Create a textfile for example 6Set Orbacus as the ORB, insert the following lines in this file:ooc.omg.CORBA.ORBClass com.ooc.CORBA.ORBooc.omg.CORBA.ORBSingletonClass com.ooc.CORBA.ORBSingleton;7Also, specify in this file, the IOR of the name service inooc.orb.service.NameService . Just like the server configuration.Two different configuration files (one for C and one for Java) have no apparentuse on just one machine. When using a network, distributed file locations have theiradvantages over central stored settings.The Client configuration file, is just a system property list for Java, which canand will easily be loaded using the method java.util.Properties.load (more onthis in section 6).The location of the configuration files is not compulsory, just an easy way to store it.

8Jan van GemertExample of the Orbacus configuration file for C sever:(Lines starting with # are comment, and ignored)file: orbacus.cfg:# Initial references:ooc.service.NameService ample of the Orbacus configuration file for the Java client:(Lines starting with # are comment, and ignored)file: Using ORBacus ORB:org.omg.CORBA.ORBClass com.ooc.CORBA.ORBorg.omg.CORBA.ORBSingletonClass com.ooc.CORBA.ORBSingleton# set IOR of the nameservice:ooc.orb.service.NameService 060001000700010008000100090001000100010520000100

Section 4 Specify the object in IDL49Specify the object in IDLThe methods and properties of an object have to be known to both the server as theclient. The object has to be described in the Interface Definition Language (IDL).This description forms the foundation on which the server, client and objects arebuilt. The IDL file (Count.idl):module Counter{ interface Count{ attribute long sum;long increment();};};The object described, is a Count object. It is a simple object with only 1 methodand 1 attribute. An attribute in IDL is not like a real member variable of a class. Itgenerates a read and a write function with the same name of the attribute specifiedin IDL, which effect the servant objectś attribute. This attribute is a long calledsum, which can be incremented using the method increment, which also returns thenew value of the attribute.To Do:123456Create a text file count.idl and save it in the same directory as theproject (this in order to let MSVC find the include files in the currentdirectory, see section 3.2 );Add the IDL file to the project;Choose settings of the IDL file;Select the settings for all configurations (both debug and release)Select custom build and add to command:cd /D \ (InputDir) (OBC ROOT)\bin\idl (InputPath);Add to output: (InputDir)/ (InputName).h (InputDir)/ (InputName).cpp (InputDir)/ (InputName) skel.h (InputDir)/ (InputName) skel.cpp.All this is necessary, to compile the IDL file with the Orbacus IDL to C compiler (idl.exe) within MSVC, and to update the generated files automatically.

10Jan van Gemert5Setting up the C ServerTo set up a CORBA server the IDL file has to be compiled, in order to auto-generateServer Skeletons and Client Stubs. Also, the object implementation (servant) andthe server itself have to be written.5.1Compile IDL fileCompilation of the IDL file with the IDL-compiler as provided with Orbacus (BIN\idl.exe)generates a number of files needed to successfully implement object transparency.To Do:12Compile IDL file, with compile button, in MSVC.(note, if you try to build the entire project, the linker will complain thatit has nothing to link with);Add following generated files to your project:Count.hCount.cppCount skel.hCount skel.cpp;Count.* is used for the Client and for the Server. Count skel.* is used onlyfor the server and contains the abstract class of the implementation of the object.Count.h contains definitions of the IDL types.5.2Implement the servant objectThe implementation of the object, which by definition, is done by the server, is calleda servant object. The task of the servant is to create the functionality required bythe object, as defined in the IDL definition.To do so, we need to create a class, which inherits from the abstract server classCount skel. In the file Count skel.h we can see the virtual functions which needimplementing. A description of these functions: To request the value of the property sum: virtual CORBA::Long sum() ; To set the value of the property sum: virtual void sum(CORBA::Long itvar sum) ; To increment the value of the property sum, and return this value, the methodincrement: virtual CORBA::Long increment().

Section 5 Setting up the C Server11Now, we need to create the code for the implementation. Conform namingconventions, we create the files Count i.h and Count i.cpp:To Do:1234Create a new file in the project directory, Count i.h, and add it to theproject;Implement this headerfile.With above functions and a constructor (and facultative a destructor) inherit from the classpublic POA Counter::Count\verb in the file Count Skel.h. Includea private member to contain the sum-value. (an Example of this file isgiven below);Create a new file in the project directory, Count i.cpp and add it tothe project;Implement this file with the required code as specified in the headerfile.(An example of this file is given below.)All files are included in the package, so you can either make your own implementation, or use the one supplied.5.2.1Example of Count i.h#include OB/CORBA.h #include "Count skel.h"#include "iostream.h"// inherit from the Server class Countclass Count i : public POA Counter::Count{ public:// constructorCount i() ;// destructor Count i() ;// get sum valueCORBA::Long sum() ;// set sum valuevoid sum(CORBA::Long itvar sum) ;// increment sum valueCORBA::Long increment() ;private:long The Sum ;};

125.2.2Jan van GemertExample of Count i.cpp#include "Count i.h"Count i::Count i(){cout "Created Count object" endl ;this- The Sum 0 ;}Count i:: Count i(){cout "Gone is the Count object" endl ;}CORBA::Long Count i::sum(){// get value of sumreturn this- The Sum ;}void Count i::sum(CORBA::Long value){// set value of sumthis- The Sum value;}CORBA::Long Count i::increment(){// increment value of sum by 1this- The Sum ;return this- The Sum ;}

Section 5 Setting up the C Server5.313Implement the serverTo setup the server we have to: Initialize the ORB; Find a reference to the RootPOA.A portable object adapter (POA), provides the mechanism by which a serverprocess maps CORBA objects to language-specific implementation (servants); Create the servant object. The servant object is the implementation of theobject; Bind the servant object to a POA; Create and bind a name to the servant object;The namingService lets you associate names with objects. The namingServiceprovides the IOR of an object; Activate the POA manager; Run the ORB.See the next page, for an example of the server code.Now, you should be able to build the server code. For running the example, refer to section 7.

145.3.1Jan van GemertServer.cpp code#include OB/CORBA.h #include OB/CosNaming.h #include "Count i.h"#include iostream.h int main( int argc, char **argv) {// initialise the ORBCORBA::ORB var orb CORBA::ORB init(argc, argv);// finding rootPoaCORBA::Object var poaObject ;PortableServer::POA var poa ;poaObject orb- resolve initial references("RootPOA");poa PortableServer::POA:: narrow(poaObject) ;// Create CORBA object and use it to register// servant object reference with the POACount i servant ;poa- activate object(&servant) ;// Declare naming ContextCosNaming::NamingContextExt var rootCxtExt ;CORBA::Object var objVarNaming ;// get root NameServiceobjVarNaming orb- resolve initial references("NameService");rootCxtExt CosNaming::NamingContextExt:: narrow(objVarNaming) ;// add the count name to the root NameServiceCosNaming::Name var name ;name rootCxtExt- to name("The counter");// get object referenceCORBA::Object var c poa- servant to reference(&servant) ;// add object reference to counterrootCxtExt- bind(name, c);// use REbind if the nameservice is already initialized// only use bind the first time you bind an object// rootCxtExt- rebind(name, c);// print IOR of object, just in case.CORBA::String var str orb- object to string(c);cout str "\n" endl ;cout "Activating the POA manager.\n" endl;poa- the POAManager()- activate() ;orb- run() ;// the ORB will be waiting for requestsreturn 0 ;}

Section 6 Setting up the Java Client615Setting up the Java ClientTo set up a CORBA Client the IDL file has to be compiled, in order to automaticlygenerate Client Stubs. Also, the client has to be written.6.1Compile IDL fileCompilation of the IDL file with the IDL-compiler as provided with Orbacus (BIN\jidl.exe)generates a number of files needed to successfully implement object transparency.To Do:126.2Compile IDL file, on the command line withjidl --no-skeletons Count.idlno skeletons are required, cause we already have a C server;A directory Counter is created with the following the clientTo setup the client we have to: Initialize the ORB; Find a reference to the naming service; Create and use the object.See the next page, for an example of the client code.This client can be executed on any machine connected to the server. Just makesure the settings are correct.Now, you should be able to compile the client code. For running this example,refer to section 7.

166.2.1Jan van code// importing the used Orbacus packagesimport org.omg.CORBA.* ;import org.omg.CosNaming.* ;import* ;import Counter.* ;// importing the compiled idl-codepublic class Client {public static void setOrbacusProperties(java.util.Properties props)throws, {String javaHome System.getProperty("java.home");File propFile new ropFile new File(javaHome File.separator "lib" File.separator .out.println("Cannot find file:");else{FileInputStream fis new ing " // end setOrbacusProperties()public static void main(String args[]) {try{System.out.println("running client.\n");// load properties for Orbacus, and the location of the NamingServicejava.util.Properties props System.getProperties();setOrbacusProperties(props) ;System.out.println("init ORB.\n");org.omg.CORBA.ORB orb org.omg.CORBA.ORB.init(args, props);// connect to nameservice, get IOR of nameserviceSystem.out.println("\n connecting to nameservice.\n");org.omg.CORBA.Object objNaming orb.resolve initial references("NameService");NamingContext ncRef NamingContextHelper.narrow(objNaming);// find object ’The counter’NameComponent nc new NameComponent("The counter","");NameComponent path[] {nc};// create a counter objectCount counter CountHelper.narrow(ncRef.resolve(path));// Set sum to initial value of 0System.out.println("Setting sum to 0");counter.sum((int)0);// Calculate Start timelong startTime System.currentTimeMillis();// Increment 1000 timesSystem.out.println("Incrementing");for (int i 0 ; i 1000 ; i ) { counter.increment();}// Calculate stop time; print out statisticslong stopTime System.currentTimeMillis();System.out.println("Avg " ((stopTime - startTime)/1000f) " msecs");System.out.println("Sum " counter.sum());} catch (Exception e) { System.out.println("!Exception.: " e); }} // end main()} // end class Client

Section 7 Running the example717Running the exampleFor running this example, we have to do several things: Run the naming service, on the port earlier specified (e.g. 8001); Run the Server; Run the client.To Do:1234Run nameserv.exe -OAport 8001 in the OBC ROOT\BIN directory;Execute the server project in MSDEV;Compile the by typing javac Be sure tohave set your CLASSPATH correctly;Run the Client with java Client.On the screen of the server something appears like:init ORB.Created Count objectconnecting to 0001000100010520000100On the screen of the Client something appears like:running client.Loading orbacus.propertiesinit ORB.connecting to nameservice.Setting sum to 0IncrementingAvg 1.188 msecsSum 1000

18REFERENCESReferences[1] R Orfali and D Harkey. Client/Server Programming with Java and CORBA.Wiley, second edition, 1998.

20REFERENCESISIS reportsThis report is in the series of ISIS technical reports. The series editor is Rein vanden Boomgaard ([email protected]). Within this series the followingtitles are available:References[1] J.M. Geusebroek, A.W.M. Smeulders, F. Cornelissen, and H. Geerts.Segmentation of tissue architectureby distance graph matching. Technical Report 16, Intelligent SensoryInformation Systems Group, University of Amsterdam, 2000.[2] J.M. Geusebroek, F. Cornelissen,A.W.M. Smeulders, and H. Geerts.Robust autofocusing in microscopy.Technical Report 17, Intelligent Sensory Information Systems Group,University of Amsterdam, 2000.[3] J.M. Geusebroek, R. van den Boomgaard, A.W.M. Smeulders, and A.Dev. Color and scale: The spatialstructure of color images. TechnicalReport 18, Intelligent Sensory Information Systems Group, Universityof Amsterdam, 2000.[4] J.M. Geusebroek. A physical basisfor color constancy. Technical Report 19, Intelligent Sensory Information Systems Group, University ofAmsterdam, 2000.[5] J.M. Geusebroek, A.W.M. Smeulders, and R. van den Boomgaard.Color invariance.Technical Report 20, Intelligent Sensory Information Systems Group, University ofAmsterdam, 2000.[6] L. Todoran and M. Worring. Segmentation of color document images. Technical Report 21, Intelligent Sensory Information SystemsGroup, University of Amsterdam,2000.[7] A.W.M. Smeulders, M. Worring, S.Santini, A. Gupta, and R. Jain.Content based image retrieval at theend of the early years. Technical Report 22, Intelligent Sensory Information Systems Group, University ofAmsterdam, 2000.[8] C.B.J. Bergsma, G.J. Streekstra,A.W.M. Smeulders, and E.M.M.Manders. Velocity estimation ofspots in 3d confocal image sequencesof living cells. Technical Report 23,Intelligent Sensory Information Systems Group, University of Amsterdam, 2000.[9] J.C. van Gemert.

6 In tab C/C , category C language change the setting Enable Run-time Type Information (RTTI)toyes; 7 Orbacus uses wsock32.lib so, add this library to tab Link, cate-gory Input add to the setting object/library modules the library wsock32.lib; 8 Add to the project, for examp