BoilerPlate: Reusable CORBA

BoilerPlate API Documentation

1.1

Introduction
How to use BoilerPlate
Supported Platforms
Building BoilerPlate

Introduction

BoilerPlate is a C++ framework that encapsulates CORBA bootstrapping. This includes code to initialize the ORB, and initialize any number of POAs using various policy perturbations. The policy combinations are pre-constructed in various types of ServantFactory. There are three types of Servant Factories:

• Simple - Persistant POA configured with the PERSISTENT Lifecycle policy
• ServantActivator - For POAs that use a ServantActivator
• ServantLocator -- For POAs that use a ServantLocator

Each type of ServantFactory can have individual Thread and Id Assignment policies. The default is ORB_CTRL_MODEL and USER_ID.
Top

How do I use BoilerPlate

Using the BoilerPlate framework is easy. All you need to do is a small implemenation that inherits one of the ServantFactory patterns and then a small mainline that instances the OrbInit class. You pass pointers to your ServantFactory-s to OrbInit and then tell it to build them. Your ServantFactory implementation contains the code that you wrote to instance your Servants. It can be as simple or as complicated as your application requires.

• Step 1 - Implement a class that inherits from a ServantFactory
• Step 2 - Implement the required operations in your ServantFactory. This can be different depending on the pattern you want to use. For ServantActivator patterns you would implement the _build_activator operation. In it you would instance your ServantActivator. For ServantLocator patterns you would implement the _build_locator operation analogous to the ServantActivator _build_activator. The Simple pattern requires an implementation of _build_servants.
• Step 3 - Implement your mainline. You instance the OrbInit class and add pointers to your ServantFactory-s to it. Then tell OrbInit to build them. OrbInit will call each ServantFactory in the order they were added and then call orb->run.

Supported Platforms

BoilerPlate currently supports Cygwin, HPUX 11i (PA-RISC), and RedHat Linux. Supported ORBs include ORBacus 4, MICO 2.3.9+, and TAO. Support for OmniORB will be added very soon.
Top

Building

BoilerPlate uses GNU Autotools to configure the BoilerPlate build. We are new to the Autotools so if you have any problems let us know.

Configuring Your ORB

Before running configure you need to do some preparation so that the configure script can pick up you ORB. For MICO you need to do very little if you have run the MICO install from the Makefile. MICO creates a configuration script that the BoilerPlate configure script sources. If you haven't run the MICO install or are using ORBacus follow the directions below.

• Create a file called <your-orb>-setup.sh. You can put this file anywhere on your file system. If you ran the MICO install, this file can be found in the <install-dir>/lib directory. If you accepted the defaults you can find the file in /user/local/lib.
• This file must contain the following entries:

   <ORB-NAME>DIR=<base directory of your orb installation>
   <ORB-NAME>SHAREDDIR=<base directory to header files. e.g., /usr/local>
   <ORB-NAME>VERSION=x.y.z
   CPPFLAGS=<additional flags for your pre-processor>
   CXXFLAGS=<additional flags for your compiler>
   IDLFLAGS=<additional flags for you IDL compiler. Be careful!>
   LIBS=<additional -L and -l flags for your linker>
   # 
   # export all of the above
  

For example for TAO:

 ACE_ROOT=/opt/ACE_wrappers
 TAO_ROOT=/opt/ACE_wrappers/TAO
 export ACE_ROOT TAO_ROOT

 TAODIR=$ACE_ROOT
 TAOSHARTDIR=$ACE_ROOT/orbsvcs
 TAOVERSION=`sed -n /version/ {y/b/./; s#^.*\([0-9]\.*\), .*$#\1#p; }` \
             "$ACE_ROOT/VERSION" `
 PATH=${ACE_ROOT}/bin:${PATH}
 LD_LIBRARY_PATH=${ACE_ROOT}/lib:${LD_LIBRARY_PATH:-}
 SHLIB_PATH=${ACE_ROOT}/lib:${SHLIB_PATH:-}
 LIBPATH=${ACE_ROOT}/lib:${LIB_PATH:-}
 CPLUS_INCLUDE_PATH=${ACE_ROOT}/include
 LIB_PATH=${ACE_ROOT}/lib

 CPPFLAGS=
 CXXFLAGS=
 IDLFLAGS=
 LDFLAGS=
 LIBS=

 export TAOVERSION PATH LD_LIBRARY_PATH CPLUS_INCLUDE_PATH LIBRARY_PATH
 export SHLIB_PATH LIB_PATH TAO_DIR
 export CPPFLAGS CXXFLAGS IDLFLAGS LDFLAGS LIBS

• Run ./configure --with-<your-orb>=path_to_env_file
• Send email to BoilerPlate Support if you have questions or problems.
  Top

Threading Models

BoilerPlate allows configurable threading models and custom threading models.

• Use a built in BoilerPlate OrbRunStrategy
• Roll your own OrbRunStrategy

There are two built-in threading models

• BasicOrbRunStrategy - Calls ORB::run with the main thread. For ORBs that use thread pool strategies by default this strategy is sufficient. The thread that was allotted to the process by the operating system is used to call ORB::run.
• ThreadedOrbRunStrategy - Uses a configurable number of threads to call ORB::run. This strategy is used for ORBs that are highly configurable like TAO. By default TAO does not deploy multiple threads in the ORB. If you don't supply a threading mechanism yourself, TAO processes are single threaded.
• Custom Strategy - If the two built-in strategies are not sufficient, you can define your own OrbRunStrategy by inheriting the OrbRunStrategy interface. You instance your implementation at runtime and pass the OrbRunStrategy pointer to OrbInit during intialization. The pointer must be heap allocated as OrbInit will assume ownership and delete the pointer when OrbInit shuts down.

Configuration Options

• -BPthdstrategy=mtorbrun To use the ThreadedOrbRunStrategy. You must accompany this option with the number of threads by using -BPmtorbstrat_himark=pos_integer.
• -BPthdstrategy=basicorbrun To use the BasicOrbRunStrategy.
• No option is necessary for a custom option. But you can define your own options for your custom solution.

---