Home

The omniORB version 4.1 User's Guide

1. public inline Echo_i virtual Echo_i virtual char echoString const char mesg y char Echo_i echoString const char mesg return CORBA string_dup mesg There are four points to note here Storage Responsibilities A string which is used both as an in argument and the return value of echoString is a variable size data type Other examples of variable size data types include sequences type any etc For these data types you must be clear about whose responsibility it is to allocate and release the associated storage As a rule of thumb the client or the caller to the implementation functions owns the storage of all IN arguments the object implementation or the callee must copy the data if it wants to retain a copy For OUT ar guments and return values the object implementation allocates the storage and passes the ownership to the client The client must release the storage when the variables will no longer be used For details please refer to the C mapping specification Multi threading As omniORB is fully multithreaded multiple threads may perform the same upcall to your implementation concurrently It is up to your implementation 12 CHAPTER 2 THE BASICS to synchronise the threads accesses to shared data In our simple example we have no shared data to protect so no thread synchronisation is necessary Alternatively you can create a POA which has the SIN
2. Type Any allows one to delay the decision on the type used in an operation un til run time To use type any in IDL use the keyword any as in the following example IDL interface anyExample any testOp in any mesg y The operation testOp in this example can now take any value expressible in OMG IDL as an argument and can also return any type expressible in OMG IDL Type Any is mapped into C as the type CORBA Any When passed as an argument or as a result of an operation the following rules apply 95 96 CHAPTER 11 TYPE ANY AND TYPECODE In InOut Out Return const CORBA Any amp CORBA Any amp CORBA Any amp CORBA Any So the above IDL would map to the following C C class anyExample_i public virtual POA_anyExample public virtual anyExample_i virtual CORBA Any testOp const CORBA Any amp a anyExample_i y 11 1 2 Inserting and Extracting Basic Types from an Any The question now arises as to how values are inserted into and removed from an Any This is achieved using two overloaded operators lt lt and gt gt To insert a value into an Any the lt lt operator is used as in this example C CORBA Any an_any CORBA Long 1 100 an_any lt lt l Note that the overloaded lt lt operator has a return type of void To extract a value the gt gt operator is used as in this example where the An
3. WbBOA Generate BOA compatible skeletons Wbold Generate old CORBA 2 1 signatures for skeletons Wbold_prefix Map C reserved words with prefix _ rather than _cxx_ Wbkeep_inc_path Preserve IDL include paths in generated include directives Wbuse_quotes Use quotes in include directives e g foo rather than lt foo gt Again most of these are self explanatory 5 2 1 Stub skeleton files By default omniidl separates the normal stub and skeleton file the SK cc file from the dynamic stubs the DynSK cc file so applications that do not need support for Any and TypeCode for a particular IDL file do not waste space with unnecessary definitions It is possible to output both the normal stubs and the dynamic stubs to a single file by simply specifying the same extension for both files This command places both the normal stubs and the dynamic stubs in aSK ce omniidl bcxx Woa Wbd SK cc a idl 64 CHAPTER 5 THE IDL COMPILER 5 2 2 Module splicing On ancient C compilers without namespace support IDL modules map to C classes and so cannot be reopened For some IDL it is possible to splice reopened modules on to the first occurrence of the module so all module definitions are in a single class It is possible in this sort of situation module M1 interface I y module M2 interface J attribute M1 I ok y y module M1 interface K attribute I still_
4. threadPoolWatchConnection default 1 If non zero threads from the pool temporarily behave a bit like thread per connec tion after dispatching a call See section 8 4 2 for details acceptBiDirectionalGIOP default 0 4 5 SERVER SIDE OPTIONS 53 Determines whether a server will ever accept clients offers of bidirectional GIOP connections See section 8 8 unixTransportDirectory default tmp omni u Unix platforms only Selects the location used to store Unix domain sockets The Su is expanded to the user name unixTransportPermission default 0777 Unix platforms only Determines the octal permission bits for Unix domain sock ets By default all users can connect to a server just as with TCP supportCurrent default 1 omniORB supports the PortableServer Current interface to provide thread context information to servants Supporting current has a small but noticeable run time overhead due to accessing thread specific storage so this option allows it to be turned off objectTableSize default 0 Hash table size of the Active Object Map If this is zero the ORB uses a dynami cally resized open hash table This is normally the best option but it leads to less predictable performance since any operation which adds or removes a table entry may trigger a resize If set to a non zero value the hash table has the specified number of entries and is never resized Note that the hash table is open so this
5. you use a URI of the form corbaloc rir NameService 6 1 2 corbaname corbaname URIs cause string_to_object to look up a name in a CORBA Naming service They are an extension of the corbaloc syntax corbaname lt corbaloc location gt lt object key gt lt stringified name gt for example corbaname myhost NameService project example echo obj corbaname rir NameService project example echo obj The object found with the corbaloc style portion must be of type CosNaming NamingContext or something derived from it If the object key or rir name is NameService it can be left out Not 2089 as printed in OMG00 6 2 CONFIGURING RESOLVE_INITIAL_REFERENCES 69 corbaname myhost project example echo obj corbaname rir project example echo obj The stringified name portion can also be left out in which case the URI denotes the CosNaming NamingContext which would have been used for a look up corbaname myhost example com corbaname rir The first of these examples is the easiest way of specifying the location of a naming service 6 2 Configuring resolve_initial_references The INS specifies two standard command line arguments which provide a portable way of configuring ORB resolve_initial_references 6 2 1 ORBInitRef ORBInitRef takes an argument of the form lt Objectld gt lt ObjectURI gt So for example with command line arguments of ORBInitRef NameService corbaname myhost
6. The following code frag ment shows how it is used CORBA ORB_ptr orb CORBA ORB_init argc argv CORBA Object_var initServ initServ orb gt resolve_initial_references NameService CosNaming NamingContext_var rootContext rootContext CosNaming NamingContext _narrow initServ There are escaping rules to cope with id and kind fields which contain and characters See chapter 6 of this manual and chapter 3 of the CORBA services specification as updated for the Interoperable Naming Service OMG00 20 CHAPTER 2 THE BASICS Remember omniORB constructs its internal list of initial references at initialisa tion time using the information provided in the configuration file omniORB cfg or given on the command line If this file is not present the internal list will be empty and resolve_initial_references will raise a CORBA ORB InvalidName exception 2 10 2 The Naming Service Interface It is beyond the scope of this chapter to describe in detail the Naming Service in terface You should consult the CORBA services specification OMG98 chapter 3 The code listed in eg3_impl cc and eg3_clt cc are good examples of how the service can be used Please spend time to study the examples carefully 2 11 Example 4 Using tie implementation templates omniORB supports tie implementation templates as an alternative way of provid ing servant classes If you use the wbtp option
7. fe line lt lt endl cerr lt lt mesg lt lt fe errmsg lt lt endl return 0 IAAAAAAAAAAAAA AAA AAA AAA A AAA AAA AAA ASA AAA AAAAAAAAAA AAA AAA AAA LLALL static CORBA Boolean CHAPTER 2 THE BASICS bindObjectToName CORBA ORB_ptr orb CORBA Object_ptr objref CosNaming NamingContext_var rootContext ERV cit Obtain a reference to the root context of the Name servic CORBA Object_var obj obj orb gt resolve_initial_references NameService Narrow the reference returned rootContext CosNaming NamingContext _narrow obj if CORBA is_nil rootContext cerr lt lt Failed to narrow the root naming context lt lt endl return 0 catch CORBA NO_RESOURCES amp cerr lt lt Caught NO_RESOURCES exception You must configure omniORB lt lt with the location lt lt endl lt lt of the naming service lt lt endl return 0 catch CORBA ORB InvalidName amp This should not happen cerr lt lt Service required is invalid does not exist lt lt endl return 0 try Bind a context called test to the root context CosNaming Name contextName contextName length 1 contextName 0 id const char test string copied contextName 0 kind const char my_context string copied Note on kind The kind field is used to indicate the type of the object This is to
8. library and correctly set up certificates See the src examples ssl_echo direc tory for an example That directory contains a README file with more details Chapter 9 Code set conversion omniORB supports full code set negotiation used to select and translate between different character code sets for the transmission of chars strings wchars and wstrings The support is mostly transparent to application code but there are a number of options that can be selected This chapter covers the options and also gives some pointers about how to implement your own code sets in case the ones that come with omniORB are not sufficient 9 1 Native code sets For the ORB to know how to handle strings and wstrings given to it by the appli cation it must know what code set they are represented with so it can properly translate them if need be The defaults are ISO 8859 1 Latin 1 for char and string and UTF 16 for wchar and wstring Different code sets can be chosen at initiali sation time with the nat iveCharCodeSet and nativeWCharCodeSet param eters The supported code sets are printed out at initialisation time if the ORB traceLevel is 15 or greater For most applications the defaults are fine Some applications may need to set the native char code set to UTF 8 allowing the full Unicode range to be supported in strings Note that the default for wchar is always UTF 16 even on Unix platforms where wchar is a 32 bit type Select the UCS
9. lt lt cerr lt lt cerr lt lt return 0 catch CORBA cerr lt lt Caught Sys catch CORBA cerr lt lt Caught files line mesg tem CO CO fatall om RBA niORB lt lt fe lt lt fe lt lt fe Exceptiong ex 23 lt lt ex _name lt lt endl Exception amp ex RBA Exception Exception amp fe lt lt ex name lt lt endl fatalException lt lt endl file lt lt endl line lt lt endl errmsg lt lt endl 24 CHAPTER 2 THE BASICS 2 12 2 eg2_impl cc eg2_impl cc This is the source code of example 2 used in Chapter 2 Sf The Basics of the omniORB user guide This is the object implementation Lh Usage eg2_impl On startup the object reference is printed to cerr as a stringified IOR This string should be used as the argument to eg2_clt include lt echo hh gt T ifdef HAVE_STD include lt iostream gt using namespace std else include lt iostream h gt endif class Echo_i public POA_Echo public inline Echo_i virtual Echo_i virtual char echoString const char mesg y char Echo_i echoString const char mesg cout lt lt Upcall lt lt mesg lt lt endl return CORBA string_dup mesg IAAAAAAAAAAAAAAA AAA AAA AAA AAA AAA A
10. lt lt line lt lt fe line lt lt endl cerr lt lt mesg lt lt fe errmsg lt lt endl return 0 IAAAAAAAAAAAA AA SSSI IIIS SALSA SSSA SASL AAA LLLI LLALLA static CORBA Object_ptr getObjectReference CORBA ORB_ptr orb CosNaming NamingContext_var rootContext ELY 4 Obtain a reference to the root context of the Name service CORBA Object_var obj obj orb gt resolve_initial references NameService Narrow the reference returned rootContext CosNaming NamingContext _narrow obj 34 CHAPTER 2 THE BASICS if CORBA is_nil rootContext cerr lt lt Failed to narrow the root naming context lt lt endl return CORBA Object _nil catch CORBA NO_RESOURCES amp cerr lt lt Caught NO_RESOURCES exception You must configure omniORB lt lt with the location lt lt endl lt lt of the naming service lt lt endl return 0 catch CORBA ORB InvalidNameg ex This should not happen cerr lt lt Service required is invalid does not exist lt lt endl return CORBA Object _nil Create a name object containing the name test context CosNaming Name name name length 2 name 0 id const char test string copied name 0 kind const char my_context string copied name 1 id const char Echo name 1 kind const char Object Note o
11. lt lt endl lt lt The Echo object replied lt lt char dest lt lt lt lt endl IAAAAAAAAAAAAAAA AAA AAA LL ILLIA int main int argc char argv try Initialise the ORB CORBA ORB_var orb CORBA ORB_init argc argv Obtain a reference to the root POA CORBA Object_var obj orb gt resolve_initial_references RootPOA PortableServer POA_var poa PortableServer POA _narrow obj We allocate the object on the heap Since this is a reference counted object it will be deleted by the POA when it is no longer needed Echo_i myecho new Echo_i Activate the object This tells the POA that this object is ready to accept requests PortableServer ObjectId_var myechoid poa gt activate_object myecho Obtain a reference to the object Echo_var myechoref myecho gt _this Decrement the reference count of the object implementation so that it will be properly cleaned up when the POA has determined that it is no longer needed myecho gt _remove_ref Obtain a POAManager and tell the POA to start accepting requests on its objects PortableServer POAManager_var pman poa gt the_POAManager pman gt activate 2 12 SOURCE LISTINGS Do the client side hello myechoref call Clean up all the resources orb gt destroy catch omniORB cerr lt lt Caught cerr
12. meaning that processing should continue with subsequent interceptors If an interceptor returns false later interceptors are not called You should only do that if you really know what you are doing Notice that the info_T contains references to omniORB internal data types The definitions of these types can be found in other header files within include omniORB4 and include omniORB4 internal 10 1 Interceptor registration All the interceptor singletons are registered within another singleton object of class omnilnterceptors You retrieve a pointer to the object with the omni0RB getInterceptors function which must be called after the ORB has been ini tialised with CORBA ORB_init but before the ORB is used The code to reg ister an interceptor looks for example like omnilnterceptors interceptors omniORB getInterceptors interceptors gt clientSendRequest add myInterceptorFunc 10 2 Available interceptors The following interceptors are available encodeIOR Called when encoding an IOR to represent an object reference This inter ception point allows the application to insert extra profile components into IORs Note that you must understand and adhere to the rules about data stored in IORs otherwise the IORs created may be invalid omniORB it self uses this interceptor to insert various items so you can see an exam ple of its use in the insertSupportedComponents function defined in src lib omniORB orbc
13. server lt lt endl catch CORBA SystemException amp ex cerr lt lt Caught a CORBA lt lt ex _name lt lt endl catch CORBA Exception amp ex cerr lt lt Caught CORBA Exception lt lt ex _name lt lt endl catch omniORB fatalException amp fe cerr lt lt Caught omniORB fatalException lt lt endl cerr lt lt file lt lt fe file lt lt endl cerr lt lt line lt lt fe line lt lt endl cerr lt lt mesg lt lt fe errmsg lt lt endl return 0 28 CHAPTER 2 THE BASICS 2 12 4 eg3_impl cc eg3_impl cc This is the source code of example 3 used in Chapter 2 Sf The Basics of the omniORB user guide This is the object implementation Lh Usage eg3_impl On startup the object reference is registered with the COS naming service The client uses the naming service to LL locate this object Sf The name which the object is bound to is as follows root context test context kind my_context Th Echo object kind Object LA include lt echo hh gt ifdef HAVE_STD include lt iostream gt using namespace std else include lt iostream h gt endif static CORBA Boolean bindObjectToName CORBA ORB_ptr CORBA Object_ptr class Echo_i public POA_Echo public inline Echo_i
14. virtual Echo_i virtual char echoString const char mesg y char Echo_i echoString const char mesg return CORBA string_dup mesg SISSSSSSSSAA ALAA AAAS LIISA SAIS AAA AAA AAAA SASS LLL AAA AAAS SSS 2 12 SOURCE LISTINGS 29 int main int argc char argv try CORBA ORB_var orb CORBA ORB_init argc argv CORBA Object_var obj orb gt resolve_initial_references RootPOA PortableServer POA_var poa PortableServer POA _narrow obj Echo_i myecho new Echo_i PortableServer ObjectId_var myechoid poa gt activate_object myecho Obtain a reference to the object and register it in the naming service obj myecho gt _this CORBA String_var x x orb gt object_to_string obj cout lt lt x lt lt endl if bindObjectToName orb obj return 1 myecho gt _remove_ref PortableServer POAManager_var pman poa gt the_POAManager pman gt activate orb gt run catch CORBA SystemException amp ex cerr lt lt Caught CORBA lt lt ex _name lt lt endl catch CORBA Exception amp ex cerr lt lt Caught CORBA Exception lt lt ex _name lt lt endl catch omniORB fatalException amp fe cerr lt lt Caught omniORB fatalException lt lt endl cerr lt lt file lt lt fe file lt lt endl cerr lt lt line lt lt
15. 1 short s y interface anyExample any testOp in any mesg y Upon compiling the above IDL with omniidl bcxx Wha the following overloaded operators are generated 1 void operator lt lt CORBA Any const testStruct 2 void operator lt lt CORBA Any amp testStruct 3 CORBA Boolean operator gt gt const CORBA Any const testStruct 4 Operators of this form are generated for all constructed types and for inter faces The first operator 1 copies the constructed type and inserts it into the Any The second operator 2 inserts the constructed type into the Any and then man ages it Note that if the second operator is used the Any consumes the constructed type and the caller should not use the pointer to access the data after insertion The following is an example of how to insert a value into an Any using operator 1 C CORBA Any an_any 98 CHAPTER 11 TYPE ANY AND TYPECODE testStruct t t l 456 t s 8 an_any lt lt t The third operator 3 is used to extract the constructed type from the Any and can be used as follows const testStruct tp if an_any gt gt tp cout lt lt testStruct 1 lt lt tp gt 1 lt lt endl cout lt lt s lt lt tp gt s lt lt endl else cout lt lt Unknown value contained in Any lt lt endl As with basic types if an attempt is made to extract a type from an Any tha
16. CORBA ORB_ptr orb static void hello Echo_ptr e if CORBA is_nil e cerr lt lt hello The object reference is nil n lt lt endl return CORBA String_var src const char Hello CORBA String_var dest e gt echoString src cerr lt lt I said lt lt char srce lt lt X lt lt endl lt lt The Echo object replied lt lt char dest lt lt X lt lt endl IAAAAAAAAAAAAAAA AAA AAA AAA AA AAA AAA AAA AAA AAA AAA NAAA AAA AAA AAA AAA AA ANN ASS 2 12 SOURCE LISTINGS 33 int main int argc char argv try CORBA ORB_var orb CORBA ORB_init argc argv CORBA Object_var obj getObjectReference orb ho_var echoref Echo _narrow obj ea Q for CORBA ULong count 0 count lt 10 count hello echoref orb gt destroy catch CORBA TRANSIENTS cerr lt lt Caught system exception TRANSIENT unable to contact the lt lt server lt lt endl catch CORBA SystemException amp ex cerr lt lt Caught a CORBA lt lt ex _name lt lt endl catch CORBA Exception amp ex cerr lt lt Caught CORBA Exception lt lt ex _name lt lt endl catch omniORB fatalException amp fe cerr lt lt Caught omniORB fatalException lt lt endl cerr lt lt file lt lt fe file lt lt endl cerr
17. Configuration fil ccscn rios tots drer s 415 Wind wWstegistiy lt ad RA 142 Tracing opion ea sa aa aa oe be beds ee a a eee wae T ALA CRC API 6 4 4 ese AAA eet AA ANA 4 3 Miscellaneous global options ake e coa ada a SS CUE OPUS lt lt ies hark s e RR EE A REY 45 Serverside options sir a RA eho e ee eS 4 5 1 Main thread selection 4 6 GIOP and interoperability options co merdr 4 7 System Exception Handlers 2s o ee Ew Re er ova AFL IVP ROGUES cs a a a ee es BS 4 7 2 CORBA TRANSIENT handlers 4 7 3 CORBA COMM_FAILURE 174 CORBA SystemException sois oerdssmtes 48 Location torwarding cos cee ee po be ae erig Ase dE a The IDL compiler SL COMO MUONS ieie eis Ke ee ee E ee NAAA 5 1 1 Preprocessor interactions 14 ce ee een Bbw a Bull WIndows IX lt a poca le at BH HS 5 1 2 Forward declared interfaces Dlo COMES Soc eG a e apaa ede a a A 52 Ce Decherd OOS ise tdi a 5 2 1 Stub skeleton files 6 0 ce ee sem Cee MOE 2 05 oy ka ae eee ee 5 2 3 Flattened tie classes 5 3 5 2 4 Generating example implementations Examples oco a eee ee CRE ae E OSS EE RK Interoperable Naming Service 6 1 6 2 6 3 6 4 6 5 Object URIS 4 4625 4h eee al BEE ROSS Rie ee EES Gi COPA e rira ce eae es hts Gd Bee we Pw a 61 2 GOTPARAMG os e ce Wad al ws Bw Wa ew Configur
18. a CloseConnection message before the con nection is closed the condition is an orderly shutdown If the message is not re ceived the condition is an abnormal shutdown In an abnormal shutdown the ORB should raise a COMM_FAILURE exception whereas in an orderly shutdown 8 6 TRANSPORTS AND ENDPOINTS 83 the ORB should not raise an exception and should try to re establish a new connec tion transparently omniORB implements these semantics completely However it is known that some ORBs are not yet able to distinguish between an orderly and an abnor mal shutdown Usually this is manifested as the client in these ORBs seeing a COMM_FAILURE occasionally when connected to an omniORB server The work around is either to catch the exception in the application code and retry or to turn off the idle connection shutdown inside the omniORB server 8 6 Transports and endpoints omniORB can support multiple network transports All platforms usually have a TCP transport available Unix platforms support a Unix domain socket transport Platforms with the OpenSSL library available can support an SSL transport Servers must be configured in two ways with regard to transports the trans ports and interfaces on which they listen and the details that are published in IORs for clients to see Usually the published details will be the same as the listening de tails but there are times when it is useful to publish different information Details are sel
19. active or can be activated by their POA with a servant manager A reference to a persistent object can be published and will remain valid even if the server process is restarted A POA s Lifespan Policy determines whether objects created within it are tran sient or persistent The Root POA has the TRANSIENT policy An alternative to creating persistent objects is to register object references in a naming service and bind them to fixed path names Clients can bind to the ob ject implementations at run time by asking the naming service to resolve the path names to the object references CORBA defines a standard naming service which is a component of the Common Object Services COS OMG98 that can be used for this purpose The next section describes an example of how to use the COS fa system exception is not caught the C runtime will call the terminate function This function is defaulted to abort the whole process and on some systems will cause a core file to be produced Run Time Type Identification The POA itself can be activated on demand with an adapter activator 2 10 EXAMPLE 3 USING THE NAMING SERVICE 19 Naming Service 2 10 Example 3 Using the Naming Service In this example the object implementation uses the Naming Service OMG98 to pass on the object reference to the client This method is far more practical than using stringified object references The full listing of the object implementation eg3_im
20. cfg or C omniMapper cfg on Windows omniMapper does not normally print anything the v option makes it verbose so it prints con figuration information and a record of the redirections it makes to standard out put The configuration file is very simple Each line contains a string to be used as an object key some white space and an IOR or any valid URI that it will redirect that object key to Comments should be prefixed with a character For example Example omniMapper cfg NameService IOR 000f InterfaceRepository IOR 0100 omniMapper can either be run on a single machine in much the same way as omniNames or it can be run on every machine with a common configuration file That way each machine s omniORB configuration file could contain the line ORBDefaultInitRef corbaloc localhost 6 5 Creating objects with simple object keys In normal use omniORB creates object keys containing various information in cluding POA names and various non ASCII characters Since object keys are sup posed to be opaque this is not usually a problem The INS breaks this opacity and requires servers to create objects with human friendly keys 72 CHAPTER 6 INTEROPERABLE NAMING SERVICE If you wish to make your objects available with human friendly URIs there are two options The first is to use omniMapper as described above in conjunc tion with a PERSISTENT POA The second is to create objects with the required keys yourse
21. code will need to do this createThread Called whenever the ORB creates a thread The info_T class for this inter ceptor is class info_T public virtual void run 0 y The interceptor function is called in the context of the newly created thread The function must call the info_T s run method to pass control to the thread body run returns just before the thread exits This arrangement allows the interceptor to initialise some per thread state before the thread body runs then release it just before the thread exits assignUpcallThread The ORB maintains a general thread pool from which threads are drawn for various purposes One purpose is for performing upcalls to application code in response to incoming CORBA calls The assignUpcallThread inter ceptor is called when a thread is assigned to perform upcalls In the thread per connection model the thread stays assigned to performing upcalls for the entire lifetime of the underlying network connection in the thread pool model threads are assigned for upcalls on a per call basis so this interceptor 94 CHAPTER 10 INTERCEPTORS is triggered for every incoming call As with the createThread interceptor the interceptor function must call the info_T s run method to pass con trol to the upcall When a thread finishes its assignment of processing upcalls it returns to the pool even in thread per connection mode so the same thread can be reas signed to perf
22. does not limit the number of active objects just how efficiently they can be located poaHoldRequestTimeout default 0 If a POA is put in the HOLDING state calls to it will be timed out after the speci fied number of milliseconds by raising a TRANSIENT exception Zero means no timeout supportBootstrapAgent default 0 If set true servers support the Sun bootstrap agent protocol 4 5 1 Main thread selection There is one server side parameter that must be set with an API function rather than a normal configuration parameter namespace omniORB void setMainThread 54 CHAPTER 4 OMNIORB CONFIGURATION AND API y POAs with the MAIN_THREAD policy dispatch calls on the main thread By de fault omniORB assumes that the thread that initialised the omnithread library is the main thread To choose a different thread call this function from the desired main thread The calling thread must have an omni_thread associated with it i e it must have been created by omnithread or omni_thread create_ dummy must have been called If it does not the function throws CORBA INITIALIZE Note that calls are only actually dispatched to the main thread if ORB run or ORB perform_work is called from that thread 4 6 GIOP and interoperability options These options control omniORB s use of GIOP and cover some areas where omni ORB can work around buggy behaviour by other ORBs maxGIOPVerson def
23. example com resolve_initial_references NameService will return a reference to the object with key NameService available on myhost example com port 2809 Since IOR format strings are considered URIs you can also say things like ORBInitRef NameService I0R 00ff 6 2 2 ORBDefaultInitRef ORBDefaultInitRef provides a prefix string which is used to resolve other wise unknown names When resolve_initial_references is unable to resolve a name which has been specifically configured with ORBInitRef it constructs a string consisting of the default prefix a character and the name requested The string is then fed to string_to_object So for example with a command line of ORBDefaultInitRef corbaloc myhost example com acall to resolve_initial_references MyService will return the object reference denoted by corbaloc myhost example com MyService Similarly a corbaname prefix can be used to cause look ups in the naming service Note however that since a character is always added to the prefix it is impossible to specify a look up in the root context of the naming service you have to use a sub context like 70 CHAPTER 6 INTEROPERABLE NAMING SERVICE ORBDefaultInitRef corbaname myhost example com services 6 3 omniNames 6 3 1 NamingContextExt omniNames supports the extended CosNaming NamingContextExt interface module CosNaming interface NamingContextExt NamingConte
24. implement code sets plus some derived classes that use look up tables to convert simple 8 bit and 16 bit code sets to Unicode When sending or receiving string data there are a total of four code sets in ac tion a native char code set a transmission char code set a native wchar code set and a transmission wchar code set The native code sets are as described above the transmission code sets are the ones selected to communicate with a remote ma chine They are responsible for understanding the GIOP marshalling formats as well as the code sets themselves Each of the four code sets has an object associated with it which contains methods for converting data There are two ways in which a string wstring can be transmitted or received If the transmission code set in action knows how to deal directly with the native code set the trivial case being that they are the same code set but more complex cases are possible too the transmission code set object can directly marshal or unmarshal the data into or out of the application buffer If the transmission code set does not know how to handle the native code set it converts the string wstring into UTF 16 and passes that to the native code set object or vice versa All code set implementations must therefore know how to convert to and from UTF 16 With this explanation the classes in codeSets h should be easy to under stand The next place to look is in the various existing code set implement
25. lt lt t cout lt lt Sending Any containing testStruct l lt lt t l lt lt endl cout lt lt SE lt lt tos lt lt endl invokeOp tobj a IAAAAAAAAAAAAAAA AA AAA AAA AAA AAA SSSA int main int argc char argv try CORBA ORB_var orb CORBA ORB_init argc argv if argc 2 cerr lt lt usage anyExample_clt lt object reference gt lt lt endl return 1 CORBA Object_var obj orb gt string_to_object argv 1 anyExample_var ref anyExample _narrow obj if CORBA is_nil ref cerr lt lt Can t narrow reference to type anyExample or it was nil lt lt endl return 1 hello ref orb gt destroy 11 4 SOURCE LISTING 107 catch CORBA TRANSIENTS cerr lt lt Caught system exception TRANSIENT unable to contact the lt lt server lt lt endl catch CORBA SystemException amp ex cerr lt lt Caught a CORBA lt lt ex _name lt lt endl catch CORBA Exception amp ex cerr lt lt Caught CORBA Exception lt lt ex _name lt lt endl catch omniORB fatalException amp fe cerr lt lt Caught omniORB fatalException lt lt endl cerr lt lt file lt lt fe file lt lt endl cerr lt lt line lt lt fe line lt lt endl cerr lt lt mesg lt lt fe errmsg lt lt endl return 0 108 CHAPTER 11 TYP
26. no longer use the myecho pointer 16 CHAPTER 2 THE BASICS 2 8 4 Activating the POA Lines 15 16 POAs are initially in the holding state meaning that incoming requests are blocked Lines 15 and 16 acquire a reference to the POA s POA manager and use it to put the POA into the active state Incoming requests are now served Failing to activate the POA is one of the most common programming mis takes If your program appears deadlocked make sure you activated the POA 2 8 5 Performing a call Line 18 At long last we can call hello with this object reference The argument is widened implicitly to the generic object reference CORBA Object_ptr 2 8 6 ORB destruction Line 20 Shutdown the ORB permanently This call causes the ORB to release all its resources e g internal threads and also to deactivate any servant objects which are currently active When it deactivates the Echo_i instance the servant s reference count drops to zero so the servant is deleted This call is particularly important when writing a CORBA DLL on Windows NT that is to be used from Activex If this call is absent the application will hang when the CORBA DLL is unloaded 2 9 Example 2 Different Address Spaces In this example the client and the object implementation reside in two different address spaces The code of this example is almost the same as the previous exam ple The only difference is the extra work which needs to be done to pass the
27. object reference from the object implementation to the client The simplest and quite primitive way to pass an object reference between two address spaces is to produce a stringified version of the object reference and to pass this string to the client as a command line argument The string is then converted by the client into a proper object reference This method is used in this example In the next example we shall introduce a better way of passing the object reference using the CORBA Naming Service 2 9 1 Object Implementation Making a Stringified Object Reference The main function of the server side is reproduced below The full listing eg2_ imp1 cc can be found at the end of this chapter 2 9 EXAMPLE 2 DIFFERENT ADDRESS SPACES 17 1 int main int argc char argv Sra 3 CORBA ORB_var orb CORBA ORB_init argc argv 4 5 CORBA Object_var obj orb gt resolve_initial references RootPOA 6 PortableServer POA_ var poa PortableServer POA _narrow obj 7 8 Echo_i myecho new Echo_i 9 0 PortableServer ObjectId_var myechoid poa gt activate_object myecho 1 2 obj myecho gt _this 3 CORBA String_var sior orb gt object_to_string obj 4 cerr lt lt char sior lt lt endl 5 6 myecho gt _remove_ref 7 8 PortableServer POAManager_var pman poa gt the_POAManager 9 pman gt activate 20 21 orb gt run 22 orb gt destroy 23 return
28. of back ends written in Python omniidl is very strict about IDL validity so you may find that it reports errors in IDL which compiles fine with other IDL compilers The general form of an omniidl command line is omniidl options b lt back end gt back end options lt file1 gt lt file2 gt 5 1 Common options The following options are common to all back ends bback end Dname value Uname Idir E Ycmd N T WpargLarg WbargLarg nf Run the specified back end For the C ORB use bcxx Define name for the preprocessor Undefine name for the preprocessor Include dir in the preprocessor search path Only run the preprocessor sending its output to stdout Use cmd as the preprocessor rather than the normal C preprocessor Do not run the preprocessor Use a temporary file not a pipe for preprocessor output Send arguments to the preprocessor Send arguments to the back end Do not warn about unresolved forward declarations Keep comments after declarations to be used by some back ends Keep comments before declarations to be used by some back ends Change directory to dir before writing output files Dump the parsed IDL then exit without running a back end Use dir as a path to find omniidl back ends Print version information then exit Print usage information 61 62 CHAPTER 5 THE IDL COMPILER v Verbose trace compilation stages Most of these options are
29. self explanatory but some are not so obvious 5 1 1 Preprocessor interactions IDL is processed by the C preprocessor before omniidl parses it omniidl always uses the GNU C preprocessor which it builds with the name omnicpp The D U and 1I options are just sent to the preprocessor Note that the current directory is not on the include search path by default use 1 for that The Y option can be used to specify a different preprocessor to omnicpp Beware that line directives inserted by other preprocessors are likely to confuse omniidl 5 1 1 1 Windows 9x The output from the C preprocessor is normally fed to the omniidl parser through a pipe On some Windows 98 machines but not all the pipe does not work and the preprocessor output is echoed to the screen When this happens the omniidl parser sees an empty file and produces useless stub files with strange long names To avoid the problem use the T option to create a temporary file between the two stages 5 1 2 Forward declared interfaces If you have an IDL file like interface I interface J attribute I the_I y then omniidl will normally issue a warning test idl 1 Warning Forward declared interface I was never fully defined It is illegal to declare such IDL in isolation but it is valid to define interface I ina separate file If you have a lot of IDL with this sort of construct you will drown under the warning messages Use the nf
30. the object id so it is assigned to a _var type Line 12 The object reference is obtained from the servant object by calling _this Like all object references the return value of _this must be released by CORBA release when it is no longer needed In this case we assign it toa _var type so the release is implicit at the end of the function One of the important characteristics of an object reference is that it is com pletely location transparent A client can invoke on the object using its object reference without any need to know whether the servant object is colocated in the same address space or is in a different address space In the case of colocated client and servant omniORB is able to short circuit the client calls so they do not involve IIOP The calls still go through the POA however so the various POA policies affect local calls in the same way as remote ones This optimisation is applicable not only to object references returned by _this but to any object references that are passed around within the same address space or received from other address spaces via re mote calls Line 13 The server code releases the reference it holds to the servant object The only reference to that object is now held by the POA it gained the reference on the call to activate_object so when the object is deactivated or the POA is destroyed the servant object will be deleted automatically After this point the code must
31. the same or a different location and that forwarded location fails immediately the TRANSIENT exception will occur again and the pattern will re peat With repeated exceptions the handler starts adding delays before retries with exponential back off In all other circumstances the default TRANSIENT handler just passes the ex ception on to the caller Applications can override the default behaviour by installing their own excep tion handler The API to do so is summarised below namespace omniORB typedef CORBA Boolean transientExceptionHandler_t void cookie CORBA ULong n_retries 4 7 SYSTEM EXCEPTION HANDLERS 57 const CORBA TRANSIENT amp ex void installTransientExceptionHandler void cookie transientExceptionHandler_t fn void installTransientExceptionHandler CORBA Object_ptr obj void cookie transientExceptionHandler_t fn The overloaded function installTransientExceptionHandler can be used to install the exception handlers for CORBA TRANSIENT Two forms are available the first form installs an exception handler for all object references except for those which have an exception handler installed by the second form which takes an additional argument to identify the target object reference The argument cookie is an opaque pointer which will be passed on by the ORB when it calls the exception handler An exception handler will be called by proxy objects with thr
32. the usual timeout This kind of configuration is good when connections are slow to be established If an object reference has multiple possible endpoints available and connect ing to the first endpoint times out only that one endpoint will have been tried before an exception is raised However once the timeout has occurred the object reference will switch to use the next endpoint If the application attempts to make another call it will use the next endpoint millisecs 80 CHAPTER 8 CONNECTION AND THREAD MANAGEMENT Connect timeout lt usual timeout If the connect timeout is set to 2 seconds the actual network level connect is only permitted to take 2 seconds As long as the connection is established in less than 2 seconds the call can proceed The 10 second call timeout still applies to the time taken for the whole call including the connection establishment So if establish ing the connection takes 1 5 seconds and the call itself takes 9 5 seconds the call will time out because although it met the connection timeout it exceeded the 10 second total call timeout On the other hand if establishing the connection takes 3 seconds the call will fail after only 2 seconds since only 2 seconds are permitted for the connect If an object reference has multiple possible endpoints available the client will attempt to connect to them in turn until one succeeds The connect timeout applies to each connection attempt So with a connec
33. value of echoString are stored in CORBA String_var variables src and dest respectively The strings managed by the variables are deallocated by the destructor of CORBA String_var It is called automatically when the variable goes out of scope as the function returns Line 15 shows how CORBA String_var variables are used They can be used in place of a string for which the mapping is char As used in line 12 assigning a constant string const char toa CORBA String_var causes the string to be copied On the other hand assigning a char toa CORBA String_var as used in line 15 causes the latter to assume the ownership of the string Under the C mapping T_var types are provided for all the non basic data types It is obvious that one should use automatic variables whenever possible both to avoid memory leaks and to maximise performance However when one has to allocate data items on the heap it is a good practice to use the T_var types to manage the heap storage 2 8 Example 1 Colocated Client and Implementation Having introduced the client and the object implementation we can now describe how to link up the two via the ORB and POA In this section we describe an exam ple in which both the client and the object implementation are in the same address space In the next two sections we shall describe the case where the two are in different address spaces The code for this example is reproduced below 1 int 2 main i
34. values was not main tained by the Any That option is no longer available 3 The members of the client SendRequest interceptor have been changed replacing all the separate variables with a single member of type GIOP_C All the values previously available can be accessed through the GIOP_C instance 4 The C mapping contains Any insertion operators for sequence types passed by pointer which cause the Any to take ownership of the inserted sequence In omniORB 4 0 and earlier the sequence was immediately marshalled into the Any s internal buffer and the sequence was deleted In omniORB 4 1 the sequence pointer is stored by the Any and the sequence is deleted later when the Any is destroyed For most uses this change is not visible to application code However if a sequence is constructed using an application supplied buffer with the re lease flag set to false meaning that the application continues to own the buffer it is now important that the buffer is not deleted or modified while the Any exists since the Any continues to refer to the buffer contents This change means that code that worked with omniORB 4 0 may now fail with 4 1 with the Any seeing modified data or the process crashing due to access ing deleted data To avoid this situation use the alternative Any insertion operator using a const reference which copies the sequence 44 CHAPTER 3 C LANGUAGE MAPPING Chapter 4 omniORB configuration and API omni
35. with the omniidl flags Wbvirtual_objref Wbimpl_mapping 13 8 3 Valuetypes supporting local interfaces According to the IDL specification it should be possible to declare a valuetype that supports a local interface local interface I void my_operation y valuetype V supports I public string s y omniidl accepts the IDL but unfortunately the resulting C code does not compile The C mapping specification has a problem in that both the CORBA LocalO0bject and CORBA ValueBase classes have add_ref and remove_ 13 8 LOCAL INTERFACES 119 ref member functions defined The classes generated for the valuetype inherit from both these base classes and therefore have an ambiguity Until the C map ping resolves this conflict valuetypes supporting local interfaces cannot be used in omniORB 120 CHAPTER 13 OBJECTS BY VALUE ETC Bibliography BLFIM98 T Berners Lee R Fielding U C Irvine and L Masinter Uniform Re HV99 OMG98 OMG00 OMG01 OMG03 Ric96 source Identifiers URI Generic Syntax RFC 2396 August 1998 Michi Henning and Steve Vinoski Advanced CORBA Programming with C Addison Wesley professional computing series 1999 Object Management Group CORBAServices Common Object Services Specification December 1998 Object Management Group Interoperable Naming Service revised chap ters August 2000 From http www omg org cgi bin doc ptc 00 08 07
36. 0 24 The stringified object reference is obtained by calling the ORB s object_to_ string function line 13 This results in a string starting with the signature IOR and followed by some hexadecimal digits All CORBA 2 compliant ORBs are able to convert the string into its internal representation of a so called Interoperable Object Reference IOR The IOR contains the location information and a key to uniquely identify the object implementation in its own address space From the IOR an object reference can be constructed 2 9 2 Client Using a Stringified Object Reference The stringified object reference is passed to the client as a command line argument The client uses the ORB s string_to_object function to convert the string into a generic object reference CORBA Object_ptr The relevant section of the code is reproduced below The full listing eg2_c1t cc can be found at the end of this chapter ty 4 CORBA Object_var obj orb gt string_to_object argv 1 hello obj catch CORBA TRANSIENT code to handle transient exception 18 CHAPTER 2 THE BASICS 2 9 3 Catching System Exceptions When omniORB detects an error condition it may raise a system exception The CORBA specification defines a series of exceptions covering most of the error con ditions that an ORB may encounter The client may choose to catch these ex ceptions and recover from the error condition For instance the c
37. 1 localhost The address of this machine 2 w x y z m1 m2 m3 m4 An IPv4 address with bits selected by the mask e g 172 16 0 0 255 240 0 0 3 w x y z prefixlen An IPv4 address with prefixlen significant bits e g 172 16 2 0 24 4 a b c d e f 2 h prefixlen An IPv6 address with prefixlen significant bits e g 3ffe 505 2 1 64 5 Wildcard that matches any address The action is one or more of the following 8 7 CONNECTION SELECTION AND ACCEPTANCE 87 none Do not use this address tep Use a TCP transport ssl Use an SSL transport unix Use a Unix socket transport bidir Connections to this address can be used bidirectionally see section 8 8 Oly Oo Ne The transport selecting actions form a prioritised list so an action of unix ssl tcp means to use a Unix transport if there is one failing that a SSL transport failing that a TCP transport In the absence of any explicit rules the client uses the implicit rule of unix ssl tcp If more than one rule is specified they are prioritised in the order they are specified For example the configuration file might contain clientTransportRule 192 168 1 0 255 255 255 0 unix tcp clientTransportRule 172 16 0 0 255 240 0 0 unix tcp a none This would be useful if there is a fast network 192 168 1 0 which should be used in preference to another network 172 16 0 0 and connections to other networks are not permitted at all In general the
38. 1 EXPO SMIDS 9 0 2 sack ee PRA ERK a 12 2 2 Importing constant symbolS Objects by value etc 13 1 Features 2 x ewok a sspears sr ra Hh ee E eo S 15 2 Rerrene COCs ea ee oe ER Res oe eS 13 3 Value sharing and local ealls o 225 2s 45 262 249 445 G0 48 13 4 Value box factories o oo ee 13 5 Standard value boxes ee 136 Covarant returns cionado Hd a EES 10 7 Valucsihside AMS a EA Ad 13 7 1 Values inside Dyn Anys gt s 64 ia dw he ee HE 89 89 89 90 91 92 92 95 95 95 96 97 98 98 98 99 99 100 100 100 100 101 101 102 102 105 109 109 109 109 110 130 Local Interfaces 2 4 6 4 2 4 4 4 id A Sle dee tae eae 117 13 8 1 Simple local intertaces lt lt oc reta EMER EE ES 117 13 8 2 Inheritance from unconstrained interfaces 117 13 8 3 Valuetypes supporting localinterfaces 118 Chapter 1 Introduction omniORB is an Object Request Broker ORB that implements the 2 6 specification of the Common Object Request Broker Architecture CORBA OMGO01 It has passed the Open Group CORBA compliant testsuite for CORBA 2 1 and was one of the three ORBs to be granted the CORBA brand in June 1999 This user guide tells you how to use omniORB to develop CORBA applications It assumes a basic understanding of CORBA In this chapter we give an overview of the main features of omniORB and what you need to do to setup your environment to run omniORB 1
39. 1 Features 1 1 1 Multithreading omniORB is fully multithreaded To achieve low call overhead unnecessary call multiplexing is eliminated With the default policies there is at most one call in flight in each communication channel between two address spaces at any one time To do this without limiting the level of concurrency new channels connecting the two address spaces are created on demand and cached when there are concurrent calls in progress Each channel is served by a dedicated thread This arrangement provides maximal concurrency and eliminates any thread switching in either of the address spaces to process a call Furthermore to maximise the throughput in processing large call arguments large data elements are sent as soon as they are processed while the other arguments are being marshalled With GIOP 1 2 large messages are fragmented so the marshaller can start transmission before it knows how large the entire message will be From version 4 0 onwards omniORB also supports a flexible thread pooling Most of the 2 6 features have been implemented The features still missing in this release are listed in section 1 1 3 Where possible backward compatibility has been maintained up to specifica tion 2 0 2More information can be found at http www opengroup org press 7jun99 b htm 2 CHAPTER 1 INTRODUCTION policy and supports sending multiple interleaved calls on a single connection This policy leads to a small amount of a
40. 4 code set to select characters out side the first plane without having to use UTF 16 surrogates 9 2 Code set library To save space in the main ORB core library most of the code set implementations are in a separate library named omniCodeSets4 To use the extra code sets you If you have no idea what this means don t worry you re better off not knowing unless you really have to 89 90 CHAPTER 9 CODE SET CONVERSION must link your application with that library On most platforms if you are using dynamic linking specifying the omniCodeSets4 library in the link command is suf ficient to have it initialised and for the code sets to be available With static linking or platforms with less intelligent dynamic linkers you must force the linker to ini tialise the library You do that by including the omniORB4 optionalFeatures h header By default that header enables several optional features Look at the file contents to see how to turn off particular features 9 3 Implementing new code sets It is quite easy to implement new code sets if you need support for code sets or marshalling formats that do not come with the omniORB distribution There are extensive comments in the headers and ORB code that explain how to implement a code set this section just serves to point you in the right direction The main definitions for the code set support are in include omni0RB4 codeSets h That defines a set of base classes use to
41. AA AA AAA AAA AAAAAAA AAA AAA AAA AAA AAA AN NSS int main int argc char argv try CORBA ORB_var orb CORBA ORB_init argc argv CORBA Object_var obj orb gt resolve_initial_references RootPOA PortableServer POA_var poa PortableServer POA _narrow obj Echo_i myecho new Echo_i 2 12 SOURCE LISTINGS 25 PortableServer ObjectId_var myechoid poa gt activate_object myecho Obtain a reference to the object and print it out as a stringified IOR obj myecho gt _this CORBA String_var sior orb gt object_to_string obj cout lt lt char sior lt lt endl myecho gt _remove_ref PortableServer POAManager_var pman poa gt the_POAManager pman gt activate orb gt run catch CORBA SystemException amp ex cerr lt lt Caught CORBA lt lt ex _name lt lt endl catch CORBA Exception amp ex cerr lt lt Caught CORBA Exception lt lt ex _name lt lt endl catch omniORB fatalException amp fe cerr lt lt Caught omniORB fatalException lt lt endl cerr lt lt file lt lt fe file lt lt endl cerr lt lt line lt lt fe line lt lt endl cerr lt lt mesg lt lt fe errmsg lt lt endl return 0 26 2 12 3 AA else CHAPTER 2 THE BASICS eg2_clt cc eg2_clt cc This is the sou
42. BA Object_var obj obj rootContext gt resolve contextName testContext CosNaming NamingContext _narrow obj if CORBA is_nil testContext cerr lt lt Failed to narrow naming context lt lt endl return 0 Bind objref with name Echo to the testContext CosNaming Name objectName objectName length 1 objectName 0 id objectName 0 kind const const try testContext gt bind objectName char Echo char string copied Object string copied objref catch CosNaming NamingContext AlreadyBound ex testContext gt rebind objectName objref Using rebind will overwrite any Object previously bound which will raise a CosNaming NamingContext AlreadyBound exception if the name it is necessary to first try bind as rebind on it s own will throw a NotFoundexception if This is incorrect behaviour Note to test Echo with obj Alternatively bind can be used EL supplied is already bound to an object Amendment When using OrbixNames and then rebind the Name has not already been bound it should just bind catch CORBA TRANSIENT amp ex cerr lt lt Caught system exception TRANSIENT unable to contact the lt lt naming service lt lt endl lt lt Make sure the naming server is running and that omniORB is lt lt configured correctly lt lt end
43. E ANY AND TYPECODE Chapter 12 Packaging stubs into DLLs omniORB s stubs can be packaged into shared libraries or DLLs On Unix plat forms this is mostly painless but on Windows things are slightly more tricky 12 1 Dynamic loading and unloading As long as your platform supports running static initialisers and destructors as libraries are loaded and unloaded you can package stubs into shared libraries DLLs and load them dynamically at runtime There is one minor problem with this which is that normally nil object refer ences are heap allocated and only deallocated when the ORB is destroyed That means that if you unload a stub library from which nil references have been ob tained just by creating an object reference _var for example there is a risk of a segmentation fault when the ORB is destroyed To avoid that problem define the OMNI_UNLOADABLE_STUBS C pre processor symbol while you are compiling the stub files Unfortunately with that define set there is a risk that object reference _vars at global scope will segfault as they are unloaded You must not create _vars at global scope if you are using OMNI_UNLOADABLE_STUBS 12 2 Windows DLLs On Unix platforms the linker figures out how to link the symbols exported by a library in to the running program On Windows unfortunately you have to tell the linker where symbols are coming from This causes all manner of difficulties 12 2 1 Exporting symbols To static
44. GLE_THREAD_MODEL Thread Policy This guarantees that all calls to that POA are processed se quentially Reference Counting All servant objects are reference counted The base PortableServer ServantBase class from which all servant skeleton classes derive defines member functions named _add_ref and _remove_ref The refer ence counting means that an Echo_i instance will be deleted when no more references to it are held by application code or the POA itself Note that this is totally separate from the reference counting which is associated with object references a servant object is never deleted due to a CORBA object reference being released Instantiation Servants are usually instantiated on the heap i e using the new operator However they can also be created on the stack as automatic variables If you do that itis vital to make sure that the servant has been deactivated and thus released by the POA before the variable goes out of scope and is destroyed 2 7 Writing the client Here is an example of how an Echo_ptr object reference is used CORBA String_var dest dest e gt echoString src 1 void 2 hello CORBA Object_ptr obj 3 1 4 Echo_var e Echo _narrow ob J 5 6 if CORBA is_nil e 7 cerr lt lt cannot invoke on a nil object reference 8 lt lt endl 9 return 0 1 2 CORBA String_var src const char Hello 3 4 5 6 Tn the previous 1 0 v
45. Implementation 13 2 8 1 ORB initialisation s s 2 4 2 44040 aa 14 20 Obtaining ne Root POA s sois 46 ea ees ras AN 14 2 8 3 Object initialisation lt se caw as r Oe hoe wiwa sa 15 284 Activating TIE PA 6 es ew DE mient E 16 285 o AE 16 2 8 6 ORB GesthuctiOl s rea rasaae weak e bee 16 29 Example 2 Different Address Spaces 24 44 es cos 16 2 9 1 Object Implementation Making a Stringified Object Reference 16 2 9 2 Client Using a Stringified Object Reference 17 29 9 Catching System Exceptions oe se ba ricas eras 18 2 9 4 Lifetime ofa CORBA object comodas estes a 18 2 10 Example 3 Using the Naming Service 19 2 10 1 Obtaining the Root Context Object Reference 19 202 The Naming Service Interface ciar ee 20 2 11 Example 4 Using tie implementation templates 20 111 DE SOLES LEUN canos Mea EERE e do dc RS Bl BRAD AAA AA A AA A EXI a SRA EY aH ALA AI III AA EBRIOS AAA Ree Aa yA E E 2126 ego CIPLC s eco dd AAA ee C language mapping 3 1 omniORB 2 BOA compatibility cios 2h ede ee ad ha ws 32 oOmniORB GU compatibility lt s se e eb ae be aa Re ee eS 39 OMMORA 4 Ocrompatibility lt 2 sence dh eer ec awed ee Re Oo omniORB configuration and API 41 Setting parameters cea AA ee Ow eS 4 1 1 Command line arguments cocos orcos Pe ba wR 412 ORD tit parameter c ora oe eas 4 1 3 Environment variables 114
46. LL See the COS services IDL files in id1 COS for an example Chapter 13 Objects by value abstract interfaces and local interfaces omniORB 4 1 supports objects by value declared with the valuetype keyword in IDL and both abstract and local interfaces This chapter outlines some issues to do with using these types in omniORB You are assumed to have read the relevant parts of the CORBA specification specifically chapters 3 4 5 and 6 of the CORBA 2 6 specification and sections 1 17 1 18 and 1 35 of the C mapping specification version 1 1 13 1 Features omniORB supports the complete objects by value specification with the exception of custom valuetypes All other valuetype features including value boxes value sharing semantics abstract valuetypes and abstract interfaces are supported Lo cal interfaces are supported with a number of caveats outlined in section 13 8 13 2 Reference counting Values are reference counted This means that as long as your application properly manages reference counts values are usually automatically deleted when they are no longer required However one of the features of valuetypes is that they sup port the representation of cyclic graph structures In that kind of situation the reference counting garbage collection does not work because references internal to the graph prevent the reference counts ever becoming zero To avoid memory leaks application code must explicitly break any referen
47. ORB 4 1 has a wide range of parameters that can be configured They can be set in the configuration file Windows registry as environment variables on the command line or within a proprietary extra argument to CORBA ORB_init A few parameters can be configured at run time This chapter lists all the configu ration parameters and how they are used 4 1 Setting parameters When CORBA ORB_init is called the value for each configuration parameter is searched for in the following order 1 Command line arguments 2 ORB_init options 3 Environment variables 4 Configuration file Windows registry 5 Built in defaults 4 1 1 Command line arguments Command line arguments take the form ORBparameter and usually expect an other argument An example is ORBtraceLevel 10 4 1 2 ORB_init parameter ORB_init s extra argument accepts an array of two dimensional string arrays like this const char options 1 2 traceLevel 1 0 O orb CORBA ORB_init argc argv omniORB4 options 45 46 CHAPTER 4 OMNIORB CONFIGURATION AND API 4 1 3 Environment variables Environment variables consist of the parameter name prefixed with ORB Using bash for example export ORBtraceLevel 10 4 1 4 Configuration file The best way to understand the format of the configuration file is to look at the sample cfg file in the omniORB distribution Each parameter is set on a single line
48. Object Management Group The Common Object Request Broker Ar chitecture and Specification 2 6 edition December 2001 From http www omg org cgi bin doc formal 01 12 01 Object Management Group C Language Mapping 1 1 edition 2003 From http www omg org cgi bin doc formal 03 06 03 Tristan Richardson The OMNI Thread Abstraction AT amp T Laboratories Cambridge October 1996 121
49. The omniORB version 4 1 User s Guide Duncan Grisby email dgrisby apasphere com Apasphere Ltd Sai Lai Lo David Riddoch AT amp T Laboratories Cambridge July 2007 Changes and Additions July 2007 e Updates for omniORB 4 1 1 Changes and Additions June 2005 e New omniORB 4 1 features Changes and Additions October 2004 e Packaging stubs into DLLs Changes and Additions July 2004 e Minor updates Changes and Additions November 2002 e Per thread timeouts e Implement missing interceptors e Minor fixes Changes and Additions June 2002 e Updated to omniORB 4 0 Contents 1 Introduction 1 UA Feau asis PR Rok EA Ea OEE RAS ee BE 1 LLL IASI he RG Re ore RARA 1 LLE Pore eke a thd eee eee he oe bo was 2 1 1 9 Missing features a Sa RRR AES ERS REESE S ES 2 1 2 Setting Up your environmen pou bce Ga ep See es 2 1 3 Platform specific variables lt lt o sec cs aop eee ens eee nass 3 2 The Basics 5 21 TheEcho Object Example lt aret secie iana dara 5 2 2 Bpecifying the Echo interface ln IDL o see ac aaaea Ew 6 20 Generating Me CHA Ste booma dk kee ada Be ER Se OAS 6 24 Object References and Servants 4 ic sede eed es ives E 2 5 A Quick Tour of the C stubs 7 251 Servant Object Implementation lt lt lt 5 abe eed es 10 2 6 Writing the servant implementation 3 2423 8485 11 27 A as oe Ree bee RAO RAR RS 12 2 8 Example 1 Colocated Client and
50. _ __OSVERSION__ 2 Linux 2 x powerpc _ powerpc_ __linux__ __OSVERSION_ 2 OpenVMS 6 x alpha _alpha__ __vms _ OSVERSION__ 6 OpenVMS 6 x vax _Vax__ __vms __OSVERSION__ 6 SGI Irix 6 x __mips__ _ drix __ OSVERSION__ 6 Reliant Unix 5 43 __mips__ __SINIX__ __OSVERSION__ 5 ATMos 4 0 _ arm__ _ atmos__ _ OSVERSION__ 4 NextStep 3 x _ m68k__ __nextstep__ __OSVERSION__ 3 Unixware 7 _ x86__ uw __OSVERSION__ 5 The preprocessor defines for new platform ports not listed above can be found in the corresponding platform configuration files For instance the platform con figuration file for Sun Solaris 2 6 is in mk platforms sun4_sosV_5 6 mk The preprocessor defines to identify a platform are in the make variable IMPORT_ CPPFLAGS In a single source multi target environment you can put the preprocessor de fines as the command line arguments for the compiler If you are building for a single platform you can edit include omniconfig h to add the definitions Chapter 2 The Basics In this chapter we go through three examples to illustrate the practical steps to use omniORB By going through the source code of each example the essential concepts and APIs are introduced If you have no previous experience with us ing CORBA you should study this chapter in detail There are pointers to other essential documents you should be familiar with If you have experience with using other ORBs you should still go through this chapt
51. ages are output traceExceptions default 0 If the traceExceptions parameter is set true all system exceptions are logged as they are thrown along with details about where the exception is thrown from This parameter is enabled by default if the traceLevel is set to 10 or more traceInvocations default 0 If the traceInvocations parameter is set true all local and remote invoca tions are logged in addition to any logging that may have been selected with traceLevel traceInvocationReturns default 0 If the traceInvocationReturns parameter is set true a log message is output as an operation invocation returns In conjunction with t raceInvocations and traceTime described below this provides a simple way of timing CORBA calls within your application traceThreadld default 0 If traceThreadId is set true all trace messages are prefixed with the id of the thread outputting the message This can be handy for tracking down race condi tions but it adds significant overhead to the logging function so it is turned off by default traceTime default 0 If traceTime is set true all trace messages are prefixed with the time This is useful but on some platforms it adds a very large overhead so it is turned off by default 48 CHAPTER 4 OMNIORB CONFIGURATION AND API 4 2 1 Tracing API The tracing parameters can be modified at runtime by assigning to the following variables namespace omniORB CORBA ULong traceLe
52. ally link with a DLL file in Windows you link with a LIB file which references the symbols exported from the DLL To build the LIB and DLL files the correct symbols must be exported One way to do that is to decorate the source 109 110 CHAPTER 12 PACKAGING STUBS INTO DLLS code with magic tags that tell the compiler to export the symbols The alternative is to provide a DFF file that lists all the symbols to be exported omniORB uses a DEF file The question is how do you create the DEF file The answer is to use a Python script named makedeffile py that lives in the bin scripts directory in the omniORB distribution makedeffile py runs the dumpbin program that comes with Visual C and processes its output to extract the necessary symbols Al though it is designed for exporting the symbols from omniORB stub files it can actually be used for arbitrary C code To use it to create a DLL from a single source file use the following steps 1 Compile the source cl c 02 MD GX Fofoo o Tpfoo cc 2 Build a static library It probably won t work on its own due to the MD switch to cl but we just need it to get the symbols out lib out foo_static lib foo o 3 Use the script to build a def file makedeffile py foo_static lib foo 1 0 foo def 4 Build the dll and lib with the def file link out foo dll dll def foo def implib foo lib foo o Of course you can link together many separate C files rather than just the
53. ations which are files of the form cs cc in the src lib omniORB orbcore and src lib omniORB codesets Note how all the 8 bit code sets the ISO 8859 family consist entirely of data and no code since they are driven by look up tables Chapter 10 Interceptors omniORB supports interceptors that allow the application to insert processing in various points along the call chain and in various other locations It does not yet support the standard Portable Interceptors API The interceptor interfaces are defined in a single header include omniORB4 omnilnterceptors h Each interception point consists of a singleton object with add and remove methods and the definition of an interceptor info class For example clas cl pu y s omnilnterceptors ass clientSendRequest_T blic class info_T public GIOP_C amp giop_c IOP ServiceContextList service_contexts info_T GIOP_C amp c giop_c c service_contexts 5 private info_T info_T const info_T amp info_T amp operator const info_T amp y typedef CORBA Boolean interceptFunc info_T amp info void add interceptFunc void remove interceptFunc he You can see that the interceptors themselves are functions that take the info_T 91 92 CHAPTER 10 INTERCEPTORS object as their argument and return boolean Interceptors are called in the order they are registered normally all interceptor functions return true
54. ator must not be performed on the type In addition to class _objref_Echo the mapping defines three static member functions in the class Echo _nil _duplicate and_narrow The _nil function returns a nil object reference of the Echo interface The following call is guaranteed to return TRUE CORBA Boolean true_result CORBA is_nil Echo _nil Remember CORBA is_nil is the only compliant way to check if an object reference is nil You should not use the equality operator Many C ORBs use the null pointer to represent a nil object reference omniORB does not The _duplicate function returns a new object reference of the Echo in terface The new object reference can be used interchangeably with the old object reference to perform an operation on the same object Duplications are required to satisfy the C mapping s reference counting memory management All CORBA objects inherit from the generic object CORBA Object CORBA Object_ptr is the object reference type for CORBA Object Any _ptr ob ject reference is therefore conceptually inherited from CORBA Object_ptr In other words an object reference such as Echo_ptr can be used in places where a CORBA Object_ptr is expected The _narrow function takes an argument of type CORBA Object_ptr and returns a new object reference of the Echo interface If the actual runtime type of the argument object reference can be narrowed to Echo_ptr _narrow will
55. ault 1 2 Choose the maximum GIOP version the ORB should support Valid values are 1 0 1 1 and 1 2 giopMaxMsgSize default 2097152 The largest message in bytes that the ORB will send or receive to avoid resource starvation If the limit is exceeded a MARSHAL exception is thrown The size must be gt 8192 strictIIOP default 1 If true be strict about interpretation of the IIOP specification if false permit some buggy behaviour to pass lcdMode default 0 If true select Lowest Common Denominator mode This disables various IIOP and GIOP features that are known to cause problems with some ORBs tcAliasExpand default 0 This flag is used to indicate whether TypeCodes associated with Anys should have aliases removed This functionality is included because some ORBs will not recog nise an Any containing a TypeCode with aliases to be the same as the actual type contained in the Any Note that omniORB will always remove top level aliases but will not remove aliases from TypeCodes that are members of other TypeCodes e g TypeCodes for members of structs etc unless t cAliasExpand is set to 1 4 7 SYSTEM EXCEPTION HANDLERS 55 There is a performance penalty when inserting into an Any if tcAliasExpand is set to 1 useTypeCodeIndirections default 1 TypeCode Indirections reduce the size of marshalled TypeCodes and are essential for recursive types but some old ORBs do not support them Setting this flag to fal
56. avoid conventions such as that used by files name type g test ps postscript etc CosNaming NamingContext_var testContext try Bind the context to root testContext rootContext gt bind_new_context contextName catch CosNaming NamingContext AlreadyBound amp ex If the context already exists this exception will be raised In this case just resolve the name and assign testContext to the object returned CORBA Object_var obj 2 12 SOURCE LISTINGS 31 Co ob ob ob tr ca Lh catc ce re obj rootContext gt resolve contextName testContext CosNaming NamingContext _narrow obj if CORBA is_nil testContext cerr lt lt Failed to narrow naming context lt lt endl return 0 Bind objref with name Echo to the testContext sNaming Name objectName jectName length 1 jectName 0 id const char Echo string copied jectName 0 kind const char Object string copied y testContext gt bind objectName objref tch CosNaming NamingContext AlreadyBound amp ex testContext gt rebind objectName objref Note Using rebind will overwrite any Object previously bound to test Echo with obj Alternatively bind can be used which will raise a CosNaming NamingContext AlreadyBound exception if the name supplied is already bound to an object Amendmen
57. bject keys containing non ASCII characters can use the standard URI escapes corbaloc iiop myhost example com 1234 My efObjectKey denotes an object key with the value 239 hex ef in the third octet The protocol name i iop can be abbreviated to the empty string so the origi nal URI can be written 67 68 CHAPTER 6 INTEROPERABLE NAMING SERVICE corbaloc myhost example com 1234 MyObjectKey The IANA has assigned port number 2809 for use by corbaloc so if the server is listening on that port you can leave the port number out The following two URIs refer to the same object corbaloc myhost example com 2809 MyObjectKey corbaloc myhost example com MyObjectKey You can specify an object which is available at more than one location by separating the locations with commas corbaloc myhost example com localhost 1234 MyObjectKey Note that you must restate the protocol for each address hence the before localhost It could equally have been written iiop localhost You can also specify an IIOP version number corbaloc 1 2 myhost example com MyObjectKey Specifying IIOP versions above 1 0 is slightly risky since higher versions make use of various information stored in IORs that is not present in a corbaloc URI It is generally best to contact initial corbaloc objects with HOP 1 0 and rely on higher versions for all other object references Alternatively to use resolve_initial_references
58. can be started in the pool is set with the maxServerThreadPool Size parameter The default is 100 A common pattern in CORBA applications is for a client to make several calls to a single object in quick succession To handle this situation most efficiently the default behaviour is to not return a thread to the pool immediately after a call is finished Instead it is set to watch the connection it has just served for a short while mimicking the behaviour in thread per connection mode If a new call comes in during the watching period the call is dispatched without any thread switch ing just as in thread per connection mode Of course if the server is supporting a very large number of connections more than the size of the thread pool this policy can delay a call coming from another connection If the threadPoolWatch Connection parameter is set to zero connection watching is disabled and threads return to the pool immediately after finishing a single request In the face of multiplexed calls on a single connection multiple threads from the pool can be dispatched for one connection just as in thread per connection mode With threadPoolWatchConnection set to the default value of 1 only the last thread servicing a connection will watch it when it finishes a request Set ting the parameter to a larger number allows the last n connections to watch the connection 8 4 3 Policy transition If the server is dealing with a relatively small number
59. ce cycles in values it manipulates This includes graphs of values received as param eters and return values from CORBA operations 113 114 CHAPTER 13 OBJECTS BY VALUE ETC 13 3 Value sharing and local calls When valuetypes are passed as parameters in CORBA calls i e calls on CORBA objects declared with interface in IDL the structure of related values is main tained Consider for example the following IDL definitions which are from the example code in src examples valuetype simple module ValueTest valuetype One public string s public long e y interface Test One opl in One a in One b y y If the client to the Test object passes the same value in both parameters just one value is transmitted and the object implementation receives a copy of the sin gle value with references to it in both parameters In the case that the object is remote from the client there is obviously a copying step involved In the case that the object is in the same address space as the client the same copying semantics must be maintained so that the object implementation can modify the values it receives without the client seeing the modifications To support that omniORB must copy the entire parameter list in one operation in case there is sharing between different parameters Such copying is a rather more time consuming process than the parameter by parameter copy that takes place in calls not involving valuetypes To avo
60. connection The IOR contains a Repository ID Repold and one or more communication profiles The communication profiles describe where and how the object can be contacted The Repold is a string which uniquely identifies the IDL interface of the object Unless the ID pragma is specified in the IDL the ORB generates the Repold string in the so called OMG IDL Format For instance the Repold for the Echo interface used in the examples of chapter 2 is IDL Echo 1 0 When interface inheritance is used in the IDL the ORB always sends the Re pold of the most derived interface For example IDL interface A se interface B A se interface C void op in A arg r For further details of the repository ID formats see section 10 6 in the CORBA 2 6 specification 73 74 CHAPTER 7 INTERFACE TYPE CHECKING C C_ptr server B_ptr ob JB A_ptr objA ob JB server gt op objA Send Bas A In the example the operation C op accepts an object reference of type A The real type of the reference passed to C op is B which inherits from A In this case the Repold of B and not that of A is sent across the network The GIOP IIOP specification allows an ORB to send a null string in the Repold field of an IOR It is up to the receiving end to work out the real type of the object omniORB never sends out null strings as Repolds but it may receive null Repolds from other ORBs In that case it will use
61. d in Chapter 9 Type Any and TypeCode of the omniORB users guide This is the client Usage anyExample_clt lt object reference gt d else include lt anyExample hh gt ifdef HAVE_STD include lt iostream gt using namespace std include lt iostream h gt endif static void invokeOp anyExample_ptr amp tobj const CORBA Any amp a CORBA Any_var bp cout lt lt Invoking operation lt lt endl bp tobj gt testOp a cout lt lt Operation completed Returned Any CORBA ULong ul if bp gt gt ul cout lt lt ULong lt lt ul lt lt An lt lt endl else cout lt lt Unknown value lt lt An lt lt endl static void hello anyExample_ptr tobj CORBA Any a Sending Long CORBA Long 1 100 a lt lt 1 cout lt lt Sending Any containing Long lt lt 1 lt lt endl invokeOp tobj a 106 CHAPTER 11 TYPE ANY AND TYPECODE Sending Double ifndef NO_FLOAT CORBA Double d 1 2345 a lt lt d cout lt lt Sending Any containing Double lt lt d lt lt endl invokeOp tobj a endif Sending String const char str Hello a lt lt str cout lt lt Sending Any containing String lt lt str lt lt endl invokeOp tobj a Sending testStruct Struct defined in IDL testStruct t t l 456 t s 8 a
62. d when their reference count becomes zero as with any other servant object Echo_i myimpl new Echo_i POA_Echo_tie lt Echo_i gt myecho myimpl PortableServer ObjectId_var myechoid poa gt activate_object amp myecho Obtain a reference to the object and register it in the naming service obj myecho _this if bindObjectToName orb obj return 1 PortableServer POAManager_var pman poa gt the_POAManager pman gt activate orb gt run catch CORBA SystemException amp ex cerr lt lt Caught CORBA lt lt ex _name lt lt endl catch CORBA Exception amp ex cerr lt lt Caught CORBA Exception lt lt ex _name lt lt endl catch omniORB fatalException amp fe cerr lt lt Caught omniORB fatalException lt lt endl cerr lt lt file lt lt fe file lt lt endl cerr lt lt line lt lt fe line lt lt endl cerr lt lt mesg lt lt fe errmsg lt lt endl return 0 38 CHAPTER 2 THE BASICS SISSSSSSSS LALLA AAAS AAA AAA AA IIIS SAIS SSSA ALAS SSSA LLL AAA AA AAAS static CORBA Boolean bindObjectToName CORBA ORB_ptr orb CORBA Object_ptr objref CosNaming NamingContext_var rootContext try d Obtain a reference to the root context of the Name servic CORBA Object_var obj obj orb gt resolve_initial_references NameServic
63. dditional call overhead compared to the default thread per connection model but allows omniORB to scale to extremely large numbers of concurrent clients 1 1 2 Portability omniORB has always been designed to be portable It runs on many flavours of Unix Windows several embedded operating systems and relatively obscure sys tems such as OpenVMS and Fujitsu Siemens BS2000 It is designed to be easy to port to new platforms The IDL to C mapping for all target platforms is the same omniORB uses real C exceptions and nested classes It keeps to the CORBA specification s standard mapping as much as possible and does not use the alter native mappings for C dialects The only exception is the mapping of IDL mod ules which can use either namespaces or nested classes omniORB relies on native thread libraries to provide multithreading capability A small class library omnithread Ric96 is used to encapsulate the APIs of the na tive thread libraries In application code it is recommended but not mandatory to use this class library for thread management It should be easy to port omnithread to any platform that either supports the POSIX thread standard or has a thread package that supports similar capabilities 1 1 3 Missing features omniORB is not yet a complete implementation of the CORBA 2 6 core The fol lowing is a list of the most significant missing features e omniORB does not have its own Interface Repository However
64. de for the _copy_value function that returns the most derived type of the value On older compilers _copy_value returns CORBA ValueBase If you write code that calls _copy_value and you need to support older compilers you should assign the result to a variable of type CORBA ValueBase and downcast to the target type rather than using the covariant return If you are overriding _copy_value you must correctly take account of the OMNI_HAVE_COVARIANT_RETURNS preprocessor definition 13 7 Values inside Anys Valuetypes inserted into Anys cause a number of interesting issues Even when inside Anys values are required to support complete sharing semantics Take this IDL for example module ValueTest valuetype One public string s public long 1 y interface AnyTest void opl in One v in Any a y Now suppose the client behaves as follows ValueTest One v new One_impl hello 123 CORBA Any a a obj gt opl v a then on the server side 116 CHAPTER 13 OBJECTS BY VALUE ETC void AnyTest_impl opl ValueTest One v CORBA Any amp a ValueTest One v2 a gt gt v2 assert v2 v This is all very well in this kind of simple situation but problems can arise if trun catable valuetypes are used Imagine this derived value module ValueTest valuetype Two truncatable One public double d y y Now suppose that the client shown above send
65. e Narrow the reference returned rootContext CosNaming NamingContext _narrow obj if CORBA is_nil rootContext cerr lt lt Failed to narrow the root naming context lt lt endl return 0 catch CORBA NO_RESOURCES8 cerr lt lt Caught NO_RESOURCES exception You must configure omniORB lt lt with the location lt lt endl lt lt of the naming service lt lt endl return 0 catch CORBA ORB InvalidName This should not happen cerr lt lt Service required is invalid does not exist lt lt endl return 0 try Bind a context called test to the root context CosNaming Name contextName contextName length 1 contextName 0 id const char test string copied contextName 0 kind const char my_context string copied Note on kind The kind field is used to indicate the type of the object This is to avoid conventions such as that used by files name type g test ps postscript etc CosNaming NamingContext_var testContext try Bind the context to root testContext rootContext gt bind_new_context contextName 2 12 SOURCE LISTINGS 39 catch CosNaming NamingContext AlreadyBound ex If the context already exists just resolve th In this case this exception will be raised name and assign testContext to the object returned COR
66. e specification does not make it clear whether or not the address string should also be escaped by the operation omniORB does not escape it For this reason it is best to avoid calling to_ur1 if the address part contains escapable characters omni ORB provides the equivalent local function omniURI addrAndNameToURI resolve_str is equivalent to calling to_name followed by the inherited resolve operation There are no string based equivalents of the various bind 6 4 OMNIMAPPER 71 operations 6 3 2 Use with corbaname To make it easy to use omniNames with corbaname URIs it starts with the default port of 2809 and an object key of NameService for the root naming context 6 4 omniMapper omniMapper is a simple daemon which listens on port 2809 or any other port and redirects IIOP requests for configured object keys to associated persistent ob ject references It can be used to make a naming service even an old non INS aware version of omniNames or other ORB s naming service appear on port 2809 with the object key NameService The same goes for any other service you may wish to specify such as an interface repository omniMapper is started with a command line of omniMapper port lt port gt config lt config file gt v The port option allows you to choose a port other than 2809 to listen on The config option specifies a location for the configuration file The default name is etc omniMapper
67. e TypeCode interface is used for this purpose Examples IDL 1 typedef double Doublel struct Testl Doublel a y IDL 2 typedef double Double2 struct Testl Double2 a y If an attempt is made to extract the type Test1 defined in IDL 1 from an Any containing the Test1 defined in IDL 2 this will succeed and vice versa as the two types differ only by an alias 11 2 3 Top level aliases When a type is inserted into an Any the Any stores both the value of the type and the TypeCode for that type However in some cases a top level alias can be lost due to the details of the C mapping For example consider these IDL definitions IDL 3 typedef sequence lt double gt seqDoublel typedef sequence lt double gt seqDouble2 typedef seqDouble2 seqDouble3 omniidl generates distinct types for seqDoublel and seqDoub1le2 and there fore each has its own set of C operators for Any insertion and extraction That means inserting a seqDoublel into an Any sets the Any s TypeCode to include the alias seqDouble1 and inserting a seqDouble2 sets the TypeCode to the alias seqDouble2 However in the C mapping seqDoub1e3 is required to be just a C type def to seqDouble2 so the C compiler uses the Any insertion operator for seqDouble2 Therefore inserting a seqDouble3 sets the Any s TypeCode to the seqDouble2 alias If this is not desirable you can use the member function void type Ty
68. e ap plication defines a class derived from it that implements the abstract hello member function Instances of that class can then be used where the IDL specifies interface Example Note that by default local interface implementations have no reference count ing behaviour If the local object should be deleted when the last reference is re leased the application must implement the _add_ref and _remove_ref virtual member functions within the implementation class Make sure that the im plementations are thread safe 13 8 2 Inheritance from unconstrained interfaces Local interfaces can inherit from unconstrained i e non local interfaces module Test interface One void problem inout string arg y local interface Two One Y interface Receiver void setOne in One a y 118 CHAPTER 13 OBJECTS BY VALUE ETC IDL like this leads to two issues to do with omniORB s C mapping imple mentation First an instance of local interface Two should be suitable to pass as the argu ment to the setOne method of a Receiver object as long as the object is in the same address space as the caller Therefore the Two abstract base class has to inherit from the internal class omniORB uses to map object references of type One For performance reasons the class that implements One object references nor mally has non virtual member functions That means that the application supplied problem member function for the
69. e the format giop unix lt filename gt 84 CHAPTER 8 CONNECTION AND THREAD MANAGEMENT where the filename is the name of the socket within the filesystem If the filename is left blank the ORB chooses a name based on the process id and a timestamp To listen on an endpoint without publishing it in IORs specify it with the endPointNoPublish configuration parameter See below for more details about endpoint publishing 8 6 1 IPv6 On platforms where it is available omniORB supports IPv6 On most Unix plat forms IPv6 sockets accept both IPv6 and IPv4 connections so omniORB s default giop tcp endpoint accepts both IPv4 and IPv6 connections On Windows ver sions before Windows Vista each socket type only accepts incoming connections of the same type so an IPv6 socket cannot be used with IPv4 clients For this rea son the default giop tcp endpoint only listens for IPv4 connections Since endpoints with a specific host name or address only listen on a single network interface they are inherently limited to just one protocol family To explicitly ask for just IPv4 or just IPv6 an endpoint with the wildcard ad dress for the protocol family should be used For IPv4 the wildcard address is 0 0 0 0 and for IPv6 it is So to listen for IPv4 connections on all IPv4 network interfaces use an endpoint of giop tep20 0 40 20 All IPv6 addresses contain colons so the address portion in URIs must be con tained wi
70. ected with the endPoint family of parameters The simplest is plain endPoint which chooses a transport and interface details and publishes the information in IORs Endpoint parameters are in the form of URIs with a scheme name of giop followed by the transport name Different transports have different parameters following the transport TCP endpoints have the format giop tcp lt host gt lt port gt The host must be a valid host name or IP address for the server machine It de termines the network interface on which the server listens The port selects the TCP port to listen on which must be unoccupied Either the host or port or both can be left empty If the host is empty the ORB publishes the IP address of the first non loopback network interface it can find or the loopback if that is the only interface but listens on all network interfaces If the port is empty the operating system chooses a port Multiple TCP endpoints can be selected either to specify multiple network in terfaces on which to listen or less usefully to select multiple TCP ports on which to listen If no endPoint parameters are set the ORB assumes a single parameter of giop tcp meaning lORs contain the address of the first non loopback network interface the ORB listens on all interfaces and the OS chooses a port number SSL endpoints have the same format as TCP ones except t cp is replaced with ssl Unix domain socket endpoints hav
71. ed below The stub code produced by other ORBs will be functionally equivalent to omniORB s but will almost certainly look very different lass Echo lass _objref_Echo C class _impl_Echo typedef _objref_Echo Echo_ptr class Echo public Declarations for this interface type typedef Echo_ptr _ptr_type typedef Echo_var _var_type static _ptr_type _duplicate _ptr_type static _ptr_type _narrow CORBA Object_ptr static _ptr_type _nil methods generated for internal use 8 CHAPTER 2 THE BASICS y class _objref_Echo public virtual CORBA Object public virtual omniObjRef public char echoString const char mesg methods generated for internal use hi In a compliant application the operations defined in an object interface should only be invoked via an object reference This is done by using arrow gt on an object reference For example the call to the operation echoString would be written as ob j gt echoString mesg It should be noted that the concrete type of an object reference is opaque i e you must not make any assumption about how an object reference is implemented In our example even though Echo_ptr is implemented as a pointer to the class _objref_Echo it should not be used as a C pointer i e conversion to void arithmetic operations and relational operations including testing for equality us ing oper
72. ee arguments The cookie is the opaque pointer registered by installTransientException Handler The argument n_retries is the number of times the proxy has called this handler for the same invocation The argument ex is the value of the exception caught The exception handler is expected to do whatever is appropriate and return a boolean value If the return value is TRUE 1 the proxy object retries the operation If the return value is FALSE 0 the original exception is propagated into the application code In the case of a TRANSIENT exception due to a failed location forward the exception propagated to the application is the original excep tion that caused the TRANSIENT e g a COMM_FAILURE or OBJECT_NOT_EXIST rather than the TRANSIENT exception The following sample code installs a simple exception handler for all objects and for a specific object CORBA Boolean my_transient_handlerl void cookie CORBA ULong retries const CORBA TRANSIENT amp ex cerr lt lt transient handler 1 called lt lt endl return 1 retry immediately CORBA Boolean my_transient_handler2 void cookie CORBA ULong retries const CORBA TRANSIENT amp ex This is a change from omniORB 4 0 and earlier where it was the TRANSIENT exception that was propagated to the application 58 CHAPTER 4 OMNIORB CONFIGURATION AND API cerr lt lt transient handler 2 called lt lt endl return 1 retry immediatel
73. efined in the global IDL namespace You should avoid this practice for the sake of object reusability If every CORBA developer de fines their interfaces in the global IDL namespace there is a danger of name clashes between two independently defined interfaces Therefore it is better to qualify your interfaces by defining them inside module names Of course this does not eliminate the chance of a name clash unless some form of naming convention is agreed globally Nevertheless a well chosen module name can help a lot 2 3 Generating the C stubs From the IDL file we use the IDL compiler to produce the C mapping of the interface The IDL compiler for omniORB is called omniidl Given the IDL file omniidl produces two stub files a C header file and a C source file For example from the file echo id1 the following files are produced e echo hh e echoSK cc omniidl must be invoked with the bcxx argument to tell it to generate C stubs The following command line generates the stubs for echo idl omniidl bcxx echo idl If you are using our make environment ODE you don t need to invoke omniidl explicitly In the example file dir mk we have the following line CORBA_INTERFACES echo That is all we need to instruct ODE to generate the stubs Remember you won t find the stubs in your working directory because all stubs are written into the stub directory at the top level of your build tree The full arguments
74. emplates see the CORBA C mapping specification 2 12 SOURCE LISTINGS 21 2 12 Source Listings 2 12 1 egl cc egl cc This is the source code of example 1 used in Chapter 2 The Basics of the omniORB user guide In this example both the object implementation and the client are in the same process Usage egl include lt echo hh gt ifdef HAVE_STD include lt iostream gt using namespace std else include lt iostream h gt endif This is the object implementation class Echo_i public POA_Echo public inline Echo_i virtual Echo_i virtual char echoString const char mesg y char Echo_i echoString const char mesg return CORBA string_dup mesg SILILI This function acts as a client to the object static void hello Echo_ptr e if CORBA is_nil e cerr lt lt hello The object reference is nil n lt lt endl return CHAPTER 2 THE BASICS CORBA String_var src const char Hello String literals are char rather than const char on some old compilers Thus it is essential to cast to const char here to ensure that the string is copied so that the CORBA String_var does not attempt to delete the string literal CORBA String_var dest e gt echoString src cout lt lt I said lt lt char srce lt lt
75. er because it provides important information about the features and APIs that are necessarily omniORB specific With the Portable Object Adapter there are very few omniORB specific details 2 1 The Echo Object Example Our example is an object which has only one method The method simply echos the argument string We have to 1 define the object interface in IDL 2 use the IDL compiler to generate the stub code 3 provide the servant object implementation 4 write the client code These examples are in the src examples echo directory of the omniORB distribution there are several other examples one directory above that in src examples The stub code is the C code that provides the object mapping as defined in the CORBA speci fication 6 CHAPTER 2 THE BASICS 2 2 Specifying the Echo interface in IDL We define an object interface called Echo as follows interface Echo string echoString in string mesg Y If you are new to IDL you can learn about its syntax in Chapter 3 of the CORBA 2 6 specification OMG01 For the moment you only need to know that the in terface consists of a single operation echoSt ring which takes a string as an input argument and returns a copy of the same string The interface is written in a file called echo idl It is part of the CORBA standard that all IDL files should have the extension id1 although omniORB does not enforce this For simplicity the interface is d
76. ersion of the C mapping servant reference counting was optional chosen by inheriting from a mixin class named RefCountServantBase That has been deprecated in the 1 1 version of the C mapping but the class is still available as an empty struct so existing code that inherits from RefCountServantBase will continue to work 2 8 EXAMPLE 1 COLOCATED CLIENT AND IMPLEMENTATION 13 17 cerr lt lt I said lt lt sre lt lt X 18 lt lt The Object said lt lt dest lt lt lt lt endl Briefly the hello function accepts a generic object reference The object reference obj is narrowed to Echo_ptr If the object reference returned by Echo _narrow is not nil the operation echoString is invoked Finally both the argument to and the return value of echoString are printed to cerr The example also illustrates how T_var types are used As was explained in the previous section T_var types take care of storage allocation and release automatically when variables are reassigned or when the variables go out of scope In line 4 the variable e takes over the storage responsibility of the object ref erence returned by Echo _narrow The object reference is released by the destructor of e It is called automatically when the function returns Lines 6 and 15 show how a Echo_var variable is used As explained earlier the Echo_var type can be used interchangeably with the Echo_ptr type The argument and the return
77. etails which no longer work e omniORB 2 did not use distinct types for object references and servants and often accepted a pointer to a servant when the CORBA specification says it should only accept an object reference Such code will not compile under omniORB 4 1 e The reverse is true for BOA 0b3_is_ready It now only works when passed a pointer to a servant object not an object reference The more com monly used mechanism of calling _obj_is_ready boa on the servant ob ject still works as expected 41 42 CHAPTER 3 C LANGUAGE MAPPING e It used to be the case that the skeleton class for interface I _sk_I was de rived from class I This meant that the names of any types declared in the interface were available in the scope of the skeleton class This is no longer true If you have an interface interface I struct S long a b y S op y then where before the implementation code might have been class I_impl public virtual _sk_I S op _sk_I is derived from I hi I S I_impl op S ret Cl wks it is now necessary to fully qualify all uses of S class I_impl public virtual _sk_I I S op _sk_I is not derived from I y I S I_impl op I S ret ff wes e The proprietary omniORB 2 LifeCycle extensions are no longer supported All of the facilities it offered can be implemented with the POA interfaces and the omniORB LOCATION_FORWARD exception see section 4 8 Code wh
78. f the compiler complains about the conversion being ambiguous 10 CHAPTER 2 THE BASICS Echo_ptr p somehow obtain an object referenc a p a assumes ownership of p must not use p any more Echo_var b a implicit _duplicate DOS sa somehow obtain another object reference a Echo _duplicate p release old object reference a now holds a copy of p 2 5 1 Servant Object Implementation Before the Portable Object Adapter POA specification many of the details of how servant objects should be implemented and registered with the system were un specified so server side code was not portable between ORBs The POA specifica tion rectifies that omniORB 4 still supports the old omniORB 2 x BOA mapping but you should always use the POA mapping for new code BOA code and POA code can coexist within a single program See section 3 1 for details of the BOA compatibility and problems you may encounter For each object interface a skeleton class is generated In our example the POA specification says that the skeleton class for interface Echo is named POA_Echo A servant implementation can be written by creating an implementation class that derives from the skeleton class The skeleton class POA_Echo is defined in echo hh The relevant section of the code is reproduced below class POA_Echo public virtual PortableServer ServantBase public Echo_ptr _this virtual char ec
79. hat mode until they are closed 8 5 Idle connection shutdown It is wasteful to leave a connection open when it has been left unused for a con siderable time Too many idle connections could block out new connections when it runs out of spare communication channels For example most platforms have a limit on the number of file handles a process can open Many platforms have a very small default limit like 64 The value can often be increased to a maximum of a thousand or more by changing the ulimit in the shell Every so often a thread scans all open connections to see which are idle The scanning period in seconds is set with the scanGranularit y parameter The default is 5 seconds Outgoing connections initiated by clients and incoming connections initiated by servers have separate idle timeouts The timeouts are set with the out ConScan Period and inConScanPeriod parameters respectively The values are in sec onds and must be a multiple of the scan granularity 8 5 1 Interoperability Considerations The IIOP specification allows both the client and the server to shutdown a connec tion unilaterally When one end is about to shutdown a connection it should send a CloseConnection message to the other end It should also make sure that the message will reach the other end before it proceeds to shutdown the connection The client should distinguish between an orderly and an abnormal connec tion shutdown When a client receives
80. hoString const char mesg 0 Li y The code fragment shows the only member functions that can be used in the object implementation code Other member functions are generated for internal use only As with the code generated for object references other POA based ORBs will generate code which looks different but is functionally equivalent to this echoString It is through this abstract function that an implementation class provides the implementation of the echoString operation Notice that its signa ture is the same as the echoString function that can be invoked via the Echo_ pt r object reference 2 6 WRITING THE SERVANT IMPLEMENTATION 11 _this This function returns an object reference for the target object provided the POA policies permit it The returned value must be deallocated via CORBA release See section 2 8 for an example of how this function is used 2 6 Writing the servant implementation You define an implementation class to provide the servant implementation There is little constraint on how you design your implementation class except that it has to inherit from the stubs skeleton class and to implement all the abstract functions defined in the skeleton class Each of these abstract functions corresponds to an operation of the interface They are the hooks for the ORB to perform upcalls to your implementation Here is a simple implementation of the Echo object class Echo_i public POA_Echo
81. icate the specific circumstances surrounding a system exception The file include omni0RB4 minorCode h contains definitions of all the minor codes used in omniORB cov ering codes allocated in the CORBA specification and ones specific to omniORB In compilers with namespace support the minor code constants appear in names pace omni otherwise they are in the global scope Applications can use minor codes to adjust their behaviour according to the condition e g try 56 CHAPTER 4 OMNIORB CONFIGURATION AND API catch CORBA TRANSIENT amp ex if ex minor omni TRANSIENT ConnectFailed vetry with a different object reference else print an error message 4 7 2 CORBA TRANSIENT handlers TRANSIENT exceptions can occur in many circumstances One circumstance is as follows 1 The client invokes on an object reference 2 The object replies with a LOCATION_FORWARD message 3 The client caches the new location and retries to the new location 4 Time passes 5 The client tries to invoke on the object again using the cached forwarded location 6 The attempt to contact the object fails 7 The ORB runtime resets the location cache and throws a TRANSIENT excep tion with minor code TRANSIENT_FailedOnForwarded In this situation the default TRANSIENT exception handler retries the call using the object s original location If the retry results in another LOCATION_ FORWARD to
82. ich used the old interfaces will have to be rewritten 3 2 omniORB 3 0 compatibility omniORB 4 1 is almost completely source code compatible with omniORB 3 0 There are two main cases where code may have to change The first is code that uses the omniORB API some aspects of which have changed The omniORB con figuration file also has a new format See the next chapter for details of the new API and configuration file The second case of code that may have to change is code using the Dynamic Any interfaces The standard changed quite significantly between CORBA 2 2 and CORBA 2 3 omniORB 3 0 supported the old CORBA 2 2 interfaces omniORB 4 1 uses the new mapping The changes are largely syntax changes rather than se mantic differences 3 3 OMNIORB 4 0 COMPATIBILITY 43 3 3 omniORB 4 0 compatibility omniORB 4 1 is source code compatible with omniORB 4 0 with four exceptions 1 As required by the 1 1 version of the CORBA C mapping specification the RefCountServantBase class has been deprecated and the reference counting functionality moved into ServantBase For backwards compati bility RefCount ServantBase still exists but is now defined as an empty struct Most code will continue to work unchanged but code that explicitly calls RefCountServantBase _add_ref or_remove_ref will no longer compile 2 omniORB 4 0 had an option for Any extraction semantics that was compati ble with omniORB 2 7 where ownership of extracted
83. id the overhead of copying parameters in this way applications can choose to relax the semantics of value copying in local calls so values are not copied at all but are passed by reference In that case the client to a call will see any modifications to the values it passes as parameters and similarly the ob ject implementation will see any changes the client makes to returned values To choose this option set the copyValuesInLocalCalls configuration parameter to zero 13 4 Value box factories With normal valuetypes omniidl generates factory classes with names ending _init as required by the C mapping specification The application is respon sible for registering the factories with the ORB Unfortunately the C mapping makes no mention of factories for value boxes In omniORB factories for value boxes are automatically registered with the ORB and there are no application visible factory classes generated for them Some other 13 5 STANDARD VALUE BOXES 115 CORBA implementations generate application visible factories and the applica tion does have to register the factories with the ORB 13 5 Standard value boxes The standard CORBA StringValue and CORBA WStringValue value boxes are available to application code To make the definitions available in IDL include the standard orb idl 13 6 Covariant returns As required by the C mapping on C compilers that support covariant return types omniidl generates co
84. ie ERE EK RoR OH 9 10 11 12 13 Code set conversion 9 1 Native code sets ce dE Codeset ibrary cossas ce samota Ee Ree Owe Ee RO a 93 Implementing new code se lt s co ccce spice aa e Interceptors 10 1 Interceptor registratiO os i seacb s sub mop arib mani peo dai 102 Available interceptors 2 koe irme e po ae E RE Ee Type Any and TypeCode ILI Peale wing ype Any eh PER A EEE e a Did Tepe ae WIDL ee bo eile oe Be eee ee ee oe 4S E 11 1 2 Inserting and Extracting Basic Types from an Any 11 1 3 Inserting and Extracting Constructed Types from an Any 11 2 Type Any OMICS ee sh bo saor ee ek Ae ee A HA 11 2 1 Generating Insertion and Extraction Operators 11 2 2 TypeCode comparison when extracting from an Any ILES Toplevel aliases as ss ag Oe as WR Ee ae Oe EA 11 2 4 Removing aliases from TypeCodes 11 25 Recursive Type 00s gt pa p sen pa pact ERM EK EE i RS 11 26 Threads and ype ANy ira risser enrian oreari s 11 3 Typecode in omMORB lt e a sasse a a AO A Ml Typecodes WIDE cis eee s Oak a A A AA A WM DEAL e a ae a e GS BS A e aS 11 3 3 Generating TypeCodes for constructed types Re Source Lising oo esiin ed ooa a e ide howd poba CHASED 1141 anyErRample Implee s age HESS oea renka 1142 any Example Cige ions ees da o a eK eK AS Packaging stubs into DLLs 12 1 Dynamic loading and unloading aoaaa 12 2 Windows DLLs aaa a 122
85. implementation of local interface Two will not override the base class s version To overcome this the IDL for the base uncon strained interface must be compiled with the Wbvirtual_objref switch to omniidl That makes the member functions of the mapping of One into virtual functions so they can be overridden The second problem is that in some cases omniORB uses a different mapping for object reference member functions than the mapping used in servant classes For example in the problem operation it uses an internal type for the inout string argument that avoids memory issues if the application uses a String _var in the argument This means that the abstract member function declared in the Two class and implemented by the application has a different signature to the member function in the base class The application supplied class will therefore not prop erly override the base class method In all likelihood the C compiler will also complain that the two member functions are ambiguous The solution to this prob lem is to use the implementation mapping in the base object reference class rather than the normal object reference mapping using the Wbimpl_mapping switch to omniidl The consequence of this is that some uses of _var types for inout argu ments that are normally acceptable in omniORB now lead to memory problems In summary to use local interfaces derived from normal unconstrained inter faces you should compile all your IDL
86. ing resolve_initial references ca aa 6 2 1 ORBInitRef 622 ORBDetiultinitRef i cried eee Bee a ada CIN IN ATES sc a eh a ae RE a ee Oe ee E ELA Gal Naming COMEN ona A 6 3 2 Use with corbaname e A Creating objects with simple object keys Interface Type Checking PL LL Introd ction o ss sa cores a we ee ee a A Interface Inheritance e Connection and Thread Management 8 1 8 2 8 3 8 4 8 5 8 6 8 7 8 8 8 9 Pag ONG ost ote ew Gs oS Hed oe eo a ee Whe MOdE 4 424435 68s oe SAS eet Ld ad BE Client side behaviour ces ese She woe Ge we ee 8 3 1 Client side timeouts Server side behaviour 8 4 1 Thread per connection mode cir 84 2 Thread POS MOde 3 ies cora ri ES Ew ES 843 Policy tanssit gt s sa ses ov de es dar Idle connection shutdown 8 5 1 Interoperability Considerations 0 46s ee be cs Transports and end poms is ee ee ee ee ra o s Be TVG ack ok etek eos eee ee ee ew Gee ee ed 8 6 1 1 Link local addresses 8 6 2 Endp int publishing lt lt s c cea ses escotir dar s Connection selection and acceptance nooo a dul Chenttransport rules ssoi gaa dew A CE eee Yeerks Bia Seryertransportr l s s oessa BRR ERED HERES Bidivechonalts1OP ooer 2 dcsleauee oe be a aS POU MNS POE c so w ee PRR ea ee i
87. inimum by de fault Minimising multiplexing works well when the ORB is relatively lightly loaded However when the ORB is under heavy load it can sometimes be beneficial to conserve operating system resources such as threads and network connections by multiplexing at the ORB level omniORB has various options that control its mul tiplexing behaviour 8 3 Client side behaviour On the client side of a connection the thread that invokes on a proxy object drives the GIOP protocol directly and blocks on the connection to receive the reply The first time the client makes a call to a particular address space the ORB opens a suitable connection to the remote address space based on the client transport rule as described in section 8 7 1 After the reply has been received the ORB caches the open network connection ready for use by another call If two or more threads in a multi threaded client attempt to contact the same address space simultaneously there are two different ways to proceed The de fault way is to open another network connection to the server This means that neither the client or server ORB has to perform any multiplexing on the network connections multiplexing is performed by the operating system which has to deal with multiplexing anyway The second possibility is for the client to multiplex the concurrent requests on a single network connection This conserves operating system resources network connections but means tha
88. it can act as a client to an IfR The omniifr project http omniifr sourceforge net aims to create an IfR for omniORB e omniORB supports interceptors but not the standard Portable Interceptor API These features may be implemented in the short to medium term It is best to check out the latest status on the omniORB home page http omniorb sourceforge net 1 2 Setting up your environment To get omniORB running you first need to install omniORB according to the in structions in the installation notes for your platform Most Unix platforms can use the Autoconf configure script to automate the configuration process 1 3 PLATFORM SPECIFIC VARIABLES 3 Once omniORB is installed in a suitable location you must configure it accord ing to your required set up The configuration can be set with a configuration file environment variables command line arguments or on Windows the Windows registry e On Unix platforms the omniORB runtime looks for the environment variable OMNIORB_CONF IG If this variable is defined it contains the pathname of the omniORB configuration file If the variable is not set omniORB will use the compiled in pathname to locate the file by default etc omni0RB cfg e On Win32 platforms Windows NT 2000 95 98 omniORB first checks the environment variable OMNIORB_CONFIG to obtain the pathname of the con figuration file If this is not set it then attempts to obtain configuration data in the sy
89. ks to be made using a connection opened by the original client rather than the normal model where the server opens a new connection for the callback This is important for negotiating firewalls since they tend not to allow connections back on arbitrary ports There are several steps required for bidirectional GIOP to be enabled for a call back Both the client and server must be configured correctly On the client side these conditions must be met e The of ferBiDirectionalGIOP parameter must be set to true e The client transport rule for the target server must contain the bidir action e The POA containing the callback object or objects must have been created with a BidirectionalPolicy value of BOTH On the server side these conditions must be met e The acceptBiDirectionalGIOP parameter must be set to true e The server transport rule for the requesting client must contain the bidir action e The POA hosting the object contacted by the client must have been created with a BidirectionalPolicy value of BOTH 8 9 SSL transport omniORB supports an SSL transport using OpenSSL It is only built if OpenSSL is available On platforms using Autoconf it is autodetected in many locations or its location can be given with the with openss1 argument to configure On other platforms the OPEN_SSL_ROOT make variable must be set in the platform file To use the SSL transport you must link your application with the omniss1TP
90. l return 0 catch CORBA SystemException amp ex cerr lt lt Caught a CORBA ZN return 0 lt lt ex _name while using the naming service lt lt endl 40 return 1 CHAPTER 2 THE BASICS Chapter 3 C language mapping Now that you are familiar with the basics it is important to familiarise yourself with the standard IDL to C language mapping The mapping is described in detail in OMG03 If you have not done so you should obtain a copy of the docu ment and use that as the programming guide to omniORB The specification is not an easy read The alternative is to use one of the books on CORBA programming that has begun to appear For instance Henning and Vinoski s Advanced CORBA Programming with C HV99 includes many ex ample code bits to illustrate how to use the C mapping 3 1 omniORB 2 BOA compatibility If you use the WbBOA option to omniidl it will generate skeleton code with the same interface as the old omniORB 2 BOA mapping as well as code to be used with the POA Note that since the major problem with the BOA specification was that server code was not portable between ORBs it is unlikely that omniORB 4 1 s BOA compatibility will help you much if you are moving from a different BOA based ORB The BOA compatibility permits the majority of BOA code to compile without difficulty However there are a number of constructs which relied on omniORB 2 implementation d
91. lean true_result A gt _is_ equivalent B Note the above call is guaranteed to be TRUE You have now been introduced to most of the operations that can be invoked via Echo_ptr The generic object CORBA Object provides a few more opera tions and all of them can be invoked via Echo_ptr These operations deal mainly with CORBA s dynamic interfaces You do not have to understand them in order to use the C mapping provided via the stubs Since object references must be released explicitly their usage is prone to error and can lead to memory leakage The mapping defines the object reference variable type to make life easier In our example the variable type Echo_var is defined The Echo_var is more convenient to use because it will automatically release its object reference when it is deallocated or when assigned a new object refer ence For many operations mixing data of type Echo_var and Echo_ptr is possible without any explicit operations or castings For instance the operation echoString can be called using the arrow gt on a Echo_var as one can do with a Echo_ptr The usage of Echo_var is illustrated below Echo_var a 2In omniORB all object reference variable types are instantiated from the template type CORBA_ObjRef_Var However the implementation of the type conversion operator between Echo_var and Echo_ptr varies slightly among different C compilers you may need to do an explicit cast i
92. lf You do this with a special POA with the name omni INSPOA ac quired from resolve_initial_references This POA has the USER_ID and PERSISTENT policies and the special property that the object keys it creates contain only the object ids given to the POA and no other data It is a normal POA in all other respects so you can activate deactivate it create children and so on in the usual way Children of the omniINSPOA do not inherit its special properties of creating simple object keys If the omniINSPOA s policies are not suitable for your applica tion you cannot create a POA with different policies such as single threading for example and still generate simple object keys Instead you can activate a servant in the omniINSPOA that uses location forwarding to redirect requests to objects in a different POA Chapter 7 Interface Type Checking This chapter describes the mechanism used by omniORB to ensure type safety when object references are exchanged across the network This mechanism is han dled completely within the ORB There is no programming interface visible at the application level However for the sake of diagnosing the problem when there is a type violation it is useful to understand the underlying mechanism in order to interpret the error conditions reported by the ORB 7 1 Introduction In GIOP TIOP an object reference is encoded as an Interoperable Object Reference IOR when it is sent across a network
93. like traceLevel 10 Some parameters can have more than one value in which case the parameter name may be specified more than once or you can leave it out InitRef NameService corbaname hostl example com InterfaceRepository corbaloc host2 example com 1234 IfR Note how command line arguments and environment variables prefix pa rameter names with ORB and ORB respectively but the configuration file and the extra argument to ORB_init do not use a prefix 4 1 5 Windows registry On Windows configuration parameters can be stored in the registry under the key HKEY_LOCAL_MACHINE SOFTWARE omniORB The file sample reg shows the settings that can be made It can be edited and then imported into regedit 4 2 Tracing options The following options control debugging trace output traceLevel default 1 omniORB can output tracing and diagnostic messages to the standard error stream The following levels are defined 4 2 TRACING OPTIONS 47 levelO critical errors only levell informational messages only level2 configuration information and warnings level5 notifications when server threads are created and communication endpoints are shutdown level 10 execution and exception traces level 25 trace each send or receive of a giop message level 30 dump up to 128 bytes of each giop message level 40 dump complete contents of each giop message The trace level is cumulative so at level 40 all trace mess
94. lties for DynAny The CORBA 2 6 specification does not mention how shared values inside DynAnys should be handled the CORBA 3 x specification slightly clarifies the situation but it is still unclear To write portable code it is best to avoid manipulating DynAnys containing values that are shared In omniORB when a value inside an Any is converted into a DynAny the value s state is copied into the DynAny and manipulated there When converting back to an Any a new value is created This means that any other references to the original value whether themselves inside Anys of not still relate to the original 13 8 LOCAL INTERFACES 117 value with unchanged state However this copying only occurs when a DynValue is actually created so for example a structure with two value members referring to the same value can manipulated inside a DynAny without breaking the sharing provided the value members are not accessed as DynAnys Extracting the value members as ValueBase will reveal the sharing for example 13 8 Local Interfaces Local interfaces are somewhat under specified in the C mapping This section outlines the way local interfaces are supported in omniORB and details the limi tations and issues 13 8 1 Simple local interfaces With simple IDL there are no particular issues module Test local interface Example string hello in string arg y The IDL compiler generates an abstract base class Test Example Th
95. n kind The kind field is used to indicate the type of the object This is to avoid conventions such as that used by files name typ e g test ps postscript etc try i Resolve the name to an object reference return rootContext gt resolve name catch CosNaming NamingContext NotFound amp ex This exception is thrown if any of the components of the path contexts or the object aren t found cerr lt lt Context not found lt lt endl catch CORBA TRANSIENT amp ex cerr lt lt Caught system exception TRANSIENT unable to contact the lt lt naming service lt lt endl lt lt Make sure the naming server is running and that omniORB is lt lt configured correctly lt lt endl catch CORBA SystemException amp ex cerr lt lt Caught a CORBA lt lt ex _name lt lt while using the naming service lt lt endl return 0 2 12 SOURCE LISTINGS return CORBA Object _nil 35 36 CHAPTER 2 THE BASICS 2 12 6 eg3_tieimpl cc eg3_tieimpl cc This example is similar to eg3_impl cc except that Tf the tie implementation skeleton is used This is the object implementation Lh Usage eg3_tieimpl On startup the object reference is registered with the COS naming service The client uses the naming service to LL locate this object Sf The name which the object is bound to is a
96. never timeout inConScanPeriod default 180 Idle timeout in seconds for incoming If a connection has been idle for this amount of time the ORB closes it See section 8 5 threadPerConnectionPolicy default 1 If true the default the ORB dedicates one server thread to each incoming connec tion Setting it false means the server should use a thread pool maxServerThreadPerConnection default 100 If the client multiplexes several concurrent requests on a single connection omni ORB uses extra threads to service them This parameter specifies the maximum number of threads that are allowed to service a single connection at any one time maxServerThreadPoolSize default 100 The maximum number of threads the server will allocate to do various tasks in cluding dispatching calls in the thread pool mode This number does not include threads dispatched under the thread per connection server mode threadPerConnectionUpperLimit default 10000 If the threadPerConnectionPolicy parameter is true the ORB can automati cally transition to thread pool mode if too many connections arrive This parameter sets the number of connections at which thread pooling is started The default of 10000 is designed to mean that it never happens threadPerConnectionLowerLimit default 9000 If thread pooling was started because the number of connections hit the upper limit this parameter determines when thread per connection should start again
97. ng the stub files As above define USE_stub_in_nt_d11 when in cluding the stub headers into application code 4 Stubs and application code are packaged into multiple DLLs but DLLs con tain the stubs for more than one IDL file This situation is handled by annotating the IDL files to indicate which DLLs they will be compiled into The annotation takes the form of some ifdefs to be inserted in the stub headers For example one idl pragma hh ifndef COMPILING_FIRST_DLL pragma hh ifndef USE_stub_in_nt_dll pragma hh define USE_stub_in_nt_dll pragma hh endif pragma hh endif include lt two idl gt module ModuleOne y two idl pragma hh ifndef COMPILING_SECOND_DLL pragma hh ifndef USE_stub_in_nt_dll pragma hh define USE_stub_in_nt_dll pragma hh endif pragma hh endif include lt three idl gt Here one idl is packaged into first dll and two idl is in second dll When compiling first d11 the COMPILING_FIRST_DLL define is set meaning definitions from one idl and any other files in that DLL are not imported Any other module that includes the stub header for one idl 112 CHAPTER 12 PACKAGING STUBS INTO DLLS does not define COMPILING_FIRST_DLL and thus imports the necessary symbols from the DLL Rather than explicitly listing all the pre processor code it can be cleaner to use a C header file for each D
98. nt argc char argv 3 5A conversion operator of CORBA String_var converts a CORBA String_var toachar Please refer to the C mapping specification for details of the String_var mapping Eu MN CHAPTER 2 THE BASICS CORBA ORB_ptr orb CORBA ORB_init argc argv omniORB4 CORBA Object_var obj orb gt resolve_initial references RootPOA PortableServer POA_var poa PortableServer POA _narrow ob J Echo_i myecho new Echo_i PortableServer ObjectId_var myechoid poa gt activate_object myecho Echo_var myechoref myecho gt _this myecho gt _remove_ref PortableServer POAManager_var pman poa gt the_POAManager pman gt activate hello myechoref VD 0 NJ DoF BW NH FP DBD we N DH A N orb gt destroy return 0 N N N A The example illustrates several important interactions among the ORB the POA the servant and the client Here are the details 2 8 1 ORB initialisation Line 4 The ORB is initialised by calling the CORBA ORB_init function The function uses the optional 3rd argument to determine which ORB should be returned Unless you are using omniORB specific features it is usually best to leave it out and get the default ORB To explicitly ask for omniORB 4 x this argument must be omniORB4 CORBA ORB_init takes the list of command line arguments and pro cesses any that start ORB It removes
99. obal timeout or the timeout for a specific object reference set ClientThreadCallTimeout sets the timeout for the calling thread The calling thread must have an omni_thread associated with it Setting any timeout value to zero disables it Accessing per thread state is a relatively expensive operation so per thread timeouts are disabled by default The supportPerThreadTimeOut parameter must be set true to enable them To choose the timeout value to use for a call the ORB first looks to see if there is a timeout for the object reference then to the calling thread and finally to the global timeout When a client has no existing connection to communicate with a server it must open a new connection before performing the call setClientConnect Timeout sets an overriding timeout for cases where a new connection must be established The effect of the connect timeout depends upon whether the connect timeout is greater or less than the timeout that would otherwise be used As an example imagine that the usual call timeout is 10 seconds Connect timeout gt usual timeout If the connect timeout is set to 20 seconds then a call that establishes a new con nection will be permitted 20 seconds before it times out Subsequent calls using the same connection have the normal 10 second timeout If establishing the connection takes 8 seconds then the call itself takes 5 seconds the call succeeds despite having taken 13 seconds in total longer than
100. od default 0 The timeout that is used in the case that a new network connection is established to the server A value of zero means that the normal call timeout is used See 50 CHAPTER 4 OMNIORB CONFIGURATION AND API section 8 3 1 for more information about timeouts supportPerThreadTimeOut default 0 If this parameter is set true timeouts can be set on a per thread basis as well as globally and per object Checking per thread storage has a noticeable performance impact so it is turned off by default outConScanPeriod default 120 Idle timeout in seconds for outgoing i e client initiated connections If a connec tion has been idle for this amount of time the ORB closes it See section 8 5 maxGIOPConnectionPerServer default 5 The maximum number of concurrent connections the ORB will open to a single server If multiple threads on the client call the same server the ORB opens addi tional connections to the server up to the maximum specified by this parameter If the maximum is reached threads are blocked until a connection becomes free for them to use oneCallPerConnection default 1 When this parameter is set to true the default the ORB will only send a single call on a connection at a time If multiple client threads invoke on the same server mul tiple connections are opened up to the limit specified by maxGIOPConnection PerServer With this parameter set to false the ORB will allow concurrent calls on a
101. ode fragment shown in section 2 9 2 catches the TRANSIENT system exception which indicates that the object could not be contacted at the time of the call usually meaning the server is not running All system exceptions inherit from CORBA SystemException With com pilers that properly support RTTP a single catch of CORBA SystemException will catch all the different system exceptions thrown by omniORB When omniORB detects an internal error such as corrupt data or invalid condi tions it raises the exception omniORB fatalException When this exception is raised it is not sensible to proceed with any operation that involves the ORB s runtime It is best to exit the program immediately The exception structure carried by omniORB fatalException contains the exact location the file name and the line number where the exception is raised In most cases fatalExceptions occur due to incorrect behaviour by the application code but they may be caused by bugs in omniORB 2 9 4 Lifetime of a CORBA object CORBA objects are either transient or persistent The majority are transient mean ing that the lifetime of the CORBA object as contacted through an object reference is the same as the lifetime of its servant object Persistent objects can live beyond the destruction of their servant object the POA they were created in and even their process Persistent objects are of course only contactable when their associ ated servants are
102. of connections it is most efficient to use thread per connection mode If the number of connections becomes too large however operating system limits on the number of threads may cause a significant slowdown or even prevent the acceptance of new connections alto gether 82 CHAPTER 8 CONNECTION AND THREAD MANAGEMENT To give the most efficient response in all circumstances omniORB allows a server to start in thread per connection mode and transition to thread pooling if many connections arrive This is controlled with the threadPerConnection UpperLimit and threadPerConnectionLowerLimit parameters The former must always be larger than the latter The upper limit chooses the number of con nections at which time the ORB transitions to thread pool mode the lower limit selects the point at which the transition back to thread per connection is made For example setting the upper limit to 50 and the lower limit to 30 would mean that the first 49 connections would receive dedicated threads The 50th to arrive would trigger thread pooling All future connections to arrive would make use of threads from the pool Note that the existing dedicated threads continue to service their connections until the connections are closed If the number of connections falls below 30 thread per connection is reactivated and new connections receive their own dedicated threads up to the limit of 50 again Once again existing connections in thread pool mode stay in t
103. ok y y but not if there are cross module dependencies module M1 interface I y module M2 interface J attribute M1 I ok y y module M1 interface K attribute M2 J oh_dear y y In both of these cases the Wosplice modules option causes omniidl to put all of the definitions for module M1 into a single C class For the first case this will work fine For the second case class M1 K will contain a reference to M2 J which has not yet been defined the C compiler will complain 5 2 3 Flattened tie classes Another problem with mapping IDL modules to C classes arises with tie tem plates The C mapping says that for the interface M 1 the C tie template class should be named POA_M 1_tie However since template classes cannot be declared inside other classes this naming scheme cannot be used with compil ers without namespace support 5 3 EXAMPLES 65 The standard solution is to produce flattened tie class names using the wbt f command line argument With that flag the template class is declared at global scope with the name POA_M_I_tie i e all occurrences of are replaced by _ 5 2 4 Generating example implementations If you use the Wbexample flag omniidl will generate an example implementation file as well as the stubs and skeletons For IDL file foo id1 the example code is written to foo_i cc The example file contains class and method declarations fo
104. on IIOP is usually asymmetric with respect to the roles of the parties at the two ends of a connection At one end is the client which can only initiate remote invocations At the other end is the server which can only receive remote invocations Notice that in CORBA as in most distributed systems remote bindings are established implicitly without application intervention This provides the illusion that all objects are local a property known as location transparency CORBA does not specify when such bindings should be established or how they should be multiplexed over the underlying network connections Instead ORBs are free to implement implicit binding by a variety of means The rest of this chapter describes how omniORB manages network connections and the programming interface to fine tune the management policy IGIOP 1 2 supports bidirectional GIOP which permits the r les to be reversed 77 78 CHAPTER 8 CONNECTION AND THREAD MANAGEMENT 8 2 The model omniORB is designed from the ground up to be fully multi threaded The objec tive is to maximise the degree of concurrency and at the same time eliminate any unnecessary thread overhead Another objective is to minimise the interference by the activities of other threads on the progress of a remote invocation In other words thread cross talk should be minimised within the ORB To achieve these objectives the degree of multiplexing at every level is kept to a m
105. one shown here 12 2 2 Importing constant symbols As if exporting the symbols from a DLL was not complicated enough any constant values exported by a DLL have to be explicitly imported into the code using them omniORB s stub files declare a number of such constants This time the constant declarations in the generated header files are decorated in a way that tells the com piler what to do When the stub headers are included the correct pre processor defines must be set If things are not set correctly the code all links without prob lems but then mysteriously blows up at run time Depending on how complex your situation is there are a range of solutions Starting with the simplest here are some scenarios you may find yourself in 1 All stub code and all code that uses it is wrapped up in a single DLL Do nothing special 2 All stub code is in a single DLL Code using it is in another DLL or not in a DLL at all tdefine USE_stub_in_nt_dll before include of the stub headers 12 2 WINDOWS DLLS 111 3 The stubs for each IDL file are in separate DLLs one DLL per IDL file In this case if the IDL files include each other when the stub files are com piled import declarations are needed so that references between the separate DLLs work To do this first compile the IDL files with the wod11_stubs flag omniidl bcxx Wbdll_stubs example idl Then define the INCLUDED_stub_in_nt_dl1l pre processor symbol when compili
106. option to suppress them 5 1 3 Comments By default omniidl discards comments in the input IDL However with the k and K options it preserves the comments for use by the back ends The C back end ignores this information but it is relatively easy to write new back ends which do make use of comments 5 2 C BACK END OPTIONS 63 The two different options relate to how comments are attached to declarations within the IDL Given IDL like interface I void opl A comment void op2 y the k flag will attach the comment to op1 the K flag will attach it to op2 5 2 C back end options When you specify the C back end with bcxx the following Wb options are available Note that the Wb options must be specified after the bcxx option so omniidl knows which back end to give the arguments to Wbh suffix Use suffix for generated header files Default hh Wb s suffix Use suffix for generated stub files Default SK cc Whd suffix Use suffix for generated dynamic files Default DynSK cc Wba Generate stubs for TypeCode and Any Wbinline Output stubs for included IDL files in line with the main file Wbtp Generate tie implementation skeletons Wbt f Generate flattened tie implementation skeletons Wbsplice modules Splice together multiply opened modules into one Wbexample Generate example implementation code WbF Generate code fragments for experts only
107. or look ups using the obsolete Sun bootstrap agent This mechanism is superseded by the interoperable naming service bootstrapAgentPort default 900 The port number for the obsolete Sun bootstrap agent principal default none GIOP 1 0 and 1 1 have a request header field named principal which contains a sequence of octets It was never defined what it should mean and its use is now deprecated GIOP 1 2 has no such field Some systems e g Gnome use the principal field as a primitive authentication scheme This parameter sets the data omniORB uses in the principal field The default is an empty sequence 4 5 Server side options These parameters affect server side operations endPoint default giop tcp endPointNoListen endPointPublish endPointNoPublish endPointPublishAllIFs These options determine the end points the ORB should listen on and the details that should be published in IORs See chapter 8 for details serverTransportRule default unix tcp ssl Configure the rules about whether a server should accept an incoming connection from a client See section 8 7 2 for details 52 CHAPTER 4 OMNIORB CONFIGURATION AND API serverCallTimeOutPeriod default 0 This timeout is used to catch the situation that the server starts receiving a request but the end of the request never comes If a calls takes longer than the specified number of milliseconds to arrive the ORB shuts the connection A value of zero means
108. ore ior cc decodeIOR Called when decoding an IOR The application can use this to get out what ever information they put into IORs with encodeIOR Again see extract SupportedComponents in src lib omniORB orbcore ior cc for an example clientSendRequest Called just before a request header is sent over the network The application can use it to insert service contexts in the header See set CodeSet Servic Context in src lib omniORB orbcore cdrStream cc for an ex ample of its use 10 2 AVAILABLE INTERCEPTORS 93 clientReceiveReply Called as the client receives a reply just after unmarshalling the reply header Called for normal replies and exceptions serverReceiveRequest Called when the server receives a request just after unmarshalling the re quest header See the get CodeSetServiceContext function in src lib omniORB orbcore cdrStream cc for an example serverSendReply Called just before the server marshals a reply header serverSendException Called just before the server marshals an exception reply header createldentity Called when the ORB is about to create an identity object to represent a CORBA object It allows application code to provide its own identity imple mentations It is very unlikely that an application will need to do this create ORBServer Used internally by the ORB to register different kinds of server At present only a GIOP server is registered It is very unlikely that application
109. orm more upcalls or reused for a different purpose Unlike the other interceptors the interceptor functions for createThread and assignUpcallThread have no return value Interceptor chaining is performed by calls through the info_T run method rather than by visiting inter ceptor functions in turn Except that with the threadPoolWatchConnection parameter set true a thread can perform mul tiple upcalls even when thread pool mode is active Chapter 11 Type Any and TypeCode The CORBA specification provides for a type that can hold the value of any OMG IDL type This type is known as type Any The OMG also specifies a pseudo object TypeCode that can encode a description of any type specifiable in OMG IDL In this chapter an example demonstrating the use of type Any is presented This is followed by sections describing the behaviour of type Any and TypeCode in omniORB For further information on type Any refer to the C Mapping spec ification and for more information on TypeCode refer to the Interface Repository chapter in the CORBA core section of the CORBA specification 11 1 Example using type Any Before going through this example you should make sure that you have read and understood the examples in chapter 2 The source code for this example is included in the omniORB distribution in the directory src examples anyExample A listing of the source code is provided at the end of this chapter 11 1 1 Type Any in IDL
110. our That is no longer the case Any extraction is now thread safe 11 3 TypeCode in omniORB This section contains some notes on the use and behaviour of TypeCode in omni ORB 11 3 1 TypeCodes in IDL When using TypeCodes in IDL note that they are defined in the CORBA scope Therefore CORBA TypeCode should be used Example Z7 IDE 5 struct Test5 long length CORBA TypeCode desc y 11 3 TYPECODE IN OMNIORB 101 11 3 2 orb idl The CORBA specification says that IDL using CORBA TypeCode must include the file orb idl That is not required in omniORB but a suitable orb idl is available 11 3 3 Generating TypeCodes for constructed types To generate a TypeCode for constructed types specify the wba command line flag when running omniidl This will generate a _tc_ TypeCode describing the type at the same scope as the type Example IDL 6 struct Test6 double a sequence lt long gt b y A TypeCode _tc_Test 6 will be generated to describe the struct Test 6 The operations defined in the TypeCode interface can be used to query the TypeCode about the type it represents 102 CHAPTER 11 TYPE ANY AND TYPECODE 11 4 Source Listing 11 4 1 anyExample_impl cc anyExample_impl cc This is the source code of th xample used in Chapter 9 Type Any and TypeCode of the omniORB users guide Vi This is the object implementation Z Usage anyExample impl On startu
111. p the object reference is printed to cout as a stringified IOR This string should be used as the argument to anyExample_clt include lt anyExample hh gt ifdef HAVE_STD include lt iostream gt using namespace std else include lt iostream h gt endif T class anyExample_i public POA_anyExample public inline anyExample_i virtual anyExample_i virtual CORBA Any testOp const CORBA Any amp a y CORBA Any anyExample_1 testOp const CORBA Anyg a cout lt lt Any received containing lt lt endl ifndef NO FLOAT CORBA Double d endif CORBA Long 1 const char str testStruct tp if a gt gt 1 11 4 SOURCE LISTING 103 cout lt lt Long lt lt 1 lt lt endl ifndef NO_FLOAT XXX should we provide stream ops for _CORBA_Double_ and _CORBA_Float_on VMS else if a gt gt d cout lt lt Double lt lt double d lt lt endl endif else if a gt gt str cout lt lt String lt lt str lt lt endl else if a gt gt tp cout lt lt testStruct 1 lt lt tp gt 1 lt lt endl cout lt lt s lt lt tp gt s lt lt endl else cout lt lt Unknown value lt lt endl CORBA Any ap new CORBA Any ap lt lt CORBA ULong 314 cout lt lt Returning Any containing ULong 314 n lt lt endl retu
112. p1 cc and the client eg3_c1t cc can be found at the end of this chap ter The names used by the Naming service consist of a sequence of name compo nents Each name component has an id and a kind field both of which are strings All name components except the last one are bound to a naming context A nam ing context is analogous to a directory in a filing system it can contain names of object references or other naming contexts The last name component is bound to an object reference Sequences of name components can be represented as a flat string using to separate the id and kind fields and to separate name components from each other In our example the Echo object reference is bound to the stringified name test my_context Echo Object The kind field is intended to describe the name in a syntax independent way The naming service does not interpret assign or manage these values However both the name and the kind attribute must match for a name lookup to succeed In this example the kind values for test and Echo are chosen to be my_context and Object respectively This is an arbitrary choice as there is no standardised set of kind values 2 10 1 Obtaining the Root Context Object Reference The initial contact with the Naming Service can be established via the root context The object reference to the root context is provided by the ORB and can be ob tained by calling resolve_initial_references
113. parated list of publish rules The rules are applied in turn to each of the configured endpoints if a rule matches an endpoint it causes one or more endpoints to be published The following core rules are supported addr the first natural address of the endpoint ipv4 the first IPv4 address of a TCP or SSL endpoint ipv6 the first IPv6 address of a TCP or SSL endpoint name the first address that can be resolved to a name hostname the result of the gethostname system call fqdn the fully qualified domain name The core rules can be combined using the vertical bar operator to try several rules in turn until one succeeds e g name ipv6 ipv4 the name of the endpoint if it has one failing that its first IPv6 address failing that its first IPv4 address Multiple rules can be combined using the comma operator to publish more than one endpoint e g name addr the name of the endpoint if it has one followed by its first address For endpoints with multiple addresses e g TCP endpoints on multi homed ma chines the a11 manipulator causes all addresses to be published e g all addr all addresses are published all name all addresses that resolve to names are published all name addr all addresses are published by name if they have one address otherwise all name addr all addresses are published by name if they have one and by address all name first the names of all addresses are p
114. peCode_ptr of the Any interface to explicitly set the TypeCode to the correct one 11 2 4 Removing aliases from TypeCodes Some ORBs such as old versions of Orbix will not accept TypeCodes contain ing tk_alias TypeCodes When using type Any while interoperating with these 100 CHAPTER 11 TYPE ANY AND TYPECODE ORBs it is necessary to remove tk_alias TypeCodes from throughout the Type Code representing a constructed type To remove all tk_alias TypeCodes from TypeCodes transmitted in Anys supply the ORBtcAliasExpand 1 command line flag when running an omni ORB executable There will be some small performance penalty when transmit ting Any values Note that the _tc_ TypeCodes generated for all constructed types will con tain the complete TypeCode for the type including any tk_alias TypeCodes regardless of whether the ORBt cAliasExpand flag is set to 1 or not It is only when Anys are transmitted that the aliases are stripped 11 2 5 Recursive TypeCodes omniORB supports recursive TypeCodes This means that types such as the fol lowing can be inserted or extracted from an Any IDL 4 struct Test4 sequence lt Test4 gt a y 11 2 6 Threads and type Any Inserting and extracting simultaneously from the same Any in 2 different threads results in undefined behaviour In versions of omniORB before 4 0 extracting simultaneously from the same Any in 2 or more different threads also led to undefined behavi
115. ppli cation Applications can override the default behaviour by installing their own exception handlers The API to do so is summarised below 4 8 LOCATION FORWARDING 59 typedef CORBA Boolean systemExceptionHandler_t void cookie CORBA ULong n_retries const CORBA SystemException amp ex void installSystemExceptionHandler void cookie systemExceptionHandler_t fn void installSystemExceptionHandler CORBA Object_ptr obj void cookie systemExceptionHandler_t fn The functions are equivalent to their counterparts for CORBA TRANSIENT 4 8 Location forwarding Any CORBA operation invocation can return a LOCATION_FORWARD message to the caller indicating that it should retry the invocation on a new object reference The standard allows ServantManagers to trigger LOCATION_FORWARDs by rais ing the PortableServer ForwardRequest exception but it does not provide a similar mechanism for normal servants omniORB provides the omni0RB LOCATION_FORWARD exception for this purpose It can be thrown by any oper ation implementation namespace omniORB class LOCATION_FORWARD public LOCATION_FORWARD CORBA Object_ptr objref y The exception object consumes the object reference it is passed 60 CHAPTER 4 OMNIORB CONFIGURATION AND API Chapter 5 The IDL compiler omniORB s IDL compiler is called omniidl It consists of a generic front end parser written in C and a number
116. r the operations of all interfaces in the IDL file along with a main function which creates an instance of each object You still have to fill in the operation implementations of course 5 3 Examples Generate the C headers and stubs for a file a idl omniidl bexx a idl Generate with Any support omniidl bcxx Wba a idl As above but also generate Python stubs assuming omniORBpy is installed omniidl bcxx Wba bpython a idl Just check the IDL files for validity generating no output omniidl a idl b idl 66 CHAPTER 5 THE IDL COMPILER Chapter 6 Interoperable Naming Service omniORB supports the Interoperable Naming Service INS The following is a summary of its facilities 6 1 Object URIs As well as accepting IOR format strings ORB string_to_object also sup ports two Uniform Resource Identifier URI BLFIM98 formats which can be used to specify objects in a convenient human readable form IOR format strings are now also considered URIs 6 1 1 corbaloc corbaloc URIs allow you to specify object references which can be contacted by IIOP or found through ORB resolve_initial_references To specify an IIOP object reference you use a URI of the form corbaloc iiop lt host gt lt port gt lt object key gt for example corbaloc iiop myhost example com 1234 MyObjectKey which specifies an object with key MyObjectKey within a process running on myhost example com listening on port 1234 O
117. rameters in local calls are copied or not See chapter 13 abortOnInternalError default 0 If this is set true internal fatal errors will abort immediately rather than throw ing the omniORB fatalException exception This can be helpful for tracking down bugs since it leaves the call stack intact 4 4 Client side options These options control aspects of client side behaviour InitRef default none Specify objects available from ORB resolve_initial_references The arguments take the form lt key gt lt uri gt where key is the name given to resolve_ initial_references and uri is a valid CORBA object reference URI as de tailed in chapter 6 DefaultInitRef default none Specify the default URI prefix for resolve_initial_references as ex plained in chapter 6 clientTransportRule default unix tcp ssl Used to specify the way the client contacts a server depending on the server s address See section 8 7 1 for details clientCallTimeOutPeriod default 0 Call timeout in milliseconds for the client side If a call takes longer than the speci fied number of milliseconds the ORB closes the connection to the server and raises a TRANSIENT exception A value of zero means no timeout calls can block for ever See section 8 3 1 for more information about timeouts Note omniORB 3 had timeouts specified in seconds omniORB 4 0 and later use milliseconds for timeouts clientConnectTimeOutPeri
118. rce code of example 2 used in Chapter 2 The Basics of the omniORB user guide This is the client The object reference is given as a stringified IOR on the command line Usage eg2_clt lt object reference gt include lt echo hh gt ifdef HAVE_STD include lt iostream gt include lt fstream gt using namespace std include lt iostream h gt endif static void hello Echo_ptr e CORBA String_var src const char Hello CORBA String_var dest e gt echoString src cout lt lt I said lt lt char src lt lt X lt lt endl lt lt The Echo object replied lt lt char dest lt lt X lt lt endl IAAAAAAAAAAAAAAAA ASA AAA AAA AAA AAA AAA AAA AA AAAAAAAAA AAA AAA AAA AAA AA ANN NSS int main int argc char argv try CORBA ORB_var orb CORBA ORB_init argc argv if argc 2 cerr lt lt usage eg2_clt lt object reference gt lt lt endl return 1 CORBA Object_var obj orb gt string_to_object argv 1 Echo_var echoref Echo _narrow obj if CORBA is_nil echoref 2 12 SOURCE LISTINGS 27 cerr lt lt Can t narrow reference to type Echo or it was nil lt lt endl return 1 for CORBA ULong count 0 count lt 10 count hello echoref orb gt destroy catch CORBA TRANSIENT amp cerr lt lt Caught system exception TRANSIENT unable to contact the lt lt
119. request and just be fore it makes the call into application code it marks the connection as selectable meaning that another thread should watch it to see if any other requests arrive If they do extra threads are dispatched to handle the concurrent calls GIOP 1 2 actu ally allows the argument data for multiple calls to be interleaved on a connection 8 4 SERVER SIDE BEHAVIOUR 81 so the unmarshalling code has to handle that too As soon as any multiplexing oc curs on the connection the aim of removing thread switching cannot be met and there is inevitable inefficiency due to thread switching The maxServerThreadPerConnection parameter can be set to limit the number of threads that can be allocated to a single connection containing concur rent calls Setting the parameter to 1 mimics the behaviour of omniORB versions before 4 0 that did not support calls multiplexed on one connection 8 4 2 Thread pool mode In thread pool mode selected by setting the threadPerConnectionPolicy pa rameter to zero a single thread watches all incoming connections When a call arrives on one of them a thread is chosen from a pool of threads and set to work unmarshalling the arguments and performing the up call There is therefore at least one thread switch for each call The thread pool is not pre initialised Instead threads are started on demand and idle threads are stopped after a period of inactivity The maximum number of threads that
120. result of filtering the endpoint specifications in an IOR with the client transport rule will be a prioritised list of transports and networks If the transport rules do not prioritise one endpoint over another the order the end points are listed in the IOR is used When trying to contact an object the ORB tries its possible endpoints in turn until it finds one with which it can contact the object Only after it has unsuccessfully tried all permissible endpoints will it raise a TRANSIENT exception to indicate that the connect failed 8 7 2 Server transport rules The server transport rules have the same format as client transport rules Rather than being used to select which of a set of ways to contact a machine they are used to determine whether or not to accept connections from particular clients In this example we only allow connections from our intranet serverTransportRule localhost unix tcp ssl 172 16 0 0 255 240 0 0 tcp ssl none And in this one we accept only SSL connections if the client is not on the intranet serverTransportRule localhost unix tcp ssl 172 16 0 0 255 240 0 0 tcp ssl ssl bidir 88 CHAPTER 8 CONNECTION AND THREAD MANAGEMENT In the absence of any explicit rules the server uses the implicit rule of unix ssl tcp meaning any kind of connection is accepted from any client 8 8 Bidirectional GIOP omniORB supports bidirectional GIOP which allows callbac
121. return a valid object reference Otherwise it will return a nil object reference Note that _narrow performs an implicit duplication of the object reference so the result must be released Note also that _narrow may involve a remote call to check the type of the object so it may throw CORBA system exceptions such as COMM_FAILURE or OBJECT_NOT_EXIST 2 5 A QUICK TOUR OF THE C STUBS 9 To indicate that an object reference will no longer be accessed you must call the CORBA release operation Its signature is as follows namespace CORBA void release CORBA Object_ptr obj other methods y Once you have called CORBA release on an object reference you must no longer use that reference This is because the associated resources may have been deallocated Notice that we are referring to the resources associated with the object reference and not the servant object Servant objects are not affected by the lifetimes of object references In particular servants are not deleted when all references to them have been released CORBA does not perform distributed garbage collection As described above the equality operator should not be used on object references To test if two object references are equivalent the member function _is_equivalent of the generic object CORBA Object can be used Here is an example of its usage Echo_ptr A initialise A to a valid object reference Echo_ptr B A CORBA Boo
122. rn ap IAAAAAAAAAAAAA AAA AAA AAA A AAA AAA AAA AAA SSSA SAAS ASSL LLL ALAA AAA AAA ASS int main int argc char argv try CORBA ORB_var orb CORBA ORB_init argc argv CORBA Object_var obj orb gt resolve_initial_references RootPOA PortableServer POA_var poa PortableServer POA _narrow obj anyExample_i myobj new anyExample_i PortableServer ObjectId_var myobjid poa gt activate_object myobj obj myobj gt _this CORBA String_var sior orb gt object_to_string obj cout lt lt char sior lt lt endl myobj gt _remove_ref PortableServer POAManager_var pman poa gt the_POAManager 104 pman gt activate orb gt run orb gt destroy CHAPTER 11 TYPE ANY AND TYPECODE catch CORBA SystemException amp ex cerr lt lt Caught CORBA lt lt ex _name lt lt endl catch CORBA Exception amp ex cerr lt lt Caught CORBA Exception lt lt ex _name lt lt endl catch omniORB fatalException amp fe cerr lt lt Caught omniORB fatalException lt lt endl cerr lt lt file lt lt fe file lt lt endl cerr lt lt line lt lt fe line lt lt endl cerr lt lt mesg lt lt fe errmsg lt lt endl return 0 11 4 SOURCE LISTING 11 4 2 anyExample_clt cc anyExample_clt cc 105 This is the source code of the example use
123. s an instance of valuetype Two in both parameters and suppose that the server has not seen the definition of val uetype Two In this situation as the first parameter is unmarshalled it will be truncated to valuetype One as required Now when the Any is unmarshalled it refers to the same value which has been truncated So even though the TypeCode in the Any indicates that the value has type Two the stored value actually has type One If the receiver of the Any tries to pass it on transmission will fail because the Any s value does not match its TypeCode In the opposite situation where an Any parameter comes before a valuetype parameter a different problem occurs In that case as the Any is unmarshalled there is no type information available for valuetype Two so the value inside the Any has an internal omniORB type used for unknown valuetypes As the next parameter is unmarshalled omniORB sees that the shared value is unknown and is able to convert it to the target One valuetype with truncation In this case the Any and the plain valuetype both have the correct types and values but the fact that both should have referred to the same value has been lost Because of these issues it is best to avoid defining interfaces that mix value types and Anys in a single operation and certainly to avoid trying to share plain values with values inside Anys 13 7 1 Values inside DynAnys The sharing semantics of valuetypes can also cause difficu
124. s follows root context test context kind my_context Th Echo object kind Object LA include lt echo hh gt ifdef HAVE_STD include lt iostream gt using namespace std else include lt iostream h gt endif static CORBA Boolean bindObjectToName CORBA ORB_ptr CORBA Object_ptr This is the object implementation Notice that it does not inherit from any stub class and notice that the echoString member function does not have to be virtual class Echo_i public inline Echo_i inline Echo_i char echoString const char mesg y char Echo_i echoString const char mesg return CORBA string_dup mesg 2 12 SOURCE LISTINGS 37 IAAAAAAAAAAAA AAA SAA AAA A AAA AAA AAA AAA AAA AAAAAAAAAA AAA AA AAA AAAS int main int argc char argv try CORBA ORB_var orb CORBA ORB_init argc argv CORBA Object_var obj orb gt resolve_initial_references RootPOA PortableServer POA_var poa PortableServer POA _narrow obj Note that the lt myecho gt tie object is constructed on the stack here It will delete its implementation myimpl when it it itself destroyed when it goes out of scope It is essential however to ensure that such servants are not deleted whilst still activated Tie objects can of course be allocated on the heap using new in which case they are delete
125. s_a call is not performed when the IOR is unmarshalled It is performed just prior to the first application invocation on the object This leads to some interesting failure modes if B reports that it is not an A Consider the following example IDL interface A 7 2 INTERFACE INHERITANCE 75 interface B A interface D interface C A opl Object op2 y C C ptr ob jC A_ptr objA CORBA Object_ptr objR objA objC gt opl void objA gt _non_existent o 0 NX Do Fk WN RB objR objC gt op2 objA A _narrow ob3R m If the stubs of A B C D are linked into the executable and Case 1 C op1 and C op2 return a B Lines 6 10 complete successfully The remote object is only contacted at line 7 Case 2 C op1 and C op2 return a D This condition only occurs if the runtime of the remote end is buggy Even though the IDL definitions show that D is not derived from A omniORB gives it the benefit of the doubt in case it actually has a more derived interface that is derived from both A and D At line 7 the object is contacted to ask if it is an A The answer is no so a CORBA INV_OBJREF exception is raised At line 10 the narrow operation will fail and objA will be set to nil If only the stubs of A are linked into the executable and Case 1 C op1 and C op2 return a B Lines 6 10 complete successfully When lines 7 and 10 are execu
126. se prevents the use of indirections and therefore recursive TypeCodes acceptMisalignedTcIndirections default 0 If true try to fix a mis aligned indirection in a typecode This is used to work around a bug in some old versions of Visibroker s Java ORB 4 7 System Exception Handlers By default all system exceptions that are raised during an operation invocation with the exception of some cases of CORBA TRANSIENT are propagated to the application code Some applications may prefer to trap these exceptions within the proxy objects so that the application logic does not have to deal with the error condition For example when a CORBA COMM_FAILURE is received an applica tion may just want to retry the invocation until it finally succeeds This approach is useful for objects that are persistent and have idempotent operations omniORB provides a set of functions to install exception handlers Once they are installed proxy objects will call these handlers when the associated system ex ceptions are raised by the ORB runtime Handlers can be installed for CORBA TRANSIENT CORBA COMM_FATLURE and CORBA SystemException This last handler covers all system exceptions other than the two covered by the first two handlers An exception handler can be installed for individual proxy objects or it can be installed for all proxy objects in the address space 4 7 1 Minor codes omniORB makes extensive use of exception minor codes to ind
127. single connection This saves connection resources but requires slightly more management work for both client and server Some server side ORBs including omniORB versions before 4 0 serialise all calls on a single connection offerBiDirectionalGIOP default 0 If set true the client will indicate to servers that it is willing to accept callbacks on client initiated connections using bidirectional GIOP provided the relevant POA policies are set See section 8 8 diiThrowsSysExceptions default 0 If this is true DII functions throw system exceptions if it is false system exceptions that occur are passed through the Environment object verifyObjectExistsAndType default 1 By default omniORB uses the GIOP LOCATE_REQUEST message to verify the ex istence of an object prior to the first invocation In the case that the full type of 4 5 SERVER SIDE OPTIONS 51 the object is not known it instead calls the _is_a operation to check the ob ject s type Some ORBs have bugs that mean one or other of these operations fail Setting this parameter false prevents omniORB from making these calls giopTargetAddressMode default 0 GIOP 1 2 supports three addressing modes for contacting objects This parameter selects the mode that omniORB uses A value of 0 means GIOP KeyAddr 1 means GIOP ProfileAddr 2 means GIOP ReferenceAddr bootstrapAgentHostname default none If set this parameter indicates the hostname to use f
128. stem registry It searches for the data under the key HKEY_LOCAL_ MACHINE SOFTWARE omniORB omniORB has a large number of parameters than can be configured See chap ter 4 for full details The files sample cfg and sample reg contain an example configuration file and set of registry entries respectively To get all the omniORB examples running the main thing you need to config ure is the Naming service omniNames To do that the configuration file or registry should contain an entry of the form InitRef NameService corbaname my host name See section 6 1 2 for full details of corbaname URIs 1 3 Platform specific variables To compile omniORB programs correctly several C preprocessor defines must be specified to identify the target platform On Unix platforms where omniORB was configured with Autoconf the omniconfig h file sets these for you On other platforms and Unix platforms when Autoconf is not used you must specify the following defines 4 CHAPTER 1 INTRODUCTION Platform CPP defines Windows NT 4 0 2000 XP __x86__ NTS __OSVERSION__ 4 _ WIN32__ Windows NT 3 5 __ x86__ __ NT__ __OSVERSION__ 3 _ WIN32__ Windows 95 _x86__ _ WIN32__ Sun Solaris 2 5 __sparc__ _ sunos__ _ OSVERSION__ 5 HPUX 10 x _ hppa__ __ hpux__ _ OSVERSION__ HPUX 11 x __hppa__ __hpux__ _ OSVERSION__ IBM AIX 4 x _ailx _ _powerpec__ _ OSVERSION__ 4 Digital Unix 3 2 __alpha__ _ osfl__ _ OSVERSION__ 3 Linux 2 x x86 _x86__ _ linux_
129. t When using OrbixNames it is necessary to first try bind and then rebind as rebind on it s own will throw a NotFoundexception if the Name has not already been bound This is incorrect behaviour it should just bind h CORBA TRANSIENT amp ex rr lt lt Caught system exception TRANSIENT unable to contact the lt lt naming service lt lt endl lt lt Make sure the naming server is running and that omniORB is lt lt configured correctly lt lt endl turn 0 catch CORBA SystemException amp ex ce rr lt lt Caught a CORBA lt lt ex _name lt lt while using the naming service lt lt endl return 0 retu rn 1 32 2 12 CHAPTER 2 THE BASICS 5 eg3_clt cc eg3_clt cc This is the source code of example 3 used in Chapter 2 A The Basics of the omniORB user guide This is the client It uses the COSS naming service to obtain the object reference Usage eg3_clt LL On startup the client lookup the object reference from the ES COS naming service ZZ The name which the object is bound to is as follows root context LH text context kind my_context Echo object kind Object include lt echo hh gt ifdef HAVE_STD include lt iostream gt using namespace std else include lt iostream h gt endif T static CORBA Object_ptr getObjectReference
130. t does not contain a value of that type the extraction operator returns False If the Any does contain that type the extraction operator returns True If the extrac tion is successful the caller s pointer will point to memory managed by the Any The caller must not delete or otherwise change this storage and should not use this storage after the contents of the Any are replaced either by insertion or as signment or after the Any has been destroyed In particular management of the pointer should not be assigned to a _var type If the extraction fails the caller s pointer will be set to point to null Note that there are special rules for inserting and extracting arrays using the _forany types and for inserting and extracting bounded strings booleans chars and octets Please refer to the C Mapping specification for further information 11 2 Type Any in omniORB This section contains some notes on the use and behaviour of type Any in omni ORB 11 2 1 Generating Insertion and Extraction Operators To generate type Any insertion and extraction operators for constructed types and interfaces the wba command line flag should be specified when running omniidl 11 2 2 TypeCode comparison when extracting from an Any When an attempt is made to extract a type from an Any the TypeCode of the type is checked for equivalence with the TypeCode of the type stored by the Any The 11 2 TYPE ANY IN OMNIORB 99 equivalent test in th
131. t both the client and server have to deal with multiplexing issues themselves In the default one call per connection mode there is a limit to the number of concurrent connections that are opened set with the maxGIOPConnection PerServer parameter To tell the ORB that it may multiplex calls on a single con nection set the oneCal1lPerConnection parameter to zero If the oneCallPer Connection parameter is set to the default value of one and there are more concurrent calls than specified by maxGIOPConnectionPerServer calls block waiting for connections to become free Note that some server side ORBs including omniORB versions before version 4 0 are unable to deal with concurrent calls multiplexed on a single connection so they serialise the calls It is usually best to keep to the default mode of opening multiple connections 8 3 CLIENT SIDE BEHAVIOUR 79 8 3 1 Client side timeouts omniORB can associate a timeout with a call meaning that if the call takes too long a TRANSIENT exception is thrown Timeouts can be set for the whole process for a specific thread or for a specific object reference Timeouts are set using this API namespace omniORB void setClientCallTimeout CORBA ULong millisecs void setClientCallTimeout CORBA Object_ptr obj CORBA ULong void setClientThreadCallTimeout CORBA ULong millisecs void setClientConnectTimeout CORBA ULong millisecs y setClientCallTimeout sets either the gl
132. t timeout of 2 seconds the client will spend up to 2 seconds attempting to connect to the first address and then if that fails up to 2 seconds trying the second address and so on The 10 second timeout still applies to the call as a whole so if the total time taken on timed out connection attempts exceeds 10 seconds the call will time out This kind of configuration is useful where calls may take a long time to com plete so call timeouts are long but a fast indication of connection failure is re quired 8 4 Server side behaviour The server side has two primary modes of operation thread per connection and thread pooling It is able to dynamically transition between the two modes and it supports a hybrid scheme that behaves mostly like thread pooling but has the same fast turn around for sequences of calls as thread per connection 8 4 1 Thread per connection mode In thread per connection mode the default and the only option in omniORB ver sions before 4 0 each connection has a single thread dedicated to it The thread blocks waiting for a request When it receives one it unmarshals the arguments makes the up call to the application code marshals the reply and goes back to watching the connection There is thus no thread switching along the call chain meaning the call is very efficient As explained above a client can choose to multiplex multiple concurrent calls on a single connection so once the server has received the
133. ted the object is contacted to ask if it is an A Case 2 C op1 and C op2 return a D This condition only occurs if the runtime of the remote end is buggy Line 6 completes and no exception is raised At line 7 the object is contacted to ask if it is an A If the answer is no a CORBA INV_OBJREF exception is raised At line 10 the narrow operation will fail and objA will be set to nil 76 CHAPTER 7 INTERFACE TYPE CHECKING Chapter 8 Connection and Thread Management This chapter describes how omniORB manages threads and network connections 8 1 Background In CORBA the ORB is the middleware that allows a client to invoke an operation on an object without regard to its implementation or location In order to invoke an operation on an object a client needs to bind to the object by acquiring its object reference Such a reference may be obtained as the result of an operation on another object such as a naming service or factory object or by conversion from a stringified representation If the object is in a different address space the binding process involves the ORB building a proxy object in the client s address space The ORB arranges for invocations on the proxy object to be transparently mapped to equivalent invocations on the implementation object For the sake of interoperability CORBA mandates that all ORBs should support IIOP as the means to communicate remote invocations over a TCP IP connecti
134. the mechanism described below to ensure type safety 7 2 Interface Inheritance When the ORB receives an IOR of interface type B when it expects the type to be A it must find out if B inherits from A When the ORB has no local knowledge of the type B it must work out the type of B dynamically The CORBA specification defines an Interface Repository IR from which IDL interfaces can be queried dynamically In the above situation the ORB could con tact the IR to find out the type of B However this approach assumes that an IR is always available and contains the up to date information of all the interfaces used in the domain This assumption may not be valid in many applications An alternative is to use the _is_a operation to work out the actual type of an object This approach is simpler and more robust than the previous one because no 3rd party is involved so this is what omniORB does class Object CORBA Boolean _is_a const char type_id hi The _is_a operation is part of the CORBA Object interface and must be implemented by every object The input argument is a Repold The function re turns true 1 if the object is really an instance of that type including if that type is a base type of the most derived type of that object In the situation above the ORB would invoke the _is_a operation on the object and ask if the object is of type A before it processes any application invocation on the object Notice that the _i
135. these arguments from the list so ap plication code does not have to deal with them If any error occurs during ORB initialisation such as invalid ORB arguments or an invalid configuration file the CORBA INITIALIZE system exception is raised 2 8 2 Obtaining the Root POA Lines 6 7 To activate our servant object and make it available to clients we must regis ter it with a POA In this example we use the Root POA rather than creating For backwards compatibility the ORB identifiers omniORB2 and omniORB3 are also accepted 2 8 EXAMPLE 1 COLOCATED CLIENT AND IMPLEMENTATION 15 any child POAs The Root POA is found with orb gt resolve_initial_ references which returns a plain CORBA Object In line 7 we nar row the reference to the right type for a POA A POA s behaviour is governed by its policies The Root POA has suitable policies for many simple servers and closely matches the policies used by omniORB 2 s BOA See Chapter 11 of the CORBA 2 6 specification OMG01 for details of all the POA policies which are available 2 8 3 Object initialisation Line 9 An instance of the Echo servant is initialised using the new operator Line 10 The servant object is activated in the Root POA using poa gt activate_ object which returns an object identifier of type PortableServer Ob jectId The object id must be passed back to various POA operations The caller is responsible for freeing
136. thin characters Therefore to listen just for IPv6 connections on all IPv6 interfaces use the somewhat cryptic GLOp Teepe Esas To listen for both IPv4 and IPv6 connections on Windows versions prior to Vista both endpoints must be explicitly provided 8 6 1 1 Link local addresses In IPv6 all network interfaces are assigned a link local address starting with the digits fe80 The link local address is only valid on the same link as the inter face meaning directly connected to the interface or possibly on the same subnet depending on how the network is switched To connect to a server s link local address a client has to know which of its network interfaces is on the same link as the server Since there is no way for omniORB to know which local interface a remote link local address may be connected to and in extreme circumstances may even end up contacting the wrong server if it picks the wrong interface link local addresses are not considered valid Servers do not publish link local addresses in their IORs 8 6 TRANSPORTS AND ENDPOINTS 85 8 6 2 Endpoint publishing For clients to be able to connect to a server the server publishes endpoint informa tion in its IORs Interoperable Object References Normally omniORB publishes the first available address for each of the endpoints it is listening on The endpoint information to publish is determined by the endPointPublish configuration parameter It contains a comma se
137. to omniidl it generates an extra template class for each interface This template class can be used to tie a C class to the skeleton class of the interface The source code in eg3_tieimp1 cc at the end of this chapter illustrates how the template class can be used The code is almost identical to eg3_impl cc with only a few changes Firstly the servant class Echo_i does not inherit from any stub classes This is the main benefit of using the template class because there are applications in which it is difficult to require every servant class to derive from CORBA classes Secondly the instantiation of a CORBA object now involves creating an in stance of the implementation class and an instance of the template Here is the relevant code fragment class Echo_i Echo_i myimpl new Echo_i POA_Echo_tie lt Echo_i gt myecho myimpl PortableServer ObjectId_var myechoid poa gt activate_object amp myecho For interface Echo the name of its tie implementation template is POA_Echo_ tie The template parameter is the servant class that contains an implementation of each of the operations defined in the interface As used above the tie template takes ownership of the Echo_i instance and deletes it when the tie object goes out of scope The tie constructor has an optional boolean argument defaulted to true which indicates whether or not it should delete the servant object For full details of using tie t
138. to omniidl are detailed in chapter 5 2 4 OBJECT REFERENCES AND SERVANTS 7 2 4 Object References and Servants We contact a CORBA object through an object reference The actual implementation of a CORBA object is termed a servant Object references and servants are quite separate entities and it is important not to confuse the two Client code deals purely with object references so there can be no confusion object implementation code must deal with both object refer ences and servants omniORB 4 uses distinct C types for object references and servants so the C compiler will complain if you use a servant when an object reference is expected or vice versa Warning omniORB 2 x did not use distinct types for object references and servants and often accepted a pointer to a servant when the CORBA specification says it should only accept an object reference If you have code which relies on this it will not compile with omniORB 3 x or 4 x even under the BOA compatibility mode 2 5 A Quick Tour of the C stubs The C stubs conform to the standard mapping defined in the CORBA specifica tion OMG03 It is important to understand the mapping before you start writing any serious CORBA applications Before going any further it is worth knowing what the mapping looks like For the example interface Echo the C mapping for its object reference is Echo_ptr The type is defined in echo hh The relevant section of the code is reproduc
139. ublished fol all addr lowed by all the addresses A specific endpoint can be published by giving its endpoint URI even if the server is not listening on that endpoint e g 86 CHAPTER 8 CONNECTION AND THREAD MANAGEMENT giop tcp not my host 12345 giop unix not my socket file If the host or port number for a TCP or SSL URI are missed out they are filled in with the details from each listening TCP SSL endpoint This can be used to publish a different name for a TCP SSL endpoint that is using an ephemeral port for example omniORB 4 0 supported two options related to endpoint publishing that are su perseded by the endPointPublish parameter and so are now deprecated Set ting endPointPublishAllIFs to 1 is equivalent to setting endPointPublish to all addr The endPointNoListen parameter is equivalent to adding end point URIs to the endPointPublish parameter 8 7 Connection selection and acceptance In the face of IORs containing details about multiple different endpoints clients have to know how to choose the one to use to connect a server Similarly servers may wish to restrict which clients can connect to particular transports This is achieved with transport rules 8 7 1 Client transport rules The clientTransportRule parameter is used to filter and prioritise the order in which transports specified in an IOR are tried Each rule has the form lt address mask gt action The address mask can be one of
140. vel CORBA Boolean traceExceptions CORBA Boolean traceInvocations CORBA Boolean traceInvocationReturns n n CORBA Boolean traceThreadld CORBA Boolean traceTime y Log messages can be sent somewhere other than stderr by registering a logging function which is called with the text of each log message namespace omniORB typedef void logFunction const char void setLogFunction logFunction f Y The log function must not make any CORBA calls since that could lead to infinite recursion as outputting a log message caused other log messages to be generated and so on 4 3 Miscellaneous global options These options control miscellaneous features that affect the whole ORB runtime dumpConfiguration default 0 If set true the ORB dumps the values of all configuration parameters at start up scanGranularity default 5 As explained in chapter 8 omniORB regularly scans incoming and outgoing con nections so it can close unused ones This value is the granularity in seconds at which the ORB performs its scans A value of zero turns off the scanning alto gether nativeCharCodeSet default ISO 8859 1 The native code set the application is using for char and string See chapter 9 nativeWCharCodeSet default UTF 16 The native code set the application is using for wchar and wst ring See chapter 9 4 4 CLIENT SIDE OPTIONS 49 copyValuesInLocalCalls default 1 Determines whether valuetype pa
141. xt typedef string StringName typedef string Address typedef string URLString StringName to_string in Name n raises InvalidName Name to_name in StringName sn raises InvalidName exception InvalidAddress URLString to_url in Address addr in StringName sn raises InvalidAddress InvalidName Object resolve_str in StringName n raises NotFound CannotProceed InvalidName AlreadyBound he hi to_string and to_name convert from CosNaming Name sequences to flattened strings and vice versa Note that calling these operations involves re mote calls to the naming service so they are not particularly efficient You can use the omniORB specific local omniURI nameToString and omniURI stringToName functions instead A CosNaming Name is stringified by separating name components with characters The kind and id fields of each component are separated by char acters If the kind field is empty the representation has no trailing if the id is empty the representation starts with a character if both id and kind are empty the representation is just a The backslash is used to escape the mean ing of and itself to_url1 takes a corbaloc style address and key string but without the corbaloc part and a stringified name and returns a corbaname URI incor rectly called a URL string having properly escaped any invalid characters Th
142. y static Echo_ptr myobj void installhandlers omniORB installTransientExceptionHandler 0 my_transient_handlerl All proxy objects will call my_transient_handlerl from now on omniORB installTransientExceptionHandler myobj 0 my_transient_handler2 The proxy object of myobj will call my_transient_handler2 from now on 4 7 3 CORBA COMM_FAILURE If the ORB has successfully contacted an object at some point and access to it sub sequently fails and the condition for TRANSIENT described above does not occur the ORB raises a CORBA COMM_FAILURE exception The default behaviour of the proxy objects is to propagate this exception to the application Applications can override the default behaviour by installing their own exception handlers The API to do so is summarised below typedef CORBA Boolean commFailureExceptionHandler_t void cookie CORBA ULong n_retries const CORBA COMM_FAILURE amp ex void installCommFailureExceptionHandler void cookie commFailureExceptionHandler_t fn void installCommFailureExceptionHandler CORBA Object_ptr obj void cookie commFailureExceptionHandler_t fn The functions are equivalent to their counterparts for CORBA TRANSIENT 4 7 4 CORBA SystemException If a system exceptions other than TRANSIENT or COMM_FAILURE occurs the de fault behaviour of the proxy objects is to propagate this exception to the a
143. y contains a long ZZ CFF CORBA Long 1 an_any gt gt l cout lt lt This is a long lt lt 1 lt lt endl The overloaded gt gt operator returns a CORBA Boolean If an attempt is made to extract a value from an Any when it contains a different type of value e g an attempt to extract a long from an Any containing a double the overloaded gt gt operator will return False otherwise it will return True Thus a common tactic to extract values from an Any is as follows C CORBA Long 1 CORBA Double d const char str if an_any gt gt 1 cout lt lt Long lt lt 1 lt lt endl else if an_any gt gt d cout lt lt Double lt lt d lt lt endl 11 1 EXAMPLE USING TYPE ANY 97 else if an_any gt gt str cout lt lt String lt lt str lt lt endl The storage of the extracted string is still owned by the any else cout lt lt Unknown value lt lt endl 11 1 3 Inserting and Extracting Constructed Types from an Any It is also possible to insert and extract constructed types and object references from an Any omniidl will generate insertion and extraction operators for the con structed type Note that it is necessary to specify the WBa command line flag when running omniidl in order to generate these operators The following exam ple illustrates the use of constructed types with type Any IDL struct testStruct long

The omniORB version 4.1 User's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents