source: main/trunk/greenstone2/runtime-src/src/corba/README@ 25232

16 March 2011
ak19

----------------------------------------------------------------------------------------------------------------------------
    Contents of this README file
----------------------------------------------------------------------------------------------------------------------------

1. How to compile up Corba, including generating the helper files from the *.idl interface source file (corbaiface.idl):
2. How to run the corbaserver and the corbarecptldd (the client) against it
3. How to view the "IOR" value in the objid/ref file in a human-readable format
4. Suggestions for future testing
5. About Greenstone 2's java-client



----------------------------------------------------------------------------------------------------------------------------
    General information
----------------------------------------------------------------------------------------------------------------------------

This is the README that goes with the Greenstone Corba code, especially with the updates that have been made to it at this time.

Many changes have been made to different parts of the corba code since we had to change over Mico's implementation of corba from version 2.3.5 to 2.3.13. Even Mico-2.3.13 required modifications to get it to compile as well as to compile with new versions of gcc (version 4.6.* as opposed to just 4.4.*).

Further, in order to bring the corba code up-to-speed with the equivalent changes that had already been made to the rest of Greenstone runtime-src code, the corbaiface.idl file has been updated with new data structures and member variables to existing ones. Corresponding (de)serialisation functions and updates to processing code have been made to corbatext_t.h and *.mpp and corbaproto.mpp.

With these changes, corba now compiles again at last (tested on Linux CentOS 64 bit machine), and when the "corbaserver" is run against the client "corbarecptldd" locally (on the same machine), things still work.
The remote case is not working at present. However, we can't get the remote case to work for the hello-1 demo example found in Mico either, though that similarly works locally.
Suggestions for future testing in this area are at the bottom.


----------------------------------------------------------------------------------------------------------------------------
    How to compile up Corba, including generating the helper files from the *.idl interface source file (corbaiface.idl):
----------------------------------------------------------------------------------------------------------------------------

1. The helper files are now generated by a new target in the runtime-src/src/corba/Makefile.in which is dependent on the corbaiface.h and corbaiface.mpp files: if corbaiface.h is modified or corbaiface.mpp is missing, the IDL executable will be run over corbaiface.idl.

You can touch the corba/corbaiface.idl (or else delete corbaiface.mpp, but not corbaiface.h!) and then run "make" again to re-run IDL and re-generate the necessary files.

2. Assuming the corbaiface.idl related files are up-to-date, as is the case when checking out from SVN at the time of writing, compilation of corba code will occur if greenstone is configured with the --enable-corba flag, followed by make and make install as usual.

For example:

greenstone2> ./configure --enable-apache-httpd --enable-corba --disable-wvware
(wvware generally to be disabled when compiling on 64 bit linux)

greenstone2> make

greenstone2> make install

Running "make install" copies the executables corbaserver and corbarecptldd (the client) into cgi-bin\linux

3. If you want to run Greenstone Mico's IDL executable over another *.idl file at any stage, you will need to set the PATH and LD_LIBRARY_PATH to contain the necessary locations to Greenstone's Mico first:

> export PATH=/my/greenstone2/runtime-src/packages/mico/bin:$PATH
> export LD_LIBRARY_PATH=/my/greenstone2/runtime-src/packages/mico/lib:$LD_LIBRARY_PATH

Now you can run Mico's IDL over your *.idl interface file as follows:
> idl <idl-options> <file.idl>



----------------------------------------------------------------------------------------------------------------------------
    How to run the corbaserver and the corbarecptldd (the client) against it
----------------------------------------------------------------------------------------------------------------------------

1. Your Greenstone's CORBA should have been compiled up as explained above.

2. Open 2 x-terms. In both, you need set the LD_LIBRARY_PATH to Greenstone Mico's lib:
> export LD_LIBRARY_PATH=/my/greenstone2/runtime-src/packages/mico/lib:$LD_LIBRARY_PATH

3. In the first x-term, run the server:

/my/greenstone2>export LD_LIBRARY_PATH=/my/greenstone2/runtime-src/packages/mico/lib:$LD_LIBRARY_PATH
/my/greenstone2>cd cgi-bin/linux
/my/greenstone2/cgi-bin/linux>./corbaserver

The server will now be listening. It will print out some stuff to the screen, but it will also have generated a file in /tmp called "localcorba.objid" containing the IOR value that clients need to use to connect to it.
Greenstone does not at present make use of a NameService to resolve "where" the server is so that clients can know how to connect to them. Instead, the *.objid (or *.ref) file is shared about between client and server. The client uses the IOR value in this file to locate and communicate with the server.
In Greenstone, the client program (corbarecptldd) EXPECTS the file to be in /tmp and to have the extension *.objid. The only thing it still requires is the name of the file, which is "localcorba" by default.
Therefore:

4. In the second x-term, run the client corbarecptldd with this filename as parameter:
/my/greenstone2> export LD_LIBRARY_PATH=/my/greenstone2/runtime-src/packages/mico/lib:$LD_LIBRARY_PATH
/my/greenstone2> cd cgi-bin/linux
/my/greenstone2/cgi-bin/linux>./corbarecptldd localcorba

(Note: Do not give /tmp/localcorba.objid as parameter. No location or suffix is to be provided, and no other location or suffix will be accepted.)

The client will print some headers and expect you to press Enter, after which it will print more HTML and then terminate.
In the server's x-term, you will notice that it has processed the incoming request from the client's end by printing more stuff to the screen.

5. To quit the server, send Ctrl-C to the x-term wherein the server is run.



----------------------------------------------------------------------------------------------------------------------------
    How to view the "IOR" value in the objid/ref file in a human-readable format
----------------------------------------------------------------------------------------------------------------------------

1. Get opalOrb from http://sourceforge.net/projects/opalorb/files/

2. Its Util/catior.pl file, when run over a file containing the IOR value, will print the contents in a human-readable format.

The catior.pl script is explained at http://opalorb.sourceforge.net/Util/catior.pl.html

Usage:
~/Desktop> opalOrb/Util/catior.pl <IOR ref file>

Example:
~/Desktop> opalOrb/Util/catior.pl /tmp/localcorba.objid



----------------------------------------------------------------------------------------------------------------------------
    Suggestions for future testing
----------------------------------------------------------------------------------------------------------------------------

One idea is to try out another example found at http://www.mario-konrad.ch/wiki/doku.php?id=programming:corba:connect_orbs
which makes use of a NameServer and which may work when client and server run remote from each other. 

I was unable to test this, since the example code at the link didn't compile (after commenting out the need for omniORB and restricting code to Mico). The compilation process failed looking for a file Cos*, which was not in the Mico 2.3.13 installation. Perhaps the example work with an older version of Mico like 2.3.5.



----------------------------------------------------------------------------------------------------------------------------
    About Greenstone 2's java-client
----------------------------------------------------------------------------------------------------------------------------

1. The gs2-java-client can be obtained from Greenstone's SVN repository. It's README file is http://trac.greenstone.org/browser/other-projects/gs2-java-client/trunk/README

2. It will not work at present, its code not having been updated to work with the changes mentioned at the start of this file.
The first thing that will need to change is its outdated *.idl. This needs to be replaced with an replica of Greenstone 2's runtime-src/src/corba/corbaiface.idl

3. Having updated the corbaiface.idl file in the java-client, the (de)serialisation code for the member variables in this must be brought up to speed, just as Greenstone's corbaproto.mpp file was changed. Refer to this file (runtime-src/src/corba/corbaproto.mpp and possible corbatext_t.h and corbatext_t.mpp for ideas on the changes that need to be made.)

A ticket has been added to the Greenstone SVN about how the gs2-java-client needs to be updated.